---
read_when:
    - 你想將 QMD 設定為記憶後端
    - 你想要重新排序或額外索引路徑等進階記憶功能
summary: 本機優先的搜尋輔助服務，支援 BM25、向量、重新排序與查詢擴展
title: QMD 記憶引擎
x-i18n:
    generated_at: "2026-07-14T13:34:19Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 25
    provider: openai
    source_hash: b13017ead7e7340624a35e603a18216a5c23405cbab09e7f53b1e15d74d59d23
    source_path: concepts/memory-qmd.md
    workflow: 16
---

[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
{
  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。

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

## 搜尋效能與相容性

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`](/zh-TW/gateway/config-tools#toolssessions) 篩選。預設的
`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 金鑰的完全本機搜尋。

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

## 疑難排解

**找不到 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.*`）、搜尋模式、更新間隔、
範圍規則及所有其他選項，請參閱
[記憶設定參考](/zh-TW/reference/memory-config)。

## 相關內容

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