TencentDB Agent Memory on KnightLi的博客

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

Wed, 15 Jul 2026 22:08:00 +0800

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 啓用：

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

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

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

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

1
2
3

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

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

啓用短期日誌壓縮（offload）

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

在插件配置中打開：

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

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

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

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

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

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

可追溯檢索如何工作

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

完整工具日誌 → 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 能否回到原始日誌。這樣得到的是可審計的本地記憶系統，而不是不可解釋的自動摘要。

TencentDB Agent Memory 本地部署教程：長期記憶、日誌壓縮與可追溯召回

Wed, 15 Jul 2026 22:00:00 +0800

本地 Agent 經常遇到兩類相反的問題：會話一長，工具日誌和上下文迅速擠滿 token；會話一斷，又要重新解釋項目約定、偏好和已完成的工作。TencentDB Agent Memory 嘗試把這兩件事拆開處理：短期任務把冗長日誌卸載並壓縮，長期記憶把對話逐層整理爲可召回的信息，同時保留回到原始證據的路徑。項目官方倉庫

它並不是把全部聊天記錄塞回提示詞，而是使用“原始記錄 → 原子事實 → 場景 → Persona”的長期記憶層次；短期側則把工具輸出保留在文件中，以 Mermaid 任務圖和 node_id 提供精簡上下文與回溯入口。適合本地 Agent、OpenClaw、Hermes 及希望接入 OpenAI 兼容模型端點的場景。

部署前先決定：你要解決哪一類記憶問題

先把目標寫清楚，配置會簡單很多：

目標	優先啓用的能力	先驗證什麼
跨會話記住項目約定和用戶偏好	長期記憶與召回	是否能在下一輪正確找回歷史事實
長任務中工具日誌太長	短期 offload 與符號記憶	原始日誌是否可通過 `node_id` 回溯
本地運行且不想依賴外部記憶 API	SQLite + sqlite-vec 默認後端	數據目錄、備份和權限是否可控
用 Ollama 或其他本地模型	OpenAI 兼容 Gateway 配置	容器/宿主機能否訪問模型端點

不要一開始就打開全部功能。建議先完成長期記憶的寫入與召回，再開啓工具日誌壓縮；這樣出現遺漏時，才容易判斷是模型、檢索、壓縮還是網絡路徑的問題。

方案一：給 OpenClaw 加上本地長期記憶

官方 README 提供的 OpenClaw 路徑最短。插件默認使用本地 SQLite + sqlite-vec，不需要外部記憶 API：

1
2

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

在 ~/.openclaw/openclaw.json 中啓用插件：

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

啓用後，插件會負責捕獲對話、抽取記憶、聚合場景、生成 Persona，並在下一輪前執行召回。此時先做一個小驗證：連續完成幾輪有明確事實的對話，重開會話後詢問其中一個細節，確認 Agent 返回的是已保存事實，而不是自行猜測。

如果你還沒有準備好本地模型服務，可先從 Codex 本地大模型接入 Ollama 的排錯順序檢查服務、模型名稱和運行環境是否對齊。

按需打開短期日誌壓縮

長任務中最容易膨脹的是搜索結果、命令輸出和錯誤日誌。TencentDB Agent Memory 的 offload 會把完整工具日誌寫到外部文件，只將帶 node_id 的精簡 Mermaid 狀態圖放進上下文；需要細節時，Agent 可以再沿 node_id 找回原始文本。

OpenClaw 的官方示例要求版本不低於 0.3.4。先開啓 offload：

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

再註冊 context engine 槽位：

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

最後執行項目提供的補丁，使 after-tool-call 消息能夠被正確卸載和恢復：

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

OpenClaw 升級後需要重新應用這個補丁。上線前用一次包含多輪工具調用的任務驗證兩件事：上下文是否變短，以及失敗時能否從 Mermaid 圖的 node_id 回到對應原始日誌。只有同時滿足，壓縮纔沒有犧牲排障能力。

方案二：用 Docker 啓動 Hermes Memory Gateway

如果你使用 Hermes，官方 Docker 鏡像會將 hermes-agent 與 memory_tencentdb provider 一起構建，Gateway 默認監聽 8420。在倉庫根目錄執行：

cd docker/opensource
docker build -f Dockerfile.hermes -t hermes-memory .
docker run -d \
  --name hermes-memory \
  --restart unless-stopped \
  -p 8420:8420 \
  -e MODEL_API_KEY="your-api-key" \
  -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \
  -e MODEL_NAME="deepseek-v3.2" \
  -e MODEL_PROVIDER="custom" \
  -v hermes_data:/opt/data \
  hermes-memory

啓動後先檢查健康狀態：

`1`	`curl http://localhost:8420/health`

返回 {"status":"ok"} 或 {"status":"degraded"} 說明 Gateway 已啓動；degraded 時不要直接投入長期任務，應先檢查模型連接、存儲卷與日誌。

與 Ollama 對接時的正確邊界

項目的 MODEL_PROVIDER="custom" 用於 OpenAI 兼容端點。Ollama 提供兼容接口時，可以作爲該 Gateway 的模型來源；但“記憶存儲在本地”與“模型也完全本地”是兩件不同的事，分別驗證。

在 Docker 中連接宿主機 Ollama 前，先確認端點可達。Windows/macOS Docker Desktop 通常可使用 host.docker.internal；Linux 則需要按 Docker 網絡方式配置宿主機網關。示意配置如下，具體模型名以你本機已拉取的模型爲準：

MODEL_API_KEY="ollama"
MODEL_BASE_URL="http://host.docker.internal:11434/v1"
MODEL_NAME="qwen3"
MODEL_PROVIDER="custom"

先在相同網絡位置測試 /v1/models 或完成一個最小聊天請求，再啓動長期記憶任務。若容器裏把 localhost 寫成模型地址，實際指向的是容器自身，而不是運行 Ollama 的宿主機，這是最常見的連接錯誤。

有關 OpenAI 兼容本地 API、Ollama、LM Studio 和 vLLM 的端點檢查，可繼續閱讀本地大模型 API 給 Codex 使用教程。

可追溯性爲什麼比“自動總結”更重要

不可逆總結看似節省 token，卻可能把一個關鍵條件、失敗原因或用戶限制丟掉。這個項目將高層信息與底層證據保持關聯：

Persona / Mermaid canvas
        ↓
Scenario / jsonl 索引
        ↓
原始對話與工具日誌（L0 / refs/*.md）

排查時不要只看最終摘要。若 Agent 記錯了偏好或誤判任務狀態，應沿這條鏈路回到原始日誌，判斷是抽取錯誤、召回排序錯誤，還是原始輸入本來就不完整。把原始資料、記憶索引和配置文件一起納入備份，才能在遷移或升級時保留這種可驗證性。

基礎安全與運維檢查

Hermes Gateway 暴露 capture、search、recall 等 HTTP 接口。官方默認按本地 sidecar 使用；如果要綁定非迴環地址或讓其他機器訪問，必須加認證和來源限制。

1
2
3

export TDAI_GATEWAY_API_KEY="replace-with-a-long-random-secret"
export TDAI_CORS_ORIGINS="https://your-console.example"
export MEMORY_TENCENTDB_GATEWAY_API_KEY="$TDAI_GATEWAY_API_KEY"

然後確認 Gateway 與插件兩側使用同一個密鑰。不要把 8420 端口直接暴露到公網，也不要把 API key、記憶數據庫或 refs/*.md 一併提交進 Git。

建議把下面幾項納入日常檢查：

爲 SQLite 數據、掛載卷和記憶目錄建立定期備份與恢復演練。
記錄插件、OpenClaw/Hermes、模型和 Docker 鏡像版本，升級後先在測試會話驗證召回。
限制單次召回數量和注入字符預算，避免“記憶越多，上下文越重”。
定期抽查高層 Persona 是否包含過期或敏感信息，並按自己的數據規則清理。

常見問題

插件啓用了，爲什麼 Agent 還是記不住？

先確認是跨會話問題，而不是當前對話未完成。再檢查插件是否已啓用、記憶抽取觸發頻率、存儲目錄是否可寫，以及下一輪召回是否因超時被跳過。不要只用一句模糊問題測試，最好用可驗證的項目約定或事實。

開啓 offload 後，是否再也看不到原始日誌？

不是。offload 的目標是把完整日誌移出主上下文，而不是刪除它。應通過 node_id、索引和 refs/*.md 回溯原始記錄；若無法回溯，應停止將其用於重要任務並先修復存儲路徑或權限。

Ollama 接不上 Gateway，最先檢查什麼？

先區分宿主機和容器網絡。容器中的 localhost 不等於宿主機；再確認 Ollama 服務、模型名稱、OpenAI 兼容 URL、端口和防火牆。用最小接口請求連通後，再排查記憶插件本身。

小結

TencentDB Agent Memory 適合需要長期運行、又希望保持本地可控和可追溯的 Agent 工作流。先用默認 SQLite 後端跑通長期記憶，再按需開啓日誌 offload；本地模型接入則單獨驗證網絡與 OpenAI 兼容端點。這樣既能減少重複解釋，也不會在壓縮後失去定位問題的原始證據。