Skip to main content

​
QMD 记忆引擎

QMD 是一个本地优先的搜索 sidecar，与 OpenClaw 一同运行。它将 BM25、向量搜索和重排序整合到单个二进制文件中，并且可以索引超出你的工作区记忆文件范围的内容。

​
相比内置功能增加了什么

  • 重排序和查询扩展，以获得更好的召回效果。
  • 索引额外目录 —— 项目文档、团队笔记、磁盘上的任何内容。
  • 索引会话转录 —— 回忆更早的对话。
  • 完全本地运行 —— 通过 Bun + node-llama-cpp 运行，自动下载 GGUF 模型。
  • 自动回退 —— 如果 QMD 不可用，OpenClaw 会无缝回退到内置引擎。

​
入门指南

​
前提条件

  • 安装 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 主目录，并自动管理 sidecar 的生命周期 —— collection、更新和 embedding 运行都会由它为你处理。它会优先使用当前的 QMD collection 和 MCP 查询形态，但在需要时仍会回退到旧版的 --mask collection 标志和更早的 MCP 工具名称。

​
sidecar 的工作方式

  • OpenClaw 会根据你的工作区记忆文件和任何已配置的 memory.qmd.paths 创建 collection，然后在启动时和定期（默认每 5 分钟）运行 qmd update + qmd embed。
  • 启动时刷新会在后台运行，因此不会阻塞聊天启动。
  • 搜索会使用已配置的 searchMode（默认：search；也支持 vsearch 和 query）。如果某种模式失败，OpenClaw 会使用 qmd query 重试。
  • 如果 QMD 完全失败，OpenClaw 会回退到内置的 SQLite 引擎。
首次搜索可能较慢 —— QMD 会在第一次运行 qmd query 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。

​
模型覆盖

QMD 的模型环境变量会从 Gateway 网关进程原样透传，因此你可以全局调整 QMD，而无需添加新的 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 模型后，请重新运行 embeddings，以确保索引与新的向量空间匹配。

​
为额外路径建立索引

将 QMD 指向其他目录，使其内容可被搜索： 
{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}
来自额外路径的片段会在搜索结果中显示为 qmd/<collection>/<relative-path>。memory_get 能识别此前缀，并从正确的 collection 根目录读取内容。

​
为会话转录建立索引

启用会话索引以回忆更早的对话： 
{
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}
转录内容会被导出为经过清理的用户/助手轮次，并存入 ~/.openclaw/agents/<id>/qmd/sessions/ 下的专用 QMD collection。

​
搜索范围

默认情况下，QMD 搜索结果只会在私信会话中显示（不包括群组或渠道）。配置 memory.qmd.scope 可更改此行为： 
{
  memory: {
    qmd: {
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
    },
  },
}
当范围规则拒绝某次搜索时，OpenClaw 会记录一条警告日志，其中包含推导出的渠道和聊天类型，以便更容易调试空结果问题。

​
引用

当 memory.citations 为 auto 或 on 时，搜索片段会包含一个 Source: <path#line> 页脚。将 memory.citations = "off" 可省略该页脚，同时仍会在内部将路径传递给智能体。

​
何时使用

当你需要以下能力时，请选择 QMD：
  • 通过重排序获得更高质量的结果。
  • 搜索工作区之外的项目文档或笔记。
  • 回忆过去的会话对话。
  • 完全本地搜索且无需 API 密钥。
对于更简单的设置，内置引擎 也能很好地工作，并且无需额外依赖。

​
故障排除

找不到 QMD？ 请确保该二进制文件位于 Gateway 网关的 PATH 中。如果 OpenClaw 作为服务运行，请创建一个符号链接： sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd。 首次搜索非常慢？ QMD 会在首次使用时下载 GGUF 模型。你可以使用与 OpenClaw 相同的 XDG 目录运行 qmd query "test" 来预热。 搜索超时？ 增加 memory.qmd.limits.timeoutMs（默认：4000ms）。对于较慢的硬件，可设置为 120000。 群聊中结果为空？ 检查 memory.qmd.scope —— 默认仅允许私信会话。 工作区可见的临时仓库导致 ENAMETOOLONG 或索引损坏？ QMD 遍历当前遵循底层 QMD 扫描器的行为，而不是 OpenClaw 内置的符号链接规则。在 QMD 提供具备循环安全的遍历或显式排除控制之前，请将临时 monorepo 检出保存在 .tmp/ 之类的隐藏目录中，或放在已索引 QMD 根目录之外。

​
配置

要查看完整的配置范围（memory.qmd.*）、搜索模式、更新间隔、范围规则及其他所有可调项，请参阅 记忆配置参考。