OpenClaw 记忆系统深度解析：双层 Markdown 记忆、向量搜索与 QMD 实验后端

OpenClaw 的记忆系统是整个 Agent 持续性的基础。与大多数 AI 系统「上下文即记忆」的做法不同，OpenClaw 的记忆是磁盘上的 Markdown 文件——模型只能「记住」写到磁盘上的内容。

「记忆文件是唯一的真相来源；模型只会记住被写入磁盘的内容。」

双层记忆架构#

第一层：每日日志（memory/YYYY-MM-DD.md）#

• 追加模式：只往里加，不删除
• 自动加载：每次会话开始时，读取今天和昨天的日志
• 用途：当天发生的事、临时上下文、运行中的笔记

第二层：长期记忆（MEMORY.md）#

• 精选模式：重要决策、持久偏好、关键事实
• 安全限制：⚠️ 只在私人主会话中加载，群组上下文中永远不加载（防止个人信息泄露）
• 用途：跨会话保持一致的用户偏好、项目背景、重要决定

两个文件都位于 Agent 工作区下（默认 ~/.openclaw/workspace）。

记忆工具#

OpenClaw 为 Agent 提供两个记忆工具：

memory_get 现在支持优雅降级：如果文件不存在（比如今天的日志还没有第一条记录），返回 { text: "", path } 而不是报错，Agent 可以无缝处理「还没有记录」的情况。

何时写记忆#

官方原则很简单：

• 决策、偏好、持久事实 → MEMORY.md
• 日常笔记、临时上下文 → memory/YYYY-MM-DD.md
• 有人说「记住这个」→ 立刻写到文件，不要只放在 RAM 里
• 如果你想让某件事持续存在，告诉 Bot 写下来

自动记忆刷新（压缩前 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."
        }
      }
    }
  }
}

工作机制：

• 当会话 Token 数超过 contextWindow - reserveTokensFloor - softThresholdTokens 时触发
• 默认静默（Prompt 包含 NO_REPLY，用户看不到这次轮次）
• 每次压缩周期只触发一次
• 工作区必须可写（沙箱只读模式下跳过）

向量记忆搜索#

OpenClaw 默认为 MEMORY.md 和 memory/*.md 构建向量索引，支持语义搜索——即使措辞完全不同，也能找到相关笔记。

嵌入模型自动选择顺序#

1. 本地模型（如配置了 memorySearch.local.modelPath）
2. OpenAI（如有 API Key）
3. Gemini（如有 API Key）
4. Voyage
5. Mistral
6. 都没有 → 记忆搜索保持禁用，直到配置

配置示例#

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",
        "model": "text-embedding-3-small",
        "extraPaths": ["../team-docs", "/srv/shared-notes/overview.md"]
      }
    }
  }
}

extraPaths 支持索引工作区以外的 Markdown 文件，方便团队共享知识库。

QMD 实验性后端#

QMD 是一个完全本地的搜索引擎，比默认的 SQLite 索引更强大：

优势：

• BM25 关键词搜索 + 向量搜索 + 重排序
• 全本地运行（Bun + node-llama-cpp，自动从 HuggingFace 下载 GGUF 模型）
• 无需 Ollama 等独立守护进程

启用方式：

{
  "memory": {
    "backend": "qmd",
    "citations": "auto",
    "qmd": {
      "includeDefaultMemory": true,
      "update": { "interval": "5m", "debounceMs": 15000 },
      "limits": { "maxResults": 6, "timeoutMs": 4000 },
      "paths": [
        { "name": "docs", "path": "~/notes", "pattern": "**/*.md" }
      ]
    }
  }
}

安装步骤：

# 安装 QMD CLI
bun install -g https://github.com/tobi/qmd

# macOS 需要 Homebrew 版 SQLite
brew install sqlite

注意：第一次搜索可能较慢，QMD 会自动下载本地 GGUF 模型（重排序器/查询扩展）。

会话搜索（实验性）#

开启 memory.qmd.sessions.enabled = true 后，OpenClaw 会将历史会话记录导出到 QMD 集合，memory_search 可以搜索以往对话内容，不仅限于 Markdown 文件。

混合搜索架构（BM25 + 向量）#

为什么要混合？#

混合搜索取两者之长：语义理解 + 精确匹配。

结果处理流水线#

1. BM25 + 向量搜索 并行运行
2. RRF 融合（倒数排名融合）合并两路结果
3. MMR 重排序（最大边际相关性）：在相关性和多样性之间取平衡，避免返回大量重复内容
4. 时间衰减：最近写入的笔记权重更高

实用建议#

让记忆真正有用#

何时用 memory_search vs memory_get#

• 不确定在哪里：用 memory_search（语义搜索）
• 知道具体文件和行号：用 memory_get（精确读取，省 Token）

引用格式#

设置 memory.citations = "auto" 后，搜索结果会附上 Source: <路径#行号> 的来源标注，方便追溯。

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