使用 openclaw memory 管理語義記憶

你是否遇過開發 AI Agent 時，它總是記不住之前的對話，或是無法從堆積如山的資料中精準抓出重點？處理語義搜尋（Semantic Search）和索引管理通常很麻煩，尤其是當你需要手動同步向量資料庫或是確認索引狀態的時候。

openclaw memory 就是為了幫你解決這些問題而設計的。它讓你直接從終端機管理記憶索引，不用再寫額外的腳本來測試搜尋效果。

需要準備的東西

• 已啟用的 memory plugin（預設為 memory-core）
• 已配置的 agent 實例
• 支援 secrets.resolve 的 Gateway 版本（若有使用 SecretRefs）

快速開始

要在 5 分鐘內搞定記憶管理，你只需要掌握這幾個核心指令：

1. 檢查狀態：確認你的記憶庫是否正常運作。

   openclaw memory status --deep

2. 建立索引：讓 Agent 開始讀取並處理資料。

   openclaw memory index --agent main --verbose

3. 執行搜尋：測試語義搜尋的準確度。

   openclaw memory search "meeting notes" --max-results 5

常用範例

你可以根據需求組合不同的 flag：

# 輸出 JSON 格式方便自動化處理
openclaw memory status --json

# 強制重新索引所有內容
openclaw memory index --force

# 使用特定的 agent 進行深入搜尋
openclaw memory search --query "deployment" --agent main --min-score 0.8

# 查看詳細的索引過程（包含 provider 和 batch 資訊）
openclaw memory status --deep --index --verbose

指令詳解

狀態檢查與索引管理

memory status 和 memory index 支援 --agent <id> 參數。如果你不指定，系統會對所有已配置的 agent 跑一遍；如果沒配置 agent 列表，則會回退到預設的 agent。

• --verbose: 想看詳細的 probe 和索引日誌就加上它。
• --deep: 在 status 中使用，用來探測 vector 和 embedding 是否可用。
• --force: 在 index 中使用，會強制執行完整的重新索引。

語義搜尋

memory search 要求你必須提供查詢內容，你可以直接接在指令後面，或是使用 --query。

• 如果同時提供 positional query 和 --query，系統會以 --query 為準。
• --max-results <n>: 限制回傳的結果數量。
• --min-score <n>: 過濾掉分數太低的匹配項。

疑難排解

如果你在使用過程中遇到問題，可以檢查以下幾點：

• Gateway 無法連線：如果你的 API key 是以 SecretRefs 格式配置，指令會嘗試從 Gateway snapshot 解析數值。如果 Gateway 沒開，指令會直接報錯退出。
• Unknown-method 錯誤：這通常是因為你的 Gateway 版本太舊。openclaw memory 需要支援 secrets.resolve 的 Gateway 版本。
• 搜尋沒有結果：檢查你的索引是否為「dirty」狀態，可以執行 openclaw memory status --index 來自動修復並重新索引。
• 指令直接結束：執行 memory search 時如果沒有提供任何 query 文字，指令會回傳錯誤並結束。

如有其他設定問題，請參考 AI Setup Assistant 獲取即時協助。

下一步

• Memory 核心概念
• Plugin 配置指南