OpenClaw 长期记忆系统深度解析：Markdown 文件、向量搜索与 QMD 后端

OpenClaw 的记忆系统设计独特：纯 Markdown 文件是唯一的事实来源，AI 只「记得」写到磁盘上的内容。本文深度解析 OpenClaw 记忆架构的每一层。

核心设计哲学#

OpenClaw 记忆 = 工作区中的纯 Markdown 文件。文件是事实来源；模型只「记得」写到磁盘上的内容。

这个设计的好处：

• 完全透明：你能直接读取和编辑所有记忆
• 可移植：记忆文件就是普通 Markdown，可以备份、同步、版本控制
• 安全隔离：MEMORY.md 只在私信会话加载，不泄露到群组

两层记忆架构#

第一层：每日日志（增量追加）#

• 增量追加：只写入，不修改历史
• 自动加载：每次会话启动时读取今天和昨天的日志
• 用途：当天的工作记录、对话摘要、临时笔记

第二层：长期记忆（精选汇总）#

• 只在主私信会话加载，不在群组中加载（安全设计）
• 精选内容：从每日日志中提炼值得长期保留的洞见
• 用途：重要决策、用户偏好、持久的背景信息

两个记忆工具#

memory_search — 语义搜索#

即使措辞不同，也能找到相关笔记。

memory_get — 精确读取#

如果文件不存在（例如今天还没有日志），返回空文本而不是报错——Agent 可以无缝处理「还没有记录」的情况。

何时写入记忆#

官方指导：

• 决策、偏好、持久事实 → 写入 MEMORY.md
• 日常笔记、工作上下文 → 写入 memory/YYYY-MM-DD.md
• 有人说「记住这个」 → 立即写入文件（不要只是「脑子里记一下」）
• 想让某件事持续有效 → 明确要求 Agent 写入记忆

自动记忆刷新（Pre-Compaction Ping）#

OpenClaw 有一个关键机制：当会话接近自动压缩时，会触发一次静默的 Agentic 轮次，提醒 Agent 在上下文被压缩前保存持久记忆。

{
  "agents": {
    "defaults": {
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "systemPrompt": "Session nearing compaction. Store durable memories now.",
          "prompt": "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store."
        }
      }
    }
  }
}

触发条件：contextWindow - reserveTokensFloor - softThresholdTokens 被超过时触发。

注意：如果沙箱设置了 workspaceAccess: "ro" 或 "none"，刷新会被跳过（无法写文件）。

向量记忆搜索#

默认开启向量索引，让语义搜索更准确：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "remote": {
          "model": "text-embedding-3-small"
        }
      }
    }
  }
}

嵌入提供商自动选择顺序：

1. 本地模型（如果配置了 modelPath 且文件存在）
2. OpenAI（如果有 API Key）
3. Gemini（GEMINI_API_KEY）
4. Voyage（VOYAGE_API_KEY）
5. Mistral（MISTRAL_API_KEY）
6. 都没有则禁用向量搜索

混合搜索：BM25 + 向量#

memory_search 使用混合搜索策略：

• BM25：关键词精确匹配（快速、可靠）
• 向量搜索：语义相似度（找措辞不同但意思相近的笔记）
• MMR 重排序：最大边际相关性，增加结果多样性，避免冗余
• 时间衰减：最近的笔记得分更高（近期记忆更重要）

QMD 后端（实验性）#

对于需要更强大搜索的用户，可以切换到 QMD（本地优先搜索引擎）：

{
  "memory": {
    "backend": "qmd"
  }
}

需要先安装 QMD：

bun install -g https://github.com/tobi/qmd

QMD 的优势：

• 完全本地运行（BM25 + 向量 + 重排序）
• 自动下载 GGUF 模型（无需 Ollama）
• 可以额外索引会话记录（memory.qmd.sessions.enabled = true）

QMD 不可用时，OpenClaw 自动回退到内置 SQLite 管理器。

扩展记忆路径#

添加工作区以外的目录进行索引：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "additionalPaths": [
          { "path": "~/notes", "pattern": "*.md" },
          { "path": "~/projects/shared-context" }
        ]
      }
    }
  }
}

原文：Memory - OpenClaw | 来源：OpenClaw 官方文档