为 OpenClaw 构建双层记忆系统：QMD + Mem0 混合架构

记忆分类策略

关键信息分层存储：

• 存储到 QMD（短期）：工作区内所有 .md 文件、项目上下文、临时信息。
• 存储到 Mem0（长期）：技术知识和经验、重要决策、用户偏好、有价值的问题解决方案。
• 双重存储：重要的调试经验、项目里程碑记录。

检索工作流

def search(query):
    # 第一层：QMD 快速搜索（<100ms）
    qmd_results = qmd_search(query)
    if qmd_results.score > 0.8:
        return qmd_results
    # 第二层：Mem0 语义搜索（<2s）
    mem0_results = memory_search(query)
    if mem0_results:
        return mem0_results
    # 第三层：生成新答案
    return generate_new_answer(query)

这种分层数据在不牺牲响应速度的前提下，获得了深度语义理解能力。

第三部分：自动化记忆维护系统

基于心跳的解决方案

Cron 任务依赖电脑持续开机，不适合个人开发场景。采用心跳机制，在用户活跃时检查是否需要执行任务。

核心逻辑：

def check_tasks():
    elapsed = now - last_execution
    # 超过 20 小时 → 触发每日任务
    if elapsed > 20 hours:
        return "execute_daily_tasks"
    # 超过 6 天 → 触发每周任务
    if elapsed > 6 days:
        return "execute_weekly_tasks"
    return "nothing_to_do"

优势包括适应非 24/7 开机、避免无谓轮询、状态持久化。

实现细节

创建了三个核心文件：

1. scripts/check-tasks.py：任务检查器核心逻辑，读取状态文件并判断执行。
2. memory/cron-state.json：任务状态追踪。

{
  "lastQMDUpdate": 1771815000000,
  "lastDailySummary": 1771815000000,
  "lastWeeklyMaintenance": 0
}

3. HEARTBEAT.md：配置心跳如何调用检查器。

第四部分：系统效果验证

性能指标

实际使用场景

• 场景 1：查找工作区文件 用户询问端口号，QMD 直接返回日志片段，延迟 <100ms。

• 场景 2：回忆技术知识 用户询问优化 Redis 缓存，QMD 无匹配，Mem0 返回存储的经验，延迟 <2s。

• 场景 3：混合检索 综合 QMD 日志片段与 Mem0 经验总结，延迟 <2.5s。

第五部分：技术细节与踩坑记录

1. Windows 环境编译 native 模块

问题： Could not locate the bindings file

解决： 安装 Visual Studio 2022 Community 和 Windows SDK，执行 npm rebuild。

2. QMD 向量嵌入生成卡住

现象： qmd embed 进度条停留在 "Gathering information"。

原因： CPU 模式下 embeddings 生成极慢，模型约 300MB。

决策： 跳过向量嵌入，仅使用 BM25 关键词搜索。对于本地个人使用场景，关键词搜索完全够用。

3. Cron Delivery 配置限制

错误： cron delivery config is only supported for sessionTarget="isolated"

修复： 主会话任务使用 systemEvent 类型，独立代理任务使用 agentTurn 类型。

4. 非 UTF-8 环境下的 Python 脚本

错误： UnicodeEncodeError: 'gbk' codec can't encode character

修复： 移除 emoji 打印，确保所有汉字字符串显式指定编码。

第六部分：项目文件清单

核心文档

• MEMORY-ARCHITECTURE.md - 详细架构设计
• MEMORY-QUICKSTART.md - 快速使用指南
• AGENTS.md - 已更新，添加双层记忆体系

自动化脚本

• scripts/check-tasks.py - 任务检查器
• scripts/memory-assistant.py - 记忆助手（预留）

配置文件

• memory/cron-state.json - 任务状态追踪
• HEARTBEAT.md - 心跳配置

经验总结

技术的价值在于解决实际问题，而不是追求完美的理论架构。

最初计划做完美的向量嵌入系统，但 CPU 模式下太慢不可用。BM25 已能满足 90% 的场景。真正需要的是自动化维护，而不是完美的算法。

有时，'够用'比'完美'更重要。双层混合架构不是最优雅的设计，但在实际使用中确实有效。

下一步计划包括测试混合检索效果、建立典型使用场景库、探索 GPU 加速集成。