TencentDB Agent Memory：從扁平向量堆到可追溯的分層記憶

先講結論：Agent 的記憶，重點不是存得更多

當 AI Agent 從單輪問答走向長任務，記憶很快會變成效能瓶頸。搜尋結果、工具輸出、錯誤堆疊、使用者偏好與過去對話全部留在上下文裡，模型看似「知道更多」，實際上卻要付出更高的 token 成本，還可能在大量互不相關的片段中迷失。

TencentCloud 開源的 TencentDB Agent Memory 提供了一個值得注意的解法：不要把所有內容扁平化後丟進向量資料庫，而是把記憶拆成不同層級，讓 Agent 先讀取高密度的結構，再在需要時沿著識別碼回查原始證據。

這個專案目前定位為 AI Agent 的團隊記憶中樞，將對話、文件與程式碼整理成可重用的記憶資產；它同時提供 OpenClaw 外掛，也支援 Hermes Agent。對正在建構多步驟 Agent、工具呼叫流程或長期個人助理的人來說，它的價值不在「再做一個聊天機器人」，而在於處理 Agent 工作流中最容易被低估的狀態管理問題。

本文的效能數字與架構描述以專案 README 和官方文件為來源。README 中的 benchmark 是專案作者公布的結果，應視為專案報告，不等同於在你的資料集與模型上的保證。

為什麼傳統記憶方案會失控？

最直覺的做法是把每一段對話切成 chunk，產生 embedding，再放進向量資料庫。使用者下次提問時，系統以相似度找回幾段文字。這個流程對 FAQ 或短內容搜尋很實用，但對長時間運作的 Agent 有三個結構性問題。

第一，向量相似不等於工作關係。一段「上次部署失敗」的錯誤記錄，和一段「偏好使用 Docker」的使用者設定，可能都包含相似的技術詞，卻在任務中扮演完全不同的角色。只靠相似度，系統很難理解哪些是事實、哪些是場景、哪些是可重用的操作模式。

第二，上下文沒有成本意識。工具輸出可能有幾十萬個 token，但真正需要模型注意的往往只是「哪個步驟成功、哪個節點失敗、下一步該怎麼走」。把完整日誌直接注入上下文，既浪費 token，也增加模型忽略關鍵資訊的機率。

第三，摘要常常不可逆。如果只把歷史濃縮成一段摘要，之後發現摘要漏掉一個參數或錯誤原因，就很難知道它是怎麼推導出來的，更不用說回到原始工具輸出重新驗證。

TencentDB Agent Memory 的設計，正是針對這三個問題：用分層取代扁平存儲，用符號化取代冗長日誌，並保留從高層結構回到原始證據的路徑。

兩條主軸：記憶分層與符號化記憶

1. 短期記憶：把工具日誌移出上下文

在長任務中，短期記憶處理的是「目前這個任務發生了什麼」。專案採用三層方式：

• 底層：把完整工具輸出與原始文字寫到外部檔案，例如 refs/*.md，保存查證所需的細節。
• 中層：將每一步抽取成 jsonl 等結構化摘要，記錄步驟、結果與關聯。
• 頂層：用 Mermaid 圖把任務狀態濃縮成高密度的符號畫布，只把這個輕量結構放進 Agent 上下文。

模型平常只需要讀頂層圖，就能掌握任務的主要節點；如果它需要核對一個錯誤訊息或某個工具回傳值，再依照 node_id 去找回底層原文。這是「progressive disclosure」的實作：先給剛好足夠的資訊，細節在需要時展開。

概念上可以想成下面的資料流：

graph LR
    A[完整工具輸出] -->|保存原文| B[refs/*.md]
    A -->|抽取關係| C[Mermaid 符號畫布]
    C -->|輕量注入| D[Agent 上下文]
    D -.->|依 node_id 回查| B

這個策略與單純摘要最大的不同，是「壓縮上下文」和「保存證據」同時成立。Agent 不必每一輪都攜帶完整日誌，但系統也沒有把原文丟掉。

2. 長期記憶：從對話逐層抽象成 Persona

跨工作階段的記憶，處理的是「這個人、這個團隊或這個專案長期有什麼規律」。TencentDB Agent Memory 把長期個人化記憶設計成語意金字塔：

• L0 Conversation：原始對話。
• L1 Atom：從對話抽取出的原子事實，例如偏好、限制或已確認的決策。
• L2 Scenario：把多個事實組合成可理解的情境區塊。
• L3 Persona：形成較穩定的使用者或團隊輪廓。

上下層不是互相取代，而是各自負責不同的取用成本。Agent 平常可以先讀 Persona 或 Scenario；當某個細節影響決策時，才往下鑽取到 Atom 與 Conversation。這讓「記得使用者偏好」不必等於「每次都重新載入所有歷史對話」。

同樣的分層概念也延伸到 Skill 生成：從底層執行紀錄找出重複出現的解法，再逐步整理成 Scenario，最後沉澱成可重用的 Skill 或 SOP。對企業 Agent 來說，這比單純保存聊天紀錄更接近真正的知識運營。

可追溯性：為什麼 node_id 很重要？

記憶系統最怕兩件事：模型把錯誤摘要當真，以及工程師無法回答「這個結論從哪裡來」。專案的做法是為高層符號保留回溯鏈：

Persona / Mermaid Canvas
        ↓
Scenario / jsonl index
        ↓
Atom / refs
        ↓
原始對話、工具輸出與錯誤堆疊

在短期記憶中，Mermaid 畫布上的節點帶有 node_id。Agent 可以用圖理解狀態轉移，程式則可以用同一個 ID 搜尋原始檔案。這種設計把「模型可讀的摘要」和「工程師可驗證的證據」接在一起。

它不會自動消除幻覺，也不會保證每個抽取結果正確；但至少讓錯誤調查有可操作的入口。當 Agent 說「部署在第三步失敗，原因是權限不足」時，系統應該能帶你回到對應的工具輸出，而不是只能相信一段無來源的摘要。

實作方式：先用本地 SQLite 跑起來

目前官方 README 提供 OpenClaw 與 Hermes 兩條整合路徑。最容易驗證概念的方式，是先在本機用 SQLite 加 sqlite-vec，不要一開始就把問題複雜化成遠端資料庫部署。

OpenClaw：外掛安裝與零配置啟用

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

接著在 OpenClaw 設定中啟用外掛：

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

預設後端是本地 SQLite + sqlite-vec。啟用後，外掛會在對話流程中處理對話擷取、記憶抽取、場景聚合、Persona 生成與下一輪回憶。若要測試短期上下文壓縮，再加入 offload 設定，並把 contextEngine slot 指向 memory-tencentdb。

{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  },
  "memory-tencentdb": {
    "enabled": true,
    "config": {
      "offload": {
        "enabled": true
      }
    }
  }
}

README 也提醒，較新的 OpenClaw 版本可能需要執行一次 after-tool-call-messages.patch.sh，讓工具呼叫後的訊息能正確被 offload 與回收。這一步應該依你目前安裝的版本與官方文件確認，不要盲目套用補丁。

Hermes：接到既有安裝

如果你已經有 Hermes Agent，可以不使用專用 Docker 映像，直接安裝外掛並把 provider 接到 Hermes 的 memory 設定。官方流程的核心步驟如下：

mkdir -p ~/.memory-tencentdb
cd ~/.memory-tencentdb
npm init -y --silent
npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev

接著把外掛放到統一目錄，並連結到 Hermes 的 provider 目錄：

rm -rf ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb
ln -sf ~/.memory-tencentdb/tdai-memory-openclaw-plugin/hermes-plugin/memory/memory_tencentdb \\
  ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb

這裡有一個容易踩到的命名細節：資料夾必須叫 memory_tencentdb，使用底線；設定層可以使用 memory-tencentdb 這個別名，但 provider 目錄不能改成連字號。

在 Hermes 設定中指定 provider：

memory:
  provider: memory_tencentdb

Gateway 需要一組啟動命令與模型設定。請把 API key 放在環境變數或受控的 .env 檔中，不要把憑證寫進文章、Issue 或 shell history：

MEMORY_TENCENTDB_GATEWAY_HOST="127.0.0.1"
MEMORY_TENCENTDB_GATEWAY_PORT="8420"
TDAI_LLM_BASE_URL="https://your-openai-compatible-endpoint/v1"
TDAI_LLM_MODEL="your-model"
TDAI_LLM_API_KEY="your-api-key"

Gateway 可以手動啟動，也可以讓 provider 在第一次對話時自動偵測並啟動。完成後先用 health endpoint 驗證：

curl http://127.0.0.1:8420/health

預期會得到 status 為 ok 或 degraded 的 JSON。若是既有 Hermes 安裝，建議先保留原本的 memory provider 設定檔，逐步比較啟用前後的上下文長度、延遲與錯誤率。

Docker：適合隔離測試或全新部署

如果你要從零建立一個帶記憶的 Hermes，官方也提供 Docker 路徑，Gateway 預設監聽 8420，資料放在 named volume。這種方式的好處是依賴隔離、重建容易；代價是需要處理模型 API、volume 備份與網路暴露。

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" \\
  -v hermes_data:/opt/data \\
  hermes-memory

curl http://localhost:8420/health

這段範例中的 key 只是佔位符。正式部署時應改用 secret manager、受限權限的環境檔或平台提供的 secret 注入，不要把真正的金鑰提交到 Git。

專案報告的 benchmark，應該怎麼讀？

README 公布了與 OpenClaw 整合後的幾組結果：在 WideSearch 上，成功率由 33% 提升到 50%，token 使用量由 221.31M 降到 85.64M；在 SWE-bench 上，成功率由 58.4% 到 64.2%，token 使用量由 3474.1M 降到 2375.4M；PersonaMem 則由 48% 到 76%。

這些數字很吸引人，但正確的解讀方式是「專案作者在特定環境下量測到的改善」，而不是「安裝後一定減少 61.38% token」。實際結果會受到模型版本、上下文策略、工具數量、任務長度、資料分布與抽取成本影響。

如果要在自己的環境驗證，建議固定以下變數：

1. 相同模型與 temperature。
2. 相同任務集合與工具可用性。
3. 相同的最大上下文與重試策略。
4. 分別記錄總 token、每輪延遲、工具成功率與最終任務完成率。
5. 對記憶抽取錯誤做人工抽樣，不只看成本下降。

尤其要注意，記憶系統本身也會消耗模型呼叫與儲存空間。真正有價值的指標不是單獨的 token 數，而是「完成同一批任務所需的總成本，以及結果是否更可重現」。

適合哪些場景？

適合：

• 需要連續執行多個工具步驟的研究、開發與自動化 Agent。
• 會反覆使用相同 SOP、專案背景與團隊規範的工作流。
• 想讓不同 Agent 或不同工作階段共享可治理記憶的團隊。
• 需要在節省上下文成本的同時，保留錯誤調查與證據回溯能力的系統。
• 已經使用 OpenClaw 或 Hermes，想以 provider／plugin 方式增強記憶，而不是重寫整個 Agent。

不一定適合：

• 只有幾輪對話、沒有跨工作階段狀態的簡單 chatbot。
• 只想做一次性的語意搜尋，且不需要場景、Persona 或工具鏈回溯。
• 目前還沒有能力監控資料保留、權限與模型抽取品質的團隊。

另外，任何保存使用者偏好、對話與工具輸出的系統，都必須先定義資料邊界。哪些內容可以長期保存？誰能查詢？如何刪除？如何處理敏感資訊？分層架構解決的是檢索與成本問題，不會自動替你完成治理。

實務評估清單

如果你要把它放進既有 Agent，建議按照下面順序試：

第一步：只啟用長期記憶

先用本地 SQLite，建立幾個可重現的對話情境，例如「使用者偏好的輸出格式」、「專案部署規則」與「常見錯誤修復」。確認下一個工作階段真的能正確召回，再考慮短期 offload。

第二步：加入短期壓縮

挑一個工具輸出很長的任務，量測上下文大小與最終成功率。檢查 Agent 是否能從 Mermaid 畫布找到正確 node_id，並且能在需要時回到 refs 讀到完整原文。

第三步：測試失敗與降級

刻意讓 Gateway 暫時不可用，觀察主 Agent 是報錯、跳過記憶，還是卡住整個任務。記憶通常是輔助能力，不能讓一個資料庫或 Gateway 故障拖垮核心對話。

第四步：再決定是否集中式部署

單機驗證通過後，才評估團隊共享、備份、權限與高可用。把原始證據與高層 Markdown 資產分開備份，並為資料刪除與保留期限建立明確流程。

結語：好的 Agent 記憶，應該同時「省」與「能查」

TencentDB Agent Memory 最值得看的地方，不是它宣稱支援多少平台，而是它把 Agent 記憶重新定義成一個可分層、可壓縮、可回溯的系統。短期記憶用符號化畫布降低上下文負擔，長期記憶用 Conversation → Atom → Scenario → Persona 建立抽象層，底層則保留能回查的原始證據。

這種設計也提醒我們：Agent 的「記得」不應該等於把全部歷史塞回 prompt。真正可用的記憶，應該知道什麼需要常駐、什麼可以延後載入、什麼必須保留原文，以及如何讓人類在結果可疑時重新檢查來源。

如果你正在做多步驟 Agent、長期工作流或團隊級 AI 助理，這個專案很適合拿來當作記憶層的參考實作。最務實的起點不是直接相信 benchmark，而是用一個可重現的小型任務集，量測啟用前後的 token、延遲、成功率與可追溯性，再決定它是否符合你的生產需求。

延伸閱讀與來源

• TencentDB Agent Memory GitHub
• 官方 README：架構與 benchmark
• Hermes Agent
• OpenClaw