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

本地 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 中啓用插件：

1
2
3
4
5


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

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

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

按需打開短期日誌壓縮

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

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

1
2
3
4
5
6
7
8
9


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

再註冊 context engine 槽位：

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

方案二：用 Docker 啓動 Hermes Memory Gateway

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


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 網絡方式配置宿主機網關。示意配置如下，具體模型名以你本機已拉取的模型爲準：

1
2
3
4


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，卻可能把一個關鍵條件、失敗原因或用戶限制丟掉。這個項目將高層信息與底層證據保持關聯：

1
2
3
4
5


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 兼容端點。這樣既能減少重複解釋，也不會在壓縮後失去定位問題的原始證據。