內建記憶引擎

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

提供的功能

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

開始使用

依預設，內建引擎使用 OpenAI 嵌入向量。如果已設定 OPENAI_API_KEY 或 models.providers.openai.apiKey，向量搜尋無需額外的記憶設定即可運作。

若要明確設定提供者：

{  memory: {    search: {      provider: "openai",    },  },}

如果沒有嵌入向量提供者，則只能使用關鍵字搜尋。

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

openclaw plugins install @openclaw/llama-cpp-provider

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

支援的嵌入向量提供者

設定 memory.search.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。 若要使用本機嵌入向量，請設定 memory.search.provider: "local"。

結果過期？ 執行 openclaw memory index --force 以重建索引。在罕見的極端情況下，監看器可能會漏掉變更。

sqlite-vec 無法載入？ OpenClaw 會自動改用程序內餘弦相似度。openclaw memory status --deep 會分別回報本機向量儲存區與嵌入向量提供者，因此 Vector store: unavailable 指向 sqlite-vec 載入狀態，而 Embeddings: unavailable 則指向提供者／驗證或模型就緒狀態。請檢查日誌中的特定載入錯誤。

設定

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

相關內容

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