> ## 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.

# 記憶體設定參考

此頁列出 OpenClaw 記憶搜尋的每一個設定旋鈕。概念性總覽請參閱：

<CardGroup cols={2}>
  <Card title="記憶總覽" href="/zh-TW/concepts/memory">
    記憶如何運作。
  </Card>

  <Card title="內建引擎" href="/zh-TW/concepts/memory-builtin">
    預設 SQLite 後端。
  </Card>

  <Card title="QMD 引擎" href="/zh-TW/concepts/memory-qmd">
    本機優先的 sidecar。
  </Card>

  <Card title="記憶搜尋" href="/zh-TW/concepts/memory-search">
    搜尋管線與調校。
  </Card>

  <Card title="主動記憶" href="/zh-TW/concepts/active-memory">
    互動式工作階段的記憶子代理。
  </Card>
</CardGroup>

除非另有註明，所有記憶搜尋設定都位於 `openclaw.json` 的 `agents.defaults.memorySearch` 下（或個別代理的 `agents.list[].memorySearch` 覆寫）。

<Note>
  如果你正在尋找 **主動記憶** 功能切換與子代理設定，它位於 `plugins.entries.active-memory` 下，而不是 `memorySearch`。

  主動記憶使用雙重閘門模型：

  1. 外掛必須已啟用，並以目前代理 id 為目標
  2. 請求必須是符合資格的互動式持久聊天工作階段

  請參閱[主動記憶](/zh-TW/concepts/active-memory)，了解啟用模型、外掛擁有的設定、逐字稿持久化，以及安全推出模式。
</Note>

***

## 提供者選擇

| 鍵          | 類型        | 預設值        | 說明                                                                                                                                                                                                 |
| ---------- | --------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`  | `boolean` | `true`     | 啟用或停用記憶搜尋                                                                                                                                                                                          |
| `provider` | `string`  | `"openai"` | 嵌入配接器 ID，例如 `bedrock`、`deepinfra`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai`、`openai-compatible` 或 `voyage`；也可以是已設定的 `models.providers.<id>`，其 `api` 指向記憶嵌入配接器或 OpenAI 相容模型 API |
| `model`    | `string`  | 提供者預設值     | 嵌入模型名稱                                                                                                                                                                                             |
| `fallback` | `string`  | `"none"`   | 主要項目失敗時的備援配接器 ID                                                                                                                                                                                   |

未設定 `provider` 時，OpenClaw 會使用 OpenAI 嵌入。明確設定 `provider`
即可使用 Bedrock、DeepInfra、Gemini、GitHub Copilot、Mistral、Ollama、
Voyage、本機 GGUF 模型，或 OpenAI 相容的 `/v1/embeddings` 端點。
仍寫著 `provider: "auto"` 的舊版設定會解析為 `openai`。

<Warning>
  變更嵌入提供者、模型、提供者設定、來源、範圍、
  分塊或 tokenizer 可能會讓現有的 SQLite 向量索引不相容。
  OpenClaw 會暫停向量搜尋並回報索引身分警告，而不是
  自動重新嵌入所有內容。準備好後，請使用
  `openclaw memory status --index --agent <id>` 或
  `openclaw memory index --force --agent <id>` 重建。
</Warning>

當 `provider` 未設定、存在舊版 `provider: "auto"`，或
`provider: "none"` 刻意選擇僅 FTS 模式時，若嵌入無法使用，記憶召回仍可
使用詞彙 FTS 排名。

明確的非本機提供者會失敗關閉。如果你將 `memorySearch.provider` 設為
具體的遠端支援提供者，例如 Bedrock、DeepInfra、Gemini、GitHub
Copilot、LM Studio、Mistral、Ollama、OpenAI、Voyage，或 OpenAI 相容的
自訂提供者，而該提供者在執行階段無法使用，`memory_search`
會傳回不可用結果，而不是靜默使用僅 FTS 召回。請修正
提供者/驗證設定、切換到可連線的提供者，或在你想刻意使用僅 FTS 召回時設定
`provider: "none"`。

### 自訂提供者 id

`memorySearch.provider` 可以指向自訂 `models.providers.<id>` 項目，用於記憶專用提供者配接器（例如 `ollama`），或用於 OpenAI 相容模型 API（例如 `openai-responses` / `openai-completions`）。OpenClaw 會解析該提供者的 `api` 擁有者以取得嵌入配接器，同時保留自訂提供者 id 以處理端點、驗證和模型前綴。這讓多 GPU 或多主機設定能將記憶嵌入指定到特定本機端點：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b", name: "Qwen3 Embedding 0.6B" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}
```

### API 金鑰解析

遠端嵌入需要 API 金鑰。Bedrock 則使用 AWS SDK 預設憑證鏈（執行個體角色、SSO、存取金鑰或 Bedrock API 金鑰）。

| 提供者            | 環境變數                                             | 設定鍵                                 |
| -------------- | ------------------------------------------------ | ----------------------------------- |
| Bedrock        | AWS 憑證鏈，或 `AWS_BEARER_TOKEN_BEDROCK`             | 不需要 API 金鑰                          |
| DeepInfra      | `DEEPINFRA_API_KEY`                              | `models.providers.deepinfra.apiKey` |
| Gemini         | `GEMINI_API_KEY`                                 | `models.providers.google.apiKey`    |
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`、`GH_TOKEN`、`GITHUB_TOKEN` | 透過裝置登入的驗證設定檔                        |
| Mistral        | `MISTRAL_API_KEY`                                | `models.providers.mistral.apiKey`   |
| Ollama         | `OLLAMA_API_KEY`（預留位置）                           | --                                  |
| OpenAI         | `OPENAI_API_KEY`                                 | `models.providers.openai.apiKey`    |
| Voyage         | `VOYAGE_API_KEY`                                 | `models.providers.voyage.apiKey`    |

<Note>
  Codex OAuth 僅涵蓋聊天/補全，不滿足嵌入請求。
</Note>

***

## 遠端端點設定

對於不應繼承全域 OpenAI 聊天憑證的通用 OpenAI 相容
`/v1/embeddings` 伺服器，請使用 `provider: "openai-compatible"`。

<ParamField path="remote.baseUrl" type="string">
  自訂 API 基底 URL。
</ParamField>

<ParamField path="remote.apiKey" type="string">
  覆寫 API 金鑰。
</ParamField>

<ParamField path="remote.headers" type="object">
  額外 HTTP 標頭（與提供者預設值合併）。
</ParamField>

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai-compatible",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}
```

***

## 提供者特定設定

<AccordionGroup>
  <Accordion title="Gemini">
    | 鍵                      | 類型       | 預設值                    | 說明                               |
    | ---------------------- | -------- | ---------------------- | -------------------------------- |
    | `model`                | `string` | `gemini-embedding-001` | 也支援 `gemini-embedding-2-preview` |
    | `outputDimensionality` | `number` | `3072`                 | 用於 Embedding 2：768、1536 或 3072   |

    <Warning>
      變更模型或 `outputDimensionality` 會改變索引身分。OpenClaw
      會暫停向量搜尋，直到你明確重建記憶索引。
    </Warning>
  </Accordion>

  <Accordion title="OpenAI 相容輸入類型">
    OpenAI 相容嵌入端點可以選擇使用提供者特定的 `input_type` 請求欄位。這對需要針對查詢與文件嵌入使用不同標籤的非對稱嵌入模型很有用。

    | 鍵                   | 類型       | 預設值 | 說明                                |
    | ------------------- | -------- | --- | --------------------------------- |
    | `inputType`         | `string` | 未設定 | 查詢與文件嵌入共用的 `input_type`           |
    | `queryInputType`    | `string` | 未設定 | 查詢時的 `input_type`；覆寫 `inputType`  |
    | `documentInputType` | `string` | 未設定 | 索引/文件 `input_type`；覆寫 `inputType` |

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          memorySearch: {
            provider: "openai-compatible",
            remote: {
              baseUrl: "https://embeddings.example/v1",
              apiKey: "${EMBEDDINGS_API_KEY}",
            },
            model: "asymmetric-embedder",
            queryInputType: "query",
            documentInputType: "passage",
          },
        },
      },
    }
    ```

    變更這些值會影響提供者批次索引的嵌入快取身分；當上游模型以不同方式處理標籤時，之後應重新索引記憶。
  </Accordion>

  <Accordion title="Bedrock">
    ### Bedrock 嵌入設定

    Bedrock 使用 AWS SDK 預設憑證鏈加上 OpenClaw 檢查的 bearer token，因此設定中不會儲存 API 金鑰。如果 OpenClaw 在 EC2 上執行，且執行個體角色已啟用 Bedrock，只要設定提供者與模型即可：

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          memorySearch: {
            provider: "bedrock",
            model: "amazon.titan-embed-text-v2:0",
          },
        },
      },
    }
    ```

    | 鍵                      | 類型       | 預設值                            | 說明                         |
    | ---------------------- | -------- | ------------------------------ | -------------------------- |
    | `model`                | `string` | `amazon.titan-embed-text-v2:0` | 任何 Bedrock 嵌入模型 ID         |
    | `outputDimensionality` | `number` | 模型預設值                          | 用於 Titan V2：256、512 或 1024 |

    **支援的模型**（含系列偵測與維度預設值）：

    | 模型 ID                                      | 提供者        | 預設維度 | 可設定維度                          |
    | ------------------------------------------ | ---------- | ---- | ------------------------------ |
    | `amazon.titan-embed-text-v2:0`             | Amazon     | 1024 | 256, 512, 1024                 |
    | `amazon.titan-embed-text-v1`               | Amazon     | 1536 | --                             |
    | `amazon.titan-embed-g1-text-02`            | Amazon     | 1536 | --                             |
    | `amazon.titan-embed-image-v1`              | Amazon     | 1024 | --                             |
    | `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon     | 1024 | 256, 384, 1024, 3072           |
    | `cohere.embed-english-v3`                  | Cohere     | 1024 | --                             |
    | `cohere.embed-multilingual-v3`             | Cohere     | 1024 | --                             |
    | `cohere.embed-v4:0`                        | Cohere     | 1536 | 256, 384, 512, 768, 1024, 1536 |
    | `twelvelabs.marengo-embed-3-0-v1:0`        | TwelveLabs | 512  | --                             |
    | `twelvelabs.marengo-embed-2-7-v1:0`        | TwelveLabs | 1024 | --                             |

    帶有輸送量後綴的變體（例如 `amazon.titan-embed-text-v1:2:8k`）與帶有區域前綴的推論設定檔 ID（例如 `us.amazon.titan-embed-text-v2:0`）會繼承基礎模型的設定。

    **區域：** 依此順序解析：`memorySearch.remote.baseUrl` 覆寫值、`models.providers.amazon-bedrock.baseUrl` 設定、`AWS_REGION`、`AWS_DEFAULT_REGION`，最後預設為 `us-east-1`。

    **驗證：** OpenClaw 會先檢查 `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` 或 `AWS_BEARER_TOKEN_BEDROCK`，然後退回標準 AWS SDK 預設憑證提供者鏈：

    1. 環境變數（`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`），除非同時設定了 `AWS_PROFILE`
    2. SSO（僅在已設定 SSO 欄位時）
    3. 共用憑證與設定檔（`fromIni`，包含 `AWS_PROFILE`）
    4. 憑證程序（AWS 設定檔中的 `credential_process`）
    5. Web 身分權杖憑證
    6. ECS 或 EC2 執行個體中繼資料憑證

    **IAM 權限：** IAM 角色或使用者需要：

    ```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      "Effect": "Allow",
      "Action": "bedrock:InvokeModel",
      "Resource": "*"
    }
    ```

    若要採用最低權限，請將 `InvokeModel` 範圍限定到特定模型：

    ```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
    arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
    ```
  </Accordion>

  <Accordion title="Local (GGUF + llama.cpp)">
    | 鍵                     | 類型                 | 預設值                | 說明                                                                                                                                                                 |
    | --------------------- | ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `local.modelPath`     | `string`           | 自動下載               | GGUF 模型檔案的路徑                                                                                                                                                       |
    | `local.modelCacheDir` | `string`           | node-llama-cpp 預設值 | 已下載模型的快取目錄                                                                                                                                                         |
    | `local.contextSize`   | `number \| "auto"` | `4096`             | 嵌入情境的情境視窗大小。4096 可涵蓋典型區塊（128-512 個權杖），同時限制非權重 VRAM。受限主機可降低至 1024-2048。`"auto"` 會使用模型訓練時的最大值 -- 不建議用於 8B+ 模型（Qwen3-Embedding-8B：最高 40 960 個權杖可能會將 VRAM 推高到約 32 GB）。 |

    請先安裝官方 llama.cpp 提供者：`openclaw plugins install @openclaw/llama-cpp-provider`。
    預設模型：`embeddinggemma-300m-qat-Q8_0.gguf`（約 0.6 GB，自動下載）。原始碼 checkout 仍需要原生建置核准：先執行 `pnpm approve-builds`，再執行 `pnpm rebuild node-llama-cpp`。

    使用獨立命令列介面驗證閘道使用的相同提供者路徑：

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw memory status --deep --agent main
    openclaw memory index --force --agent main
    ```

    若要使用本機 GGUF 嵌入，請明確設定 `provider: "local"`。明確的本機設定支援 `hf:` 與 HTTP(S) 模型參照（透過 node-llama-cpp 的模型解析），但它們不會變更預設提供者。
  </Accordion>
</AccordionGroup>

### 內嵌嵌入逾時

<ParamField path="sync.embeddingBatchTimeoutSeconds" type="number">
  覆寫記憶索引期間內嵌嵌入批次的逾時。

  未設定時會使用提供者預設值：`local`、`ollama`、`lmstudio` 等本機/自架提供者為 600 秒，託管提供者為 120 秒。當本機 CPU-bound 嵌入批次健康但緩慢時，請增加此值。
</ParamField>

***

## 索引行為

除非另有註明，全部位於 `memorySearch.sync` 之下：

| 鍵                              | 類型        | 預設值    | 說明                           |
| ------------------------------ | --------- | ------ | ---------------------------- |
| `onSessionStart`               | `boolean` | `true` | 工作階段開始時同步記憶索引                |
| `onSearch`                     | `boolean` | `true` | 偵測到內容變更後，在搜尋時延遲同步            |
| `watch`                        | `boolean` | `true` | 監看記憶檔案（chokidar），並在變更時排程重新索引 |
| `watchDebounceMs`              | `number`  | `1500` | 合併快速檔案監看事件的防抖視窗              |
| `intervalMinutes`              | `number`  | `0`    | 週期性重新索引間隔（分鐘）（`0` 會停用）       |
| `sessions.postCompactionForce` | `boolean` | `true` | 在壓縮觸發的逐字稿更新後強制重新索引工作階段       |

<ParamField path="chunking.tokens" type="number">
  在嵌入前分割記憶來源時使用的區塊大小（以權杖計，預設值：400）。
</ParamField>

<ParamField path="chunking.overlap" type="number">
  相鄰區塊之間的權杖重疊，用來保留分割邊界附近的情境（預設值：80）。
</ParamField>

<Note>
  變更 `chunking.tokens` 或 `chunking.overlap` 會改變區塊邊界，並使現有索引身分失效（請參閱「提供者選擇」下方的警告）。
</Note>

***

## 混合搜尋設定

全部位於 `memorySearch.query` 之下：

| 鍵            | 類型       | 預設值    | 說明            |
| ------------ | -------- | ------ | ------------- |
| `maxResults` | `number` | `6`    | 注入前傳回的最大記憶命中數 |
| `minScore`   | `number` | `0.35` | 納入命中的最低相關性分數  |

以及 `memorySearch.query.hybrid` 之下：

| 鍵                     | 類型        | 預設值    | 說明               |
| --------------------- | --------- | ------ | ---------------- |
| `enabled`             | `boolean` | `true` | 啟用混合 BM25 + 向量搜尋 |
| `vectorWeight`        | `number`  | `0.7`  | 向量分數的權重（0-1）     |
| `textWeight`          | `number`  | `0.3`  | BM25 分數的權重（0-1）  |
| `candidateMultiplier` | `number`  | `4`    | 候選池大小乘數          |

<Tabs>
  <Tab title="MMR (diversity)">
    | 鍵             | 類型        | 預設值     | 說明                  |
    | ------------- | --------- | ------- | ------------------- |
    | `mmr.enabled` | `boolean` | `false` | 啟用 MMR 重新排序         |
    | `mmr.lambda`  | `number`  | `0.7`   | 0 = 最大多樣性，1 = 最大相關性 |
  </Tab>

  <Tab title="Temporal decay (recency)">
    | 鍵                            | 類型        | 預設值     | 說明        |
    | ---------------------------- | --------- | ------- | --------- |
    | `temporalDecay.enabled`      | `boolean` | `false` | 啟用近期性加權   |
    | `temporalDecay.halfLifeDays` | `number`  | `30`    | 分數每 N 天減半 |

    常青檔案（`MEMORY.md`、`memory/` 中非日期命名的檔案）永不衰減。
  </Tab>
</Tabs>

### 完整範例

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          maxResults: 6,
          minScore: 0.35,
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}
```

***

## 額外記憶路徑

| 鍵            | 類型         | 說明          |
| ------------ | ---------- | ----------- |
| `extraPaths` | `string[]` | 要索引的其他目錄或檔案 |

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  agents: {
    defaults: {
      memorySearch: {
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
    },
  },
}
```

路徑可以是絕對路徑或相對於工作區的路徑。目錄會遞迴掃描 `.md` 檔案。符號連結處理取決於作用中的後端：內建引擎會略過符號連結，而 QMD 會遵循底層 QMD 掃描器行為。

若要進行代理程式範圍的跨代理程式逐字稿搜尋，請使用 `agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。這些額外集合遵循相同的 `{ path, name, pattern? }` 形狀，但會按每個代理程式合併，且當路徑指向目前工作區之外時，可以保留明確的共用名稱。如果同一個已解析路徑同時出現在 `memory.qmd.paths` 和 `memorySearch.qmd.extraCollections` 中，QMD 會保留第一個項目並略過重複項目。

***

## 多模態記憶（Gemini）

使用 Gemini Embedding 2 索引影像與音訊，並與 Markdown 一併索引：

| 鍵                         | 類型         | 預設值        | 說明                                  |
| ------------------------- | ---------- | ---------- | ----------------------------------- |
| `multimodal.enabled`      | `boolean`  | `false`    | 啟用多模態索引                             |
| `multimodal.modalities`   | `string[]` | --         | `["image"]`、`["audio"]` 或 `["all"]` |
| `multimodal.maxFileBytes` | `number`   | `10485760` | 索引的最大檔案大小（10 MiB）                   |

<Note>
  僅適用於 `extraPaths` 中的檔案。預設記憶根目錄仍僅限 Markdown。需要 `gemini-embedding-2-preview`。`fallback` 必須是 `"none"`。
</Note>

支援格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`（影像）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音訊）。

***

## 嵌入快取

| Key                | Type      | Default | Description        |
| ------------------ | --------- | ------- | ------------------ |
| `cache.enabled`    | `boolean` | `true`  | 在 SQLite 中快取區塊嵌入向量 |
| `cache.maxEntries` | `number`  | 未設定     | 快取嵌入向量的盡力上限        |

避免在重新索引或逐字稿更新期間，對未變更的文字重新產生嵌入向量。若要使用無上限快取，請讓 `maxEntries` 保持未設定；當磁碟成長比重新索引峰值速度更重要時，請設定它。設定後，一旦快取超過限制，最舊的項目（依最後更新時間）會先被修剪。

***

## 批次索引

| Key                           | Type      | Default | Description |
| ----------------------------- | --------- | ------- | ----------- |
| `remote.nonBatchConcurrency`  | `number`  | `4`     | 平行內嵌嵌入向量    |
| `remote.batch.enabled`        | `boolean` | `false` | 啟用批次嵌入 API  |
| `remote.batch.concurrency`    | `number`  | `2`     | 平行批次工作      |
| `remote.batch.wait`           | `boolean` | `true`  | 等待批次完成      |
| `remote.batch.pollIntervalMs` | `number`  | `2000`  | 輪詢間隔        |
| `remote.batch.timeoutMinutes` | `number`  | `60`    | 批次逾時        |

適用於 `gemini`、`openai` 和 `voyage`。對大型回填而言，OpenAI 批次通常最快且成本最低。

`remote.nonBatchConcurrency` 控制本機/自託管提供者，以及未啟用提供者批次 API 時託管提供者所使用的內嵌嵌入呼叫。Ollama 針對非批次索引預設為 `1`，以避免壓垮較小的本機主機；在較大的機器上可設定更高的值。

這與 `sync.embeddingBatchTimeoutSeconds` 分開，後者控制內嵌嵌入呼叫的逾時。

***

## 工作階段記憶搜尋（實驗性）

索引工作階段逐字稿，並透過 `memory_search` 顯示：

| Key                           | Type       | Default      | Description            |
| ----------------------------- | ---------- | ------------ | ---------------------- |
| `experimental.sessionMemory`  | `boolean`  | `false`      | 啟用工作階段索引               |
| `sources`                     | `string[]` | `["memory"]` | 加入 `"sessions"` 以包含逐字稿 |
| `sync.sessions.deltaBytes`    | `number`   | `100000`     | 重新索引的位元組閾值             |
| `sync.sessions.deltaMessages` | `number`   | `50`         | 重新索引的訊息閾值              |

<Warning>
  工作階段索引為選擇性啟用，且會非同步執行。結果可能略為過時。工作階段記錄會保存在磁碟上，因此請將檔案系統存取視為信任邊界。
</Warning>

工作階段逐字稿命中也會遵循
[`tools.sessions.visibility`](/zh-TW/gateway/config-tools#toolssessions)。預設
`tree` 可見性只會公開目前工作階段及其產生的工作階段。若要從不同
工作階段（例如 DM）回想無關但同一代理程式由閘道派送的工作階段，
請有意將可見性擴大為 `agent`（或只有在也需要跨代理程式回想且代理程式對代理程式政策允許時才使用 `all`）。

以下範例會將這些設定放在 `agents.defaults` 底下。你也可以
在個別代理程式覆寫中套用等效的 `memorySearch` 設定，當只有一個
代理程式需要索引和搜尋工作階段逐字稿時使用。

對於同一代理程式的閘道到 DM 回想：

<Tabs>
  <Tab title="內建後端">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          memorySearch: {
            experimental: { sessionMemory: true },
            sources: ["memory", "sessions"],
          },
        },
      },
      tools: {
        sessions: { visibility: "agent" },
      },
    }
    ```
  </Tab>

  <Tab title="QMD 後端">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          memorySearch: {
            experimental: { sessionMemory: true },
            sources: ["memory", "sessions"],
          },
        },
      },
      memory: {
        backend: "qmd",
        qmd: {
          sessions: { enabled: true },
        },
      },
      tools: {
        sessions: { visibility: "agent" },
      },
    }
    ```
  </Tab>
</Tabs>

使用 QMD 時，`agents.defaults.memorySearch.experimental.sessionMemory` 和
`sources: ["sessions"]` 本身不會將逐字稿匯出到 QMD。也請設定
`memory.qmd.sessions.enabled: true`。

***

## SQLite 向量加速 (sqlite-vec)

| Key                          | Type      | Default | Description          |
| ---------------------------- | --------- | ------- | -------------------- |
| `store.vector.enabled`       | `boolean` | `true`  | 使用 sqlite-vec 進行向量查詢 |
| `store.vector.extensionPath` | `string`  | 隨附      | 覆寫 sqlite-vec 路徑     |

當 sqlite-vec 無法使用時，OpenClaw 會自動退回使用程序內的餘弦相似度。

***

## 索引儲存

內建記憶索引位於每個代理的 OpenClaw SQLite 資料庫：
`agents/<agentId>/agent/openclaw-agent.sqlite`。

| 鍵                     | 類型       | 預設值         | 說明                                      |
| --------------------- | -------- | ----------- | --------------------------------------- |
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 tokenizer（`unicode61` 或 `trigram`） |

***

## QMD 後端設定

設定 `memory.backend = "qmd"` 以啟用。所有 QMD 設定位於 `memory.qmd` 底下：

| 鍵                        | 類型        | 預設值      | 說明                                                          |
| ------------------------ | --------- | -------- | ----------------------------------------------------------- |
| `command`                | `string`  | `qmd`    | QMD 可執行檔路徑；當服務的 `PATH` 與你的 shell 不同時，請設定絕對路徑                |
| `searchMode`             | `string`  | `search` | 搜尋命令：`search`、`vsearch`、`query`                             |
| `rerank`                 | `boolean` | --       | 搭配 `searchMode: "query"` 和 QMD 2.1+ 設為 `false`，可略過 QMD 重新排序 |
| `includeDefaultMemory`   | `boolean` | `true`   | 自動索引 `MEMORY.md` + `memory/**/*.md`                         |
| `paths[]`                | `array`   | --       | 額外路徑：`{ name, path, pattern? }`                             |
| `sessions.enabled`       | `boolean` | `false`  | 將工作階段逐字稿匯出到 QMD                                             |
| `sessions.retentionDays` | `number`  | --       | 逐字稿保留期限                                                     |
| `sessions.exportDir`     | `string`  | --       | 匯出目錄                                                        |

`searchMode: "search"` 僅限詞彙/BM25。OpenClaw 不會針對該模式執行語意向量就緒探測或 QMD embedding 維護，包括在 `memory status --deep` 期間；`vsearch` 和 `query` 仍會要求 QMD 向量就緒與 embeddings。

`rerank: false` 只會變更 QMD `query` 模式，且需要 QMD 2.1 或更新版本。在直接命令列介面模式中，OpenClaw 會傳遞 `--no-rerank`；在 mcporter 支援的 MCP 模式中，則會將 `rerank: false` 傳給 QMD 的統一查詢工具。保持未設定即可使用 QMD 預設的查詢重新排序行為。

OpenClaw 偏好目前的 QMD collection 和 MCP 查詢形狀，但會在需要時嘗試相容的 collection pattern 旗標和較舊的 MCP 工具名稱，讓較舊的 QMD 發行版仍可運作。當 QMD 宣告支援多個 collection 篩選器時，來自相同來源的 collections 會以一個 QMD 程序搜尋；較舊的 QMD 組建會保留每個 collection 的相容路徑。相同來源是指持久記憶 collections（預設記憶檔案加上自訂路徑）會分組在一起，而工作階段逐字稿 collections 會維持為另一個獨立群組，因此來源多樣化仍然同時具備兩種輸入。

<Note>
  QMD 模型覆寫會留在 QMD 端，而不是 OpenClaw 設定。如果你需要全域覆寫 QMD 的模型，請在閘道執行階段環境中設定環境變數，例如 `QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。
</Note>

### mcporter 整合

全部位於 `memory.qmd.mcporter` 底下。透過長時間執行的 `mcporter` MCP daemon 路由 QMD 搜尋，而不是每次查詢都產生 `qmd`，以降低較大型模型的冷啟動開銷。

| 鍵             | 類型        | 預設值     | 說明                                                        |
| ------------- | --------- | ------- | --------------------------------------------------------- |
| `enabled`     | `boolean` | `false` | 透過 mcporter 路由 QMD 呼叫，而不是每次請求都產生 `qmd`                    |
| `serverName`  | `string`  | `qmd`   | 執行 `qmd mcp` 且帶有 `lifecycle: keep-alive` 的 mcporter 伺服器名稱 |
| `startDaemon` | `boolean` | `true`  | 當 `enabled` 為 true 時，自動啟動 mcporter daemon                 |

需要已安裝 `mcporter` 並位於 PATH 上，並且已設定會執行 `qmd mcp` 的 mcporter 伺服器。對於每次查詢產生程序成本可接受的較簡單本機設定，請保持停用。

<AccordionGroup>
  <Accordion title="更新排程">
    | 鍵                         | 類型        | 預設值      | 說明                                         |
    | ------------------------- | --------- | -------- | ------------------------------------------ |
    | `update.interval`         | `string`  | `5m`     | 重新整理間隔                                     |
    | `update.debounceMs`       | `number`  | `15000`  | 對檔案變更進行 debounce                           |
    | `update.onBoot`           | `boolean` | `true`   | 長時間執行的 QMD 管理器開啟時重新整理；設為 false 可略過立即開機更新   |
    | `update.startup`          | `string`  | `off`    | 選用的閘道啟動 QMD 初始化：`off`、`idle` 或 `immediate` |
    | `update.startupDelayMs`   | `number`  | `120000` | 在 `startup: "idle"` 重新整理執行前延遲              |
    | `update.waitForBootSync`  | `boolean` | `false`  | 阻擋管理器開啟，直到其初始重新整理完成                        |
    | `update.embedInterval`    | `string`  | `60m`    | 個別 embedding 節奏                            |
    | `update.commandTimeoutMs` | `number`  | `30000`  | QMD 維護命令逾時（collection list/add）            |
    | `update.updateTimeoutMs`  | `number`  | `120000` | 每個 `qmd update` 週期的逾時                      |
    | `update.embedTimeoutMs`   | `number`  | `120000` | 每個 `qmd embed` 週期的逾時                       |
  </Accordion>

  <Accordion title="限制">
    | 鍵                         | 類型       | 預設值    | 說明       |
    | ------------------------- | -------- | ------ | -------- |
    | `limits.maxResults`       | `number` | `4`    | 最大搜尋結果數  |
    | `limits.maxSnippetChars`  | `number` | `450`  | 限制片段長度   |
    | `limits.maxInjectedChars` | `number` | `2200` | 限制總注入字元數 |
    | `limits.timeoutMs`        | `number` | `4000` | 搜尋逾時     |
  </Accordion>

  <Accordion title="範圍">
    控制哪些工作階段可以接收 QMD 搜尋結果。結構描述與 [`session.sendPolicy`](/zh-TW/gateway/config-agents#session) 相同：

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      memory: {
        qmd: {
          scope: {
            default: "deny",
            rules: [{ action: "allow", match: { chatType: "direct" } }],
          },
        },
      },
    }
    ```

    隨附的預設值是僅限 DM/直接訊息，拒絕群組和其他頻道類型。`match.keyPrefix` 會比對正規化的工作階段鍵；`match.rawKeyPrefix` 會比對包含 `agent:<id>:` 的原始鍵。
  </Accordion>

  <Accordion title="引用">
    `memory.citations` 適用於所有後端：

    | 值          | 行為                              |
    | ---------- | ------------------------------- |
    | `auto`（預設） | 在片段中包含 `Source: <path#line>` 頁尾 |
    | `on`       | 一律包含頁尾                          |
    | `off`      | 省略頁尾（路徑仍會在內部傳遞給代理）              |
  </Accordion>
</AccordionGroup>

啟用 gateway-start QMD 初始化時，OpenClaw 只會為符合資格的代理啟動 QMD。如果 `update.onBoot` 為 true，且未設定 interval/embed 維護，啟動時會使用一次性管理器進行開機重新整理，然後關閉它。如果設定了更新或 embed 間隔，啟動時會開啟長駐 QMD 管理器，讓它負責 watcher 和間隔計時器；`update.onBoot: false` 只會略過立即的開機重新整理。

### 完整 QMD 範例

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  memory: {
    backend: "qmd",
    citations: "auto",
    qmd: {
      includeDefaultMemory: true,
      update: { interval: "5m", debounceMs: 15000 },
      limits: { maxResults: 4, timeoutMs: 4000 },
      scope: {
        default: "deny",
        rules: [{ action: "allow", match: { chatType: "direct" } }],
      },
      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
    },
  },
}
```

***

## 夢境整理

夢境整理是在 `plugins.entries.memory-core.config.dreaming` 下設定，而不是在 `agents.defaults.memorySearch` 下。

夢境整理會以一次排程掃描執行，並將內部的 light/deep/REM 階段作為實作細節。

如需概念行為和斜線命令，請參閱[夢境整理](/zh-TW/concepts/dreaming)。

### 使用者設定

| 鍵                                      | 類型        | 預設值         | 說明                                                      |
| -------------------------------------- | --------- | ----------- | ------------------------------------------------------- |
| `enabled`                              | `boolean` | `false`     | 完整啟用或停用夢境整理                                             |
| `frequency`                            | `string`  | `0 3 * * *` | 完整夢境整理掃描的可選排程節奏                                         |
| `model`                                | `string`  | 預設模型        | 可選的 Dream Diary 子代理模型覆寫                                 |
| `phases.deep.maxPromotedSnippetTokens` | `number`  | `160`       | 從每個提升至 `MEMORY.md` 的短期回想片段中保留的最大估計 token 數；來源中繼資料仍會保持可見 |

### 範例

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    entries: {
      "memory-core": {
        subagent: {
          allowModelOverride: true,
          allowedModels: ["anthropic/claude-sonnet-4-6"],
        },
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *",
            model: "anthropic/claude-sonnet-4-6",
          },
        },
      },
    },
  },
}
```

<Note>
  * 夢境整理會將機器狀態寫入 `memory/.dreams/`。
  * 夢境整理會將人類可讀的敘事輸出寫入 `DREAMS.md`（或現有的 `dreams.md`）。
  * `dreaming.model` 使用現有外掛子代理信任閘門；啟用前請先設定 `plugins.entries.memory-core.subagent.allowModelOverride: true`。
  * 設定的模型不可用時，Dream Diary 會使用工作階段預設模型重試一次。信任或允許清單失敗會被記錄，且不會靜默重試。
  * light/deep/REM 階段策略與臨界值是內部行為，不是面向使用者的設定。
</Note>

## 相關

* [設定參考](/zh-TW/gateway/configuration-reference)
* [記憶概覽](/zh-TW/concepts/memory)
* [記憶搜尋](/zh-TW/concepts/memory-search)