內建記憶引擎

內建引擎是預設的記憶後端。它會將記憶索引儲存在每個代理程式各自的 SQLite 資料庫中，且不需要額外相依套件即可開始使用。

提供的功能

• 透過 FTS5 全文索引進行關鍵字搜尋（BM25 評分）。
• 使用任何支援供應商所提供的嵌入向量進行向量搜尋。
• 結合兩者以獲得最佳結果的混合搜尋。
• 透過三元組詞元化支援中文、日文和韓文的 CJK 支援。
• 使用 sqlite-vec 加速資料庫內的向量查詢（選用）。

開始使用

根據預設，內建引擎使用 OpenAI 嵌入向量。如果已設定 OPENAI_API_KEY 或 models.providers.openai.apiKey，則無須額外設定記憶功能即可使用向量搜尋。

若要明確設定供應商：

{  agents: {    defaults: {      memorySearch: {        provider: "openai",      },    },  },}

若沒有嵌入向量供應商，則只能使用關鍵字搜尋。

若要強制使用本機 GGUF 嵌入向量，請安裝官方 llama.cpp 供應商外掛，然後將 local.modelPath 指向 GGUF 檔案：

openclaw plugins install @openclaw/llama-cpp-provider

{  agents: {    defaults: {      memorySearch: {        provider: "local",        fallback: "none",        local: {          modelPath: "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf",        },      },    },  },}

支援的嵌入向量供應商

設定 memorySearch.provider 即可改用 OpenAI 以外的供應商。

索引的運作方式

OpenClaw 會將 MEMORY.md 和 memory/*.md 索引為區塊（預設為 400 個詞元，重疊 80 個詞元），並將其儲存在每個代理程式各自的 SQLite 資料庫中。

• **索引位置：**所屬代理程式的資料庫： ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• **儲存維護：**透過定期檢查點和關閉時檢查點，限制 SQLite WAL 附屬檔案的大小。
• **檔案監看：**記憶檔案的變更會觸發經過防抖處理的重新索引（預設 1.5 秒）。
• **自動重新索引：**當嵌入向量供應商、模型、分塊設定、已設定的來源或範圍變更時，索引會自動重建。
• 隨需重新索引：openclaw memory index --force

適用時機

內建引擎是大多數使用者的合適選擇：

• 無須額外相依套件，開箱即可使用。
• 能妥善處理關鍵字搜尋和向量搜尋。
• 支援所有嵌入向量供應商。
• 混合搜尋結合了兩種擷取方式的優點。

如果您需要重新排序、查詢擴展，或想要索引工作區之外的目錄，請考慮改用 QMD。

如果您想要具備自動使用者建模功能的跨工作階段記憶，請考慮使用 Honcho。

疑難排解

**記憶搜尋已停用？**請檢查 openclaw memory status。如果未偵測到供應商，請明確設定一個供應商或新增 API 金鑰。

**未偵測到本機供應商？**請確認本機路徑存在，然後執行：

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

獨立的命令列介面命令和閘道都使用相同的 local 供應商 ID。若要使用本機嵌入向量，請設定 memorySearch.provider: "local"。

**結果已過時？**執行 openclaw memory index --force 以重建索引。在少數邊界情況下，監看器可能會遺漏變更。

**sqlite-vec 無法載入？**OpenClaw 會自動改用程序內餘弦相似度。openclaw memory status --deep 會分別回報本機向量儲存區與嵌入向量供應商的狀態，因此 Vector store: unavailable 表示 sqlite-vec 載入問題，而 Embeddings: unavailable 則表示供應商／驗證或模型就緒狀態有問題。請檢查日誌以取得具體的載入錯誤。

設定

如需嵌入向量供應商設定、混合搜尋調校（權重、MMR、時間衰減）、批次索引、多模態記憶、sqlite-vec、額外路徑及所有其他設定選項，請參閱記憶設定參考。

相關內容

• 記憶概覽
• 記憶搜尋
• 主動記憶