TencentDB Agent Memory 怎麼接入 OpenClaw：本地長期記憶、日誌壓縮與可追溯檢索

OpenClaw 的長任務一旦跨越多輪工具調用，通常會出現兩個問題：上下文被日誌塞滿，或新會話又要重新解釋項目約定。TencentDB Agent Memory 爲 OpenClaw 提供本地長期記憶和短期日誌壓縮：默認使用 SQLite + sqlite-vec，將長期信息分層整理；啓用 offload 後，把完整工具輸出保存到外部文件，僅向上下文注入精簡的符號化狀態。項目官方倉庫

本文只處理 OpenClaw 接入。關鍵目標不是“讓 Agent 記住一切”，而是讓它在需要時能找回事實，並讓你能從高層摘要追溯到原始對話或工具日誌。

安裝前先確認兩件事

當前 OpenClaw 已能正常啓動和執行基本對話；先解決模型、權限或 Gateway 問題，再加記憶插件。
你清楚本機數據的備份位置和訪問邊界。記憶裏可能包含項目上下文、任務記錄和工具輸出，不應把它當作臨時無關緩存。

初次接入建議先只啓用長期記憶，確認召回正確後再啓用日誌壓縮。這樣一旦出現錯誤，能明確判斷是記憶抽取、檢索還是 offload 配置造成的。

安裝並啓用插件

使用 OpenClaw 原生插件命令安裝：

1
2


openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

後續升級也應使用 OpenClaw 的插件更新命令，避免語義版本範圍導致插件被禁用：

1

openclaw plugins update @tencentdb-agent-memory/memory-tencentdb

在 ~/.openclaw/openclaw.json 啓用：

1
2
3
4
5


{
  "memory-tencentdb": {
    "enabled": true
  }
}

官方 README 說明，默認後端是本地 SQLite + sqlite-vec。啓用後，插件會捕獲對話、抽取記憶、聚合場景、生成 Persona，並在下一輪前做召回；它不需要爲記憶功能額外調用外部 API。

用一組可驗證事實測試長期記憶

不要僅問“你還記得我嗎”。請做一個有答案、可複查的測試：

1
2
3


第 1 輪：告訴 Agent 當前項目的包管理器、測試命令和一條明確的輸出約定。
第 2 輪：讓它執行一個與這些約定相關的小任務。
新會話：詢問測試命令和輸出約定，並要求說明信息來源或不確定項。

通過標準不是它背出了更多內容，而是它能正確找回事實、不擅自補充不存在的信息。如果項目約定已經改變，應更新或清理舊記憶，而不是期待模型自動判斷哪一條過期。

啓用短期日誌壓縮（offload）

工具輸出、搜索結果和錯誤棧通常是長任務 token 膨脹的主要來源。項目的 offload 功能會把完整日誌移到外部文件，將壓縮後的 Mermaid 狀態圖留在上下文中。官方要求 OpenClaw 與插件版本不低於 0.3.4。

在插件配置中打開：

1
2
3
4
5
6
7
8
9


{
  "memory-tencentdb": {
    "config": {
      "offload": {
        "enabled": true
      }
    }
  }
}

然後註冊 context engine 槽位，讓 OpenClaw 將 context-offload 請求交給該插件：

1
2
3
4
5
6
7


{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

最後運行項目提供的補丁，使 after-tool-call 消息可被卸載和恢復：

1

bash scripts/openclaw-after-tool-call-messages.patch.sh

該補丁對每個 OpenClaw 安裝只需運行一次；OpenClaw 升級後，需要重新應用。

可追溯檢索如何工作

日誌壓縮不應該等於丟失細節。TencentDB Agent Memory 的短期鏈路是：

1
2
3
4
5


完整工具日誌 → refs/*.md
              ↓
步驟摘要 → jsonl 索引
              ↓
Mermaid 狀態圖（帶 node_id）→ 注入 Agent 上下文

當 Agent 或你需要覈實某個結論時，可沿 node_id 從 Mermaid 狀態圖找到對應摘要和原始日誌。長期記憶也遵循類似的下鑽關係：Persona → Scenario → Atom → Conversation。因此，排查“爲什麼 Agent 記錯了”時，應先回到原始證據，而不是隻修改最終摘要。

啓用後應該做的三項驗收

長期召回：新會話中正確找回一條測試事實，並能承認不確定項。
日誌回溯：執行一段多工具調用任務，確認壓縮後仍能通過 node_id 找到原始輸出。
失敗保護：故意讓一個工具調用失敗，檢查錯誤信息、原始日誌和下一輪恢復是否仍可理解。

如果只看到上下文變短，卻不能追溯原始信息，不應將 offload 用於重要生產任務。壓縮的前提是可恢復，而不是減少 token 本身。

配置與數據的安全邊界

默認本地存儲並不意味着可以忽略安全。建議：

將記憶數據目錄納入加密備份與恢復演練。
不要在對話、工具日誌或 Persona 中放入不應長期保存的密鑰。
更新 OpenClaw 或插件後，先用測試會話確認記憶抽取、召回與 offload 沒有退化。
定期檢查舊 Persona、場景和項目約定，清除已過期或敏感的信息。

如需同時部署 Hermes、Docker Gateway 或 OpenAI 兼容本地模型，可閱讀 TencentDB Agent Memory 本地部署總覽。

常見問題

啓用後還是忘記項目約定，先查哪裏？

先確認插件已啓用、Gateway 已重啓、測試是否真的跨越新會話；再檢查記憶抽取的觸發時機與存儲目錄權限。不要用模糊描述測試，使用可驗證的命令、路徑或輸出約定。

offload 後爲什麼看不到完整日誌？

完整日誌應被保存到 refs/*.md 等外部記錄，不再全部注入上下文。通過 Mermaid 圖中的 node_id 和摘要索引回溯；若文件不存在或無法讀取，先排查路徑、權限和補丁是否已正確應用。

是否必須啓用 offload？

不是。短任務或調試初期可以只使用長期記憶。只有當工具輸出確實造成上下文膨脹，並且你已驗證回溯鏈路完整時，再開啓 offload。

小結

接入 TencentDB Agent Memory 的安全順序是：先安裝並啓用 OpenClaw 插件，用可驗證事實測試長期召回，再按需打開 offload、註冊 context engine、應用補丁，最後檢查 node_id 能否回到原始日誌。這樣得到的是可審計的本地記憶系統，而不是不可解釋的自動摘要。