本页介绍 OpenClaw 的 QMD 记忆引擎：一个本地优先的搜索 sidecar，集成 BM25、向量搜索和重排序。支持索引 workspace 外的额外目录和历史会话记录，QMD 不可用时自动回退到内置引擎。

QMD 记忆引擎

QMD 是运行在 OpenClaw 旁边的本地优先搜索 sidecar，将 BM25、向量搜索和重排序集成在一个二进制文件中，还能索引 workspace memory 文件以外的内容。

比内置引擎多了什么

• 重排序和查询扩展：更高质量的召回
• 索引额外目录：项目文档、团队笔记，磁盘上任意位置
• 索引会话记录：召回历史对话
• 完全本地：通过 Bun + node-llama-cpp 运行，自动下载 GGUF 模型
• 自动回退：QMD 不可用时，无缝回退到内置引擎

快速开始

前置条件

• 安装 QMD：npm install -g @tobilu/qmd 或 bun install -g @tobilu/qmd
• 支持扩展的 SQLite（macOS 用 brew install sqlite）
• QMD 必须在 gateway 的 PATH 中
• macOS 和 Linux 开箱即用。Windows 建议通过 WSL2 使用

启用

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

OpenClaw 会在 ~/.openclaw/agents/<agentId>/qmd/ 下创建独立的 QMD home 目录，自动管理 sidecar 生命周期（集合创建、更新、embedding 运行）。

Sidecar 工作原理

• OpenClaw 从 workspace memory 文件和配置的 memory.qmd.paths 创建集合，在启动和定期（默认每 5 分钟）运行 qmd update + qmd embed
• 启动时刷新在后台进行，不阻塞聊天启动
• 搜索使用配置的 searchMode（默认 search；也支持 vsearch 和 query）。某个模式失败时自动用 qmd query 重试
• QMD 完全失败时，回退到内置 SQLite 引擎

第一次搜索可能较慢——QMD 会在首次 qmd query 时自动下载 GGUF 模型（约 2 GB）用于重排序和查询扩展。

模型覆盖

QMD 模型环境变量直接从 gateway 进程透传，无需新增 OpenClaw 配置即可全局调整：

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"

更换 embedding 模型后，需重新运行 embedding 以使索引与新向量空间匹配。

索引额外路径

将 QMD 指向其他目录，使其可被搜索：

{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}

额外路径的搜索结果以 qmd/<collection>/<relative-path> 形式出现。memory_get 理解这个前缀，会从正确的集合根路径读取。

索引会话记录

启用会话索引，召回历史对话：

{
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}

会话记录以 User/Assistant 对话轮次导出到 ~/.openclaw/agents/<id>/qmd/sessions/ 下的专属 QMD 集合。

搜索范围

默认情况下，QMD 搜索结果只在私信（DM）会话中显示，不在群组或频道中显示。通过 memory.qmd.scope 配置：

{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}

scope 拒绝搜索时，OpenClaw 会记录警告并附上推导出的 channel 和 chat type，方便调试空结果。

引用来源

memory.citations 设为 auto 或 on 时，搜索片段包含 Source: <path#line> 页脚。设为 "off" 可隐藏页脚（内部仍将路径传给 agent）。

适用场景

选择 QMD 的情形：

• 需要重排序以获得更高质量的结果
• 需要搜索 workspace 外的项目文档或笔记
• 需要召回历史会话
• 需要完全本地搜索且不需要 API key

更简单的场景，内置引擎无需额外依赖即可运行。

排查

QMD 找不到？ 确保二进制在 gateway 的 PATH 中。作为服务运行时：sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd

第一次搜索很慢？ QMD 首次使用时下载 GGUF 模型，可用 qmd query "test" 预热（使用 OpenClaw 相同的 XDG 目录）

搜索超时？ 增大 memory.qmd.limits.timeoutMs（默认 4000ms），慢硬件设为 120000

群聊没有结果？ 检查 memory.qmd.scope——默认只允许 DM 会话

临时仓库导致 ENAMETOOLONG 或索引异常？ 将临时 monorepo 放在 .tmp/ 之类的隐藏目录，或移到 QMD 索引根之外

常见问题

Q: QMD 与内置引擎可以同时运行吗？

A: 不行，两者是互斥的 backend 配置。切换到 QMD 后，内置引擎作为回退保底，但不会同时运行。

Q: Windows 能用 QMD 吗？

A: 建议通过 WSL2 使用。原生 Windows 路径对 QMD 的 SQLite 扩展支持不完整。

Q: 如何只为某个 agent 启用 QMD？

A: 在 agents.list[<agentId>] 下配置 memory.backend: "qmd"，其他 agent 仍使用内置引擎。

配置参考

完整配置（memory.qmd.*、搜索模式、更新间隔、scope 规则等）请参考Memory 配置参考。