> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# QMD 記憶引擎

[QMD](https://github.com/tobi/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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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。

<Info>
  首次搜尋可能較慢 — QMD 會在第一次執行 `qmd query` 時，自動下載用於
  重新排序與查詢擴展的 GGUF 模型（約 2 GB）。
</Info>

## 搜尋效能與相容性

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

啟動時，OpenClaw 會為每個管理器檢查一次已安裝 QMD 的說明文字。如果
二進位檔宣告支援多個集合篩選器，OpenClaw
會以單一命令搜尋所有來源相同的集合：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main
```

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
qmd --help | grep -i collection
```

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

## 覆寫模型

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  memory: {
    backend: "qmd",
    qmd: {
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}
```

額外路徑的摘要片段會以 `qmd/<collection>/<relative-path>` 的形式出現在
搜尋結果中。`memory_get` 能識別此前置字串，並從
正確的集合根目錄讀取內容。

## 為工作階段逐字稿建立索引

啟用工作階段索引以回想先前的對話。QMD 同時需要
一般的 `memory.search` 工作階段來源及 QMD 逐字稿匯出器：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`](/zh-TW/gateway/config-tools#toolssessions) 篩選。預設的
`tree` 可見性包含目前工作階段、由其產生的工作階段，
以及透過環境群組感知所監看、屬於同一代理程式的群組工作階段。使用
`session.dmScope: "main"` 時，多使用者私訊設定中的使用者會共用主要
工作階段，並可回想其所監看群組中的內容。若要隔離私訊，請使用每個對等方各自的
`dmScope`，或將可見性設為 `"self"`，以停用環境監看工作階段的讀取。
其他無關但屬於同一代理程式的工作階段仍需要
`"agent"` 可見性。

## 搜尋範圍

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 金鑰、完全在本機執行的搜尋。

對於較簡單的設定，[內建引擎](/zh-TW/concepts/memory-builtin) 不需額外相依套件
即可良好運作。

## 疑難排解

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

如果 `qmd --version` 可在你的殼層中運作，但 OpenClaw 仍回報
`spawn qmd ENOENT`，閘道程序的 `PATH` 可能與
你的互動式殼層不同。請明確固定二進位檔路徑：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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.*`）、搜尋模式、更新間隔、
範圍規則及所有其他選項，請參閱
[記憶設定參考](/zh-TW/reference/memory-config)。

## 相關內容

* [記憶概觀](/zh-TW/concepts/memory)
* [內建記憶引擎](/zh-TW/concepts/memory-builtin)
* [Honcho 記憶](/zh-TW/concepts/memory-honcho)