OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Sessions and memory

QMD 記憶引擎

QMD 是一個本機優先的搜尋輔助服務，與 OpenClaw 並行運作。它將 BM25、向量搜尋和重新排序整合在單一 執行檔中，並且可以索引工作區記憶檔案以外的內容。

相較於內建引擎新增的功能

  • 重新排序與查詢擴展，以提高召回率。
  • 索引額外目錄 — 專案文件、團隊筆記，以及磁碟上的任何內容。
  • 索引工作階段逐字稿 — 回想先前的對話。
  • 完全在本機運作 — 使用官方 llama.cpp 提供者外掛執行，並 自動下載 GGUF 模型。
  • 自動備援 — 如果 QMD 無法使用，OpenClaw 會無縫切換回 內建引擎。

開始使用

必要條件

  • 安裝 QMD：npm install -g @tobilu/qmd 或 bun install -g @tobilu/qmd
  • 允許載入擴充功能的 SQLite 組建版本（macOS 上為 brew install sqlite）。
  • QMD 必須位於閘道的 PATH 中。
  • macOS 和 Linux 可直接使用。Windows 最適合透過 WSL2 使用。

啟用

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

OpenClaw 會在 ~/.openclaw/agents/<agentId>/qmd/ 下建立獨立完整的 QMD 主目錄，並自動管理輔助服務的生命週期 — 集合、更新和嵌入執行都會由系統處理。 它會優先採用目前的 QMD 集合與 MCP 查詢格式，但會在需要時切換至 替代的集合模式旗標和較舊的 MCP 工具名稱。 啟動時的協調程序也會將過時的受管理集合重新建立為其 標準模式，前提是仍存在名稱相同的舊版 QMD 集合。

輔助服務的運作方式

  • OpenClaw 會根據工作區記憶檔案及任何已設定的 memory.qmd.paths 建立集合，接著在 QMD 管理程式 開啟時及之後定期執行 qmd update（memory.qmd.update.interval，預設為 5m）。重新整理會透過 QMD 子程序執行，而非在程序內 掃描檔案系統。語意搜尋模式也會執行 qmd embed （memory.qmd.update.embedInterval，預設為 60m）。
  • 預設工作區集合會追蹤 MEMORY.md 與 memory/ 目錄樹。小寫的 memory.md 不會當作根記憶檔案建立索引。
  • QMD 自身的掃描器會忽略隱藏路徑，以及常見的相依套件／建置 目錄，例如 .git、.cache、node_modules、vendor、dist 和 build。閘道啟動時預設不會初始化 QMD （memory.qmd.update.startup 預設為 off），因此冷啟動時可避免 在首次使用記憶之前匯入記憶執行階段或建立長期運作的監看程式。
  • 若仍要在閘道啟動時初始化 QMD，請將 memory.qmd.update.startup 設為 idle 或 immediate。 memory.qmd.update.onBoot 預設為 true，並會在啟動時 執行初始重新整理；將其設為 false 可跳過此次 即時重新整理（設定更新或嵌入間隔後，長期運作的管理程式仍會開啟， 因此 QMD 會繼續負責其定期監看程式／計時器）。
  • 搜尋會使用已設定的 searchMode（預設：search；也支援 vsearch 和 query）。search 僅使用 BM25，因此在此模式下，OpenClaw 會略過語意 向量就緒探測和嵌入維護。如果某個模式失敗，OpenClaw 會改用 qmd query 重試。
  • 當 searchMode 為 query 時，將 memory.qmd.rerank 設為 false， 即可使用不含重新排序器的 QMD 混合查詢路徑（需要 QMD 2.1 或更新版本）。 OpenClaw 會將 --no-rerank 傳遞至直接 QMD 命令列介面路徑，並將 rerank: false 傳遞至 QMD 的 MCP 查詢工具。
  • 對於宣告支援多集合篩選器的 QMD 版本，OpenClaw 會將 來源相同的集合合併到一次 QMD 搜尋呼叫中。較舊的 QMD 版本 則會保留相容的逐集合備援方式。
  • 如果 QMD 完全失敗，OpenClaw 會切換回內建 SQLite 引擎。 開啟失敗後，重複的聊天回合嘗試會短暫退避，以免 缺少執行檔或輔助服務相依套件損壞造成重試風暴； openclaw memory status 和單次命令列介面探測仍會直接 重新檢查 QMD。

搜尋效能與相容性

OpenClaw 會讓 QMD 搜尋路徑同時相容於目前及較舊的 QMD 安裝版本。

啟動時，OpenClaw 會針對每個管理程式檢查一次已安裝 QMD 的說明文字。如果 執行檔宣告支援多個集合篩選器，OpenClaw 就會 使用一個命令搜尋所有來源相同的集合：

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

這可避免為每個持久記憶集合啟動一個 QMD 子程序。 工作階段逐字稿集合會保留在自己的來源群組中，因此混合 memory + sessions 搜尋仍能將兩種來源的結果提供給 結果多樣化器。

較舊的 QMD 組建版本只接受一個集合篩選器。當 OpenClaw 偵測到 這類組建版本時，會保留相容性路徑，分別搜尋每個集合， 再合併結果並移除重複項目。

若要手動檢查已安裝版本的合約，請執行：

bash
qmd --help | grep -i collection

目前的 QMD 說明會提及以一個或多個集合為目標。較舊的說明 通常只描述單一集合。

模型覆寫

QMD 模型環境變數會從閘道程序原封不動地傳遞，因此你可以 在不新增 OpenClaw 設定的情況下，全域調整 QMD：

bash
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"

變更嵌入模型後，請重新執行嵌入，讓索引符合新的 向量空間。

索引額外路徑

將 QMD 指向其他目錄，即可讓這些目錄的內容可供搜尋：

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

額外路徑的片段會在搜尋結果中顯示為 qmd/<collection>/<relative-path>。memory_get 能辨識此前綴，並從 正確的集合根目錄讀取內容。

索引工作階段逐字稿

啟用工作階段索引即可回想先前的對話。QMD 同時需要 一般的 memorySearch 工作階段來源和 QMD 逐字稿匯出器：

json5
{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },}

逐字稿會以經過清理的使用者／助理對話回合形式，匯出至 ~/.openclaw/agents/<id>/qmd/sessions/ 下的專用 QMD 集合。僅設定 memorySearch.experimental.sessionMemory 並不會將逐字稿匯出至 QMD。

工作階段命中結果仍會由 tools.sessions.visibility 篩選。預設的 tree 可見性不會公開同一代理程式中無關的工作階段。如果希望從另一個私訊工作階段 回想由閘道分派的工作階段，請有意識地設定 tools.sessions.visibility: "agent"。

搜尋範圍

預設情況下，QMD 搜尋結果只會顯示在直接工作階段中（不包含 群組或頻道聊天）。設定 memory.qmd.scope 可變更此行為：

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

上述片段就是實際的預設規則。當範圍規則拒絕搜尋時， OpenClaw 會記錄包含推導出的頻道和聊天類型的警告，讓 空白結果更容易偵錯。

引用

當 memory.citations 為 auto 或 on 時，搜尋片段會附加 Source: <path>#L<line>（或 #L<start>-L<end>）頁尾。在 auto 模式中，只有直接聊天工作階段會加入頁尾。將 memory.citations = "off" 設為省略頁尾，同時仍在內部將路徑傳遞給 代理程式。

適用情境

在需要以下功能時選擇 QMD：

  • 透過重新排序取得更高品質的結果。
  • 搜尋工作區外的專案文件或筆記。
  • 回想過去工作階段的對話。
  • 不需要 API 金鑰的完全本機搜尋。

對於較簡單的設定，內建引擎 無需額外相依套件 即可良好運作。

疑難排解

找不到 QMD？ 請確保執行檔位於閘道的 PATH 中。如果 OpenClaw 以服務形式執行，請建立符號連結： sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd。

如果 qmd --version 可在你的 Shell 中運作，但 OpenClaw 仍回報 spawn qmd ENOENT，則閘道程序的 PATH 很可能與 互動式 Shell 不同。請明確指定執行檔：

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

在安裝 QMD 的環境中使用 command -v qmd，然後以 openclaw memory status --deep 重新檢查。

第一次搜尋非常慢？ QMD 會在首次使用時下載 GGUF 模型。請使用 OpenClaw 所用的相同 XDG 目錄執行 qmd query "test" 來預熱。

搜尋期間出現許多 QMD 子程序？ 如有可能，請更新 QMD。只有在 已安裝的 QMD 宣告支援多個 -c 篩選器時，OpenClaw 才會使用單一程序執行來源相同的多集合搜尋；否則會 保留較舊的逐集合備援方式，以確保正確性。

僅使用 BM25 的 QMD 仍嘗試建置 llama.cpp？ 請設定 memory.qmd.searchMode = "search"。OpenClaw 會將該模式視為 僅限詞彙搜尋，略過 QMD 向量狀態探測和嵌入維護，並將 語意就緒檢查留給 vsearch 或 query 設定。

搜尋逾時？ 請增加 memory.qmd.limits.timeoutMs（預設：4000ms）。 對於速度較慢的硬體，請設定更高的值，例如 120000。此限制適用於 代理程式 memory_search 呼叫期間 QMD 自身的搜尋命令；設定、同步、 內建備援和補充語料庫作業會保留各自較短的期限。

群組或頻道聊天中的結果為空？ 在預設 memory.qmd.scope 下這是預期行為，因為它只允許直接工作階段。如果你希望 在這些位置顯示 QMD 結果，請為 group 或 channel 聊天類型新增 allow 規則。

根記憶搜尋範圍突然變得太廣？ 請重新啟動閘道，或等待 下一次啟動協調。偵測到同名衝突時，OpenClaw 會將過時的受管理 集合重新建立為標準的 MEMORY.md 和 memory/ 模式。

工作區可見的暫存儲存庫造成 ENAMETOOLONG 或索引損壞？ QMD 周遊會遵循底層 QMD 掃描器的行為，而非 OpenClaw 的 內建符號連結規則。在 QMD 提供 可安全處理循環的周遊或明確排除控制之前，請將暫存 monorepo 簽出放在 .tmp/ 等隱藏 目錄中，或置於已建立索引的 QMD 根目錄之外。

設定

如需完整設定介面（memory.qmd.*）、搜尋模式、更新間隔、 範圍規則及所有其他選項，請參閱 記憶設定參考。

相關內容

Was this useful?
On this page

On this page