記憶設定參考

此頁面列出 OpenClaw 記憶搜尋的所有設定旋鈕。如需概念性概覽，請參閱：

除非另有註明，所有記憶搜尋設定都位於 openclaw.json 的 agents.defaults.memorySearch 下。

# Provider 選擇

# 自動偵測順序

未設定 provider 時，OpenClaw 會選擇第一個可用項目：

支援 ollama，但不會自動偵測（請明確設定）。

# 自訂 provider ID

memorySearch.provider 可以指向自訂 models.providers.<id> 項目。OpenClaw 會解析該 provider 的 api 擁有者以用於嵌入轉接器，同時保留自訂 provider ID 以處理端點、驗證和模型前綴。這讓多 GPU 或多主機設定可以將記憶嵌入專用於特定本機端點：

{
  models: {
    providers: {
      "ollama-5080": {
        api: "ollama",
        baseUrl: "http://gpu-box.local:11435",
        apiKey: "ollama-local",
        models: [{ id: "qwen3-embedding:0.6b" }],
      },
    },
  },
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama-5080",
        model: "qwen3-embedding:0.6b",
      },
    },
  },
}

# API key 解析

遠端嵌入需要 API key。Bedrock 則改用 AWS SDK 預設憑證鏈（instance roles、SSO、access keys）。

# 遠端端點設定

用於自訂 OpenAI 相容端點，或覆寫 provider 預設值：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
        remote: {
          baseUrl: "https://api.example.com/v1/",
          apiKey: "YOUR_KEY",
        },
      },
    },
  },
}

# Provider 專用設定

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        remote: {
          baseUrl: "https://embeddings.example/v1",
          apiKey: "env:EMBEDDINGS_API_KEY",
        },
        model: "asymmetric-embedder",
        queryInputType: "query",
        documentInputType: "passage",
      },
    },
  },
}

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "bedrock",
        model: "amazon.titan-embed-text-v2:0",
      },
    },
  },
}

{
  "Effect": "Allow",
  "Action": "bedrock:InvokeModel",
  "Resource": "*"
}

arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0

openclaw memory status --deep --agent main
openclaw memory index --force --agent main

# 內嵌嵌入逾時

# 混合搜尋設定

全部位於 memorySearch.query.hybrid 下：

# 完整範例

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            vectorWeight: 0.7,
            textWeight: 0.3,
            mmr: { enabled: true, lambda: 0.7 },
            temporalDecay: { enabled: true, halfLifeDays: 30 },
          },
        },
      },
    },
  },
}

# 其他記憶體路徑

{
  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 一起索引：

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

# 嵌入快取

在重新索引或逐字稿更新期間，避免重新嵌入未變更的文字。

# 批次索引

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

remote.nonBatchConcurrency 控制本機／自託管供應商，以及未啟用供應商批次 API 時的託管供應商所使用的內嵌嵌入呼叫。Ollama 的非批次索引預設為 1，以避免讓較小的本機主機負載過高；在較大的機器上可設定較高的值。

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

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

索引工作階段逐字稿，並透過 memory_search 呈現：

# SQLite 向量加速（sqlite-vec）

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

# 索引儲存

# QMD 後端設定

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

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

OpenClaw 偏好目前的 QMD collection 與 MCP query 形狀，但會在需要時嘗試相容的 collection pattern flags 與較舊的 MCP tool 名稱，以維持較舊 QMD 版本可用。當 QMD 宣告支援多個 collection filters 時，同來源 collections 會以單一 QMD process 搜尋；較舊的 QMD builds 則保留逐 collection 的相容路徑。同來源表示 durable memory collections 會被分組在一起，而 session transcript collections 仍保留為獨立群組，讓 source diversification 仍同時具備兩種輸入。

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

QMD boot refreshes 會在 Gateway 啟動期間使用一次性的 subprocess path。當 memory search 被開啟供互動使用時，長駐 QMD manager 仍負責一般 file watcher 與 interval timers。

# 完整 QMD 範例

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

# Dreaming

Dreaming 設定於 plugins.entries.memory-core.config.dreaming 之下，而不是 agents.defaults.memorySearch 之下。

Dreaming 會作為單一排程 sweep 執行，並使用內部 light/deep/REM phases 作為 implementation detail。

如需概念行為與 slash commands，請參閱 Dreaming。

# 使用者設定

# 範例

{
  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",
          },
        },
      },
    },
  },
}

# 相關

• 設定參考
• Memory 概覽
• Memory search