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 會繼續管理每個代理程式 QMD 主目錄下的 index.sqlite、YAML 集合設定及模型 下載；這些是外部工具成品， 並非 OpenClaw 狀態資料表。OpenClaw 擁有的協調資料僅位於 SQLite： 一個共用租約會限制代理程式之間的嵌入工作，而每個 代理程式資料庫中的一個租約，則會將該代理程式的集合、更新及嵌入寫入作業序列化。 執行階段不再建立 QMD 檔案鎖定輔助檔。openclaw doctor --fix 只會在證實舊程序擁有者已失效後，移除已淘汰的輔助檔。 升級採用完全切換：在使用新版本之前，請停止並重新啟動所有 共用該狀態目錄的 OpenClaw 程序。不支援新舊版本混用的 QMD 寫入程式；執行階段刻意不會對已淘汰的 輔助檔進行雙重鎖定。
  • 預設工作區集合會追蹤 MEMORY.md 及 memory/ 目錄樹。小寫的 memory.md 不會以根記憶檔案的形式建立索引。
  • QMD 自身的掃描器會忽略隱藏路徑及常見的相依套件／建置 目錄，例如 .git、.cache、node_modules、vendor、dist 和 build。閘道啟動時會讓 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 模型環境變數會從閘道 程序原封不動地傳遞，因此你可以全域調整 QMD，而不必新增 OpenClaw 設定：

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 同時需要 一般的 memory.search 工作階段來源及 QMD 逐字稿匯出器：

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

逐字稿會以經過清理的使用者／助理對話回合匯出至 ~/.openclaw/agents/<id>/qmd/sessions/ 下的專用 QMD 集合。只設定 sources: ["sessions"] 不會將逐字稿匯出至 QMD；還必須啟用 rememberAcrossConversations 或明確的 QMD 工作階段匯出功能。

工作階段命中結果仍會由 tools.sessions.visibility 篩選。預設的 tree 可見性包含目前工作階段、由其產生的工作階段， 以及透過環境群組感知所監看、屬於同一代理程式的群組工作階段。使用 session.dmScope: "main" 時，多使用者私訊設定中的使用者會共用主要 工作階段，並可回想其所監看群組中的內容。若要隔離私訊，請使用每個對等方各自的 dmScope，或將可見性設為 "self"，以停用環境監看工作階段的讀取。 其他無關但屬於同一代理程式的工作階段仍需要 "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 可在你的殼層中運作，但 OpenClaw 仍回報 spawn qmd ENOENT，閘道程序的 PATH 可能與 你的互動式殼層不同。請明確固定二進位檔路徑：

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

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

首次搜尋非常慢？ QMD 會在首次使用時下載 GGUF 模型。請使用 qmd query "test" 並搭配 OpenClaw 使用的相同 XDG 目錄預先暖機。

搜尋期間出現許多 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 提供 循環安全的走訪或明確排除控制之前，請將暫存單一儲存庫簽出目錄放在 .tmp/ 等隱藏 目錄下，或放在已建立索引的 QMD 根目錄之外。

設定

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

相關內容

Was this useful?
On this page

On this page