記憶搜尋

memory_search 會從你的記憶檔案中找出相關筆記，即使其措辭與原文不同。它會將記憶分割成小片段，並使用嵌入、關鍵字或兩者進行搜尋。

快速開始

OpenClaw 預設使用 OpenAI 嵌入。若要使用其他供應商，請明確設定：

{  memory: {    search: {      provider: "openai", // 或 "gemini"、"voyage"、"mistral"、"bedrock"、"local"、"ollama"、"lmstudio"、"github-copilot"、"openai-compatible"    },  },}

provider 也可以參照自訂的 models.providers.<id> 項目（例如 ollama-5080），只要該項目將 api 設為 "ollama"，或設為另一個具備記憶嵌入轉接器的供應商 ID。

若要使用不需 API 金鑰的本機嵌入，請安裝官方 llama.cpp 供應商外掛並設定 provider: "local"：

openclaw plugins install @openclaw/llama-cpp-provider

原始碼簽出仍需核准原生建置：先執行 pnpm approve-builds，再執行 pnpm rebuild node-llama-cpp。

部分與 OpenAI 相容的嵌入端點需要非對稱的 input_type 標籤，例如搜尋使用 "query"，索引片段使用 "document"/"passage"。請透過 queryInputType 和 documentInputType 設定；詳見記憶設定參考。

支援的供應商

搜尋的運作方式

OpenClaw 會平行執行兩條擷取路徑，並合併結果：

flowchart LR
    Q["查詢"] --> E["嵌入"]
    Q --> T["權杖化"]
    E --> VS["向量搜尋"]
    T --> BM["BM25 搜尋"]
    VS --> M["加權合併"]
    BM --> M
    M --> R["最佳結果"]

• 向量搜尋會比對相近的語意（「閘道主機」可比對到「執行 OpenClaw 的機器」）。
• BM25 關鍵字搜尋會比對完全相同的詞彙（ID、錯誤字串、設定鍵）。
• 檔名搜尋會將路徑與筆記內文分開建立索引。完全相符的完整路徑、基礎檔名及檔名主幹，排名會高於部分路徑相符項目；摘要與內文關鍵字分數仍取自筆記內容。

若只有其中一條路徑可用，另一條會單獨執行。

僅 FTS 模式。 將 provider: "none" 設定為刻意停用嵌入，並僅使用關鍵字搜尋。若未設定 provider 或將其設為 "auto"，且未設定嵌入驗證，也會回復為僅使用關鍵字排名而不會報錯；provider: "local"（GGUF/llama.cpp 供應商）失敗時亦同。

明確指定的供應商無法使用。 若你明確指定任何其他供應商（例如 openai、ollama、gemini），而該供應商在請求時無法使用（驗證錯誤、網路故障），memory_search 會回報記憶無法使用，而不會無聲降級為僅 FTS 結果。這可讓設定錯誤的供應商問題保持可見。若要刻意使用僅 FTS 的回憶功能，請設定 provider: "none"；或修正供應商／驗證設定，以恢復語意排名。

改善搜尋品質

兩項選用功能可協助處理大量筆記歷程。

時間衰減

舊筆記的排名權重會逐漸降低，讓近期資訊優先顯示。採用預設的 30 天半衰期時，上個月的筆記分數會降至原始權重的 50%。MEMORY.md 及 memory/ 下其他不含日期的檔案屬於長期有效內容，永不衰減；只有含日期的 memory/YYYY-MM-DD.md 檔案會衰減。

MMR（多樣性）

減少重複結果。如果五則筆記都提到相同的路由器設定，MMR 可確保最佳結果涵蓋不同主題，而非反覆顯示相同內容。

同時啟用兩者

{  memory: {    search: {      query: {        hybrid: {          mmr: { enabled: true },          temporalDecay: { enabled: true },        },      },    },  },}

多模態記憶

使用 gemini-embedding-2-preview，你可以將圖片與音訊和 Markdown 一併建立索引。這僅適用於 memory.search.extraPaths 下的檔案；預設記憶根目錄（MEMORY.md、memory/*.md）仍僅支援 Markdown。搜尋查詢仍為文字，但可與視覺及音訊內容進行比對。設定方式請參閱記憶設定參考。

工作階段記憶搜尋

若要從工作階段逐字稿進行精確全文回憶，請使用 sessions_search，再透過 sessions_history 開啟結果。工作階段記憶搜尋仍是實驗性的語意補充功能。

你也可以選擇為工作階段逐字稿建立索引，讓 memory_search 能回憶較早的對話。這是選用功能：請設定 experimental.sessionMemory: true，並將 "sessions" 加入 sources（sources 的預設值為 ["memory"]）。

工作階段命中結果遵循 tools.sessions.visibility：預設的 "tree" 會開放目前工作階段、由其衍生的工作階段，以及透過環境群組感知監看的同代理程式群組工作階段。使用 session.dmScope: "main" 時，多使用者私訊設定會共用該主要工作階段，因此被路由至該處的使用者可以回憶其所監看群組中的內容。若要隔離私訊，請使用每位對象獨立的 dmScope；或將可見性設為 "self"，以停用環境監看工作階段的讀取。其他不相關的同代理程式工作階段仍需要 "agent" 可見性。

使用 QMD 後端時，也請設定 memory.qmd.sessions.enabled: true，讓逐字稿匯出至 QMD 集合；僅設定 experimental.sessionMemory 和 sources 不會將逐字稿匯出至 QMD。詳見設定參考。

疑難排解

沒有結果？ 執行 openclaw memory status 檢查索引。若索引為空，請執行 openclaw memory index --force。

只有關鍵字相符結果？ 你的嵌入供應商可能尚未設定。請檢查 openclaw memory status --deep。

本機嵌入逾時？ ollama、lmstudio 和 local 使用由供應商管理的較長批次期限。請檢查供應商健康狀態，並重新執行 openclaw memory index --force。

找不到 CJK 文字？ 請使用 openclaw memory index --force 重建 FTS 索引。

相關內容

• 記憶概覽
• 主動記憶
• 內建記憶引擎
• 記憶設定參考