QMD 记忆引擎

​

相较于内置引擎的增强功能

• 重排序和查询扩展，提高召回率。
• 为额外目录建立索引 — 项目文档、团队笔记以及磁盘上的任何内容。
• 为会话记录建立索引 — 回忆较早的对话。
• 完全本地运行 — 使用官方 llama.cpp provider 插件运行，并 自动下载 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 根据工作区记忆文件和配置的 memory.qmd.paths 创建集合。QMD 适配器负责更新、嵌入、防抖和 超时启发式策略；这些不是用户配置项。
• QMD 继续负责其 index.sqlite、YAML 集合配置以及每个 Agent 的 QMD 主目录下的模型下载；这些是外部工具工件， 并非 OpenClaw 状态表。OpenClaw 所有的协调仅存在于 SQLite 中： 一个共享租约限制跨 Agent 的嵌入工作，而每个 Agent 数据库中的一个租约会串行化该 Agent 的集合、更新和嵌入写入。 运行时不再创建 QMD 文件锁边车。openclaw doctor --fix 仅在确认其旧进程所有者已失效后，才会移除退役的边车。 升级采用完全切换方式：使用新版本前，停止并重新启动共享该状态目录的 所有 OpenClaw 进程。不支持新旧 QMD 写入器混用；运行时有意不对 已退役的边车执行双重加锁。
• 默认工作区集合会跟踪 MEMORY.md 以及 memory/ 目录树。小写的 memory.md 不会作为根记忆文件建立索引。
• QMD 自身的扫描器会忽略隐藏路径，以及常见的依赖项/构建 目录，例如 .git、.cache、node_modules、vendor、dist 和 build。Gateway 网关启动时会保持 QMD 延迟加载；管理器会在首次使用记忆时 初始化。
• 搜索使用配置的 searchMode（默认值：search；还支持 vsearch 和 query）。search 仅使用 BM25，因此 OpenClaw 在该模式下会跳过语义 向量就绪性探测和嵌入维护。如果某个模式 失败，OpenClaw 会使用 qmd query 重试。
• 当 searchMode 为 query 时，将 memory.qmd.rerank 设置为 false，即可使用 QMD 不含重排序器的混合查询路径（需要 QMD 2.1 或更高版本）。 OpenClaw 会向直接 QMD CLI 路径传递 --no-rerank， 并向 QMD 的 MCP 查询工具传递 rerank: false。
• 对于声明支持多集合过滤器的 QMD 版本，OpenClaw 会将 相同来源的集合分组到一次 QMD 搜索调用中。较旧的 QMD 版本 会保留兼容的逐集合回退路径。
• 如果 QMD 完全失败，OpenClaw 会回退到内置 SQLite 引擎。 打开失败后，重复的聊天轮次尝试会短暂退避，避免 二进制文件缺失或边车依赖项损坏造成重试风暴； openclaw memory status 和一次性 CLI 探测仍会直接重新检查 QMD。

​

搜索性能和兼容性

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

qmd --help | grep -i collection

​

模型覆盖设置

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"

​

为额外路径建立索引

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

​

为会话记录建立索引

{
  memory: {
    backend: "qmd",
    search: {
      experimental: { sessionMemory: true },
      sources: ["memory", "sessions"],
    },
    qmd: {
      sessions: { enabled: true },
    },
  },
}

​

搜索范围

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

​

引用

​

适用场景

• 通过重排序获得更高质量的结果。
• 搜索工作区之外的项目文档或笔记。
• 回忆过去的会话对话。
• 无需 API 密钥的完全本地搜索。

​

故障排查

{
  memory: {
    backend: "qmd",
    qmd: {
      command: "/absolute/path/to/qmd",
    },
  },
}

​

配置

​

相关内容

• 记忆概览
• 内置记忆引擎
• Honcho 记忆