QMD 記憶引擎

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

相較於內建功能新增了什麼

• 重新排序與查詢擴展，以提升召回率。
• 索引額外目錄 — 專案文件、團隊筆記、磁碟上的任何內容。
• 索引工作階段轉錄 — 召回較早的對話。
• 完全本機執行 — 使用選用的 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",
  },
}

​

sidecar 的運作方式

• OpenClaw 會從你的工作區記憶檔案與任何已設定的 memory.qmd.paths 建立 collections，接著在 QMD manager 開啟時執行 qmd update，並於之後定期執行（預設每 5 分鐘一次）。這些重新整理會透過 QMD 子程序執行，而不是在程序內爬取檔案系統。語意模式也會執行 qmd embed。
• 預設工作區 collection 會追蹤 MEMORY.md 加上 memory/ 樹狀目錄。小寫的 memory.md 不會被索引為根記憶檔案。
• QMD 自己的掃描器會忽略隱藏路徑，以及常見的相依性/建置目錄，例如 .git、.cache、node_modules、vendor、dist 與 build。Gateway 啟動時預設不會初始化 QMD，因此冷啟動可避免在首次使用記憶之前匯入記憶執行階段或建立長時間存活的 watcher。
• 如果你仍想要 Gateway 啟動時重新整理，請將 memory.qmd.update.startup 設為 idle 或 immediate。選擇加入的啟動重新整理會使用一次性的 QMD 子程序路徑，而不是建立完整、長時間存活的程序內 watcher。
• 搜尋會使用已設定的 searchMode（預設：search；也支援 vsearch 與 query）。search 只使用 BM25，因此 OpenClaw 會在該模式中略過語意向量就緒探測與嵌入維護。如果某個模式失敗，OpenClaw 會用 qmd query 重試。
• 對於宣告支援多 collection 篩選器的 QMD 版本，OpenClaw 會將相同來源的 collections 分組到一次 QMD 搜尋呼叫中。較舊的 QMD 版本會保留相容的逐 collection 備援。
• 如果 QMD 完全失敗，OpenClaw 會退回內建 SQLite 引擎。重複的聊天回合嘗試會在開啟失敗後短暫退避，因此缺少二進位檔或損壞的 sidecar 相依性不會造成重試風暴；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",
    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 記憶