TencentDB Agent Memory 本地 Agent 指南：先搞懂資料去哪，再決定要不要裝

Side project 跑久了，最煩的通常不是模型不夠聰明，而是它每次重開都失憶。你得重講架構、偏好、做到哪裡，手動維護的 MEMORY.md 又越來越長。TencentDB Agent Memory 想解的是這個問題，但「本地記憶」四個字很容易讓人誤會。這篇依官方文件拆解，我沒有在本次撰稿中親自安裝，因此不會把官方測試寫成實測心得。

先講適用門檻：這是給已經在自架 OpenClaw、Hermes，或願意維護 Gateway 的讀者。若你只用 ChatGPT、Claude 或 Notion 的一般介面，沒有在管理自己的 Agent runtime，這套 plugin 目前不是你的低門檻記憶工具。

TL;DR

預設 SQLite 代表記憶資料可存在本機，不代表抽取與搜尋完全不會呼叫外部模型。
它的差異是把記憶分成 L0 到 L3，並保留從 Persona 往回追到原始對話的路徑，不只是多放一個向量庫。
第一輪先用隔離 Agent、SQLite 與 keyword 搜尋，跨 session 召回真的有用，再考慮 embedding 或雲端後端。
短任務、低頻使用，或 MEMORY.md 已經夠用的人，不值得多養一套有狀態的服務。

「本地」到底本地在哪裡？

TencentDB Agent Memory 的本地模式，是把記憶後端設為 SQLite + sqlite-vec。 這回答的是「資料存在哪裡」，沒有回答「哪些內容會被模型處理」。長期記憶抽取仍需要 LLM，embedding 是否外送則取決於你的設定。

安裝前先把資料流拆成四段，會比看一句 local-first 安心很多。

階段	處理內容	預設或可選目的地	安裝前要問
對話捕捉	原始 conversation	本機 L0 檔案與 SQLite	客戶資料是否允許被捕捉？
記憶抽取	對話轉成 Atom、Scenario、Persona	OpenClaw 宿主模型或另設 LLM	模型是不是遠端 API？會送出哪些文字？
記憶儲存	分層記憶與索引	預設 SQLite，可選 TCVDB	資料路徑、權限與備份在哪裡？
記憶召回	keyword、embedding 或 hybrid 查詢	本機關鍵字搜尋，或設定的 embedding provider	查詢文字會不會離開裝置？

如果資料流裡有任何一段無法接受，就別拿真實客戶內容試。先放一個不敏感的 side project，這是最便宜的風險控制。

它不是另一個聊天紀錄庫，L0 到 L3 怎麼運作？

官方把記憶拆成四層：L0 是原始對話，L1 是可獨立使用的原子記憶，L2 把相關記憶整理成情境，L3 再形成 Persona。上層讓 Agent 快速取得背景，下層保留追查依據。

層級	主要內容	適合保存	最常見風險
L0 Conversation	原始對話	還原上下文、追查證據	敏感資訊被完整留下
L1 Atom	單一偏好、事實或決策	技術選擇、穩定偏好	抽取錯誤或資訊過期
L2 Scenario	一組相關情境	專案流程、重複場景	不同情境被錯誤合併
L3 Persona	高階使用者輪廓	長期合作方式	偏見被固化成「你就是這樣」

真正有用的是可追溯。當 Agent 堅持你偏好某個框架，你應該能從 Persona 回到 Scenario、Atom，再找到原始 Conversation，確認它是讀錯、摘要錯，還是資訊早就變了。純 Markdown 比較容易人工看懂，但要自己維護載入與更新；四層 pipeline 多了自動化，也多了必須治理的 state。

如果你還在選 Agent 的記憶方式，可以先看AI Agent 記憶架構的整理，再決定要不要把自動捕捉打開。

誰適合裝，誰用 MEMORY.md 就夠了？

先分清楚三種方案。OpenClaw built-in memory 會索引 MEMORY.md 與 memory/*.md，並支援 keyword、vector 與 hybrid 搜尋；TencentDB Agent Memory 則再加入對話捕捉與 L0 到 L3 抽取流程。兩者都可能使用 SQLite，但解的問題不完全一樣。

方案	記憶怎麼產生	搜尋方式	主要維護工作	適合誰
手動 `MEMORY.md`	人工整理與刪改	由 Agent 讀檔，或交給宿主索引	維護文字內容與載入規則	記憶量小、想完全掌控內容的人
OpenClaw built-in memory	索引 `MEMORY.md` 與 `memory/*.md`	keyword、vector、hybrid	管理檔案、embedding provider 與索引	已有 Markdown 記憶，主要缺搜尋的人
TencentDB Agent Memory	自動捕捉對話並抽取 L0 到 L3	keyword、embedding、hybrid	額外管理抽取、排程、分層資料、備份與版本	跨 session 背景重複多，且需要追溯記憶來源的人

你的情況	建議	原因
每週多次重講同一份專案背景	試跑	重複成本清楚，容易量測改善
長 session 常因 context 壓力遺失早期決策	試跑	分層記憶可能比整段歷史重塞更好管理
需要查出某個偏好從哪段對話而來	試跑	可追溯鏈路正好對應需求
任務一兩次就結束	先不要	額外的資料庫與排程很難回本
一份短 `MEMORY.md` 已穩定運作	保持簡單	人工可讀、可版控，故障面更少
無法做備份、權限管理與定期檢查	不要上正式資料	長期記憶會累積，沒治理就只是延後出事

GitHub 熱度不是採用門檻。你真正要算的是，一週重複交代背景幾次，以及願不願意負責備份、刪除、升級與錯誤記憶修正。

OpenClaw 最小試跑，先不要一次裝滿所有元件

官方目前提供的最短 OpenClaw 路徑是安裝 npm plugin、重啟 Gateway，再啟用 memory-tencentdb。發布前我已用官方 README 與 npm 頁交叉確認套件名稱，但 OpenClaw 與 plugin 都會更新，執行前仍應重看 README 和 CHANGELOG。

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

接著編輯官方 README 指定的 ~/.openclaw/openclaw.json。只寫 enabled: true 時，官方 schema 的 recall strategy 預設是 hybrid，但 embedding provider 預設是 none。這和本文要測的純 keyword baseline 不一致，因此第一輪要把兩個欄位都寫清楚：

{
  "memory-tencentdb": {
    "enabled": true,
    "config": {
      "recall": {
        "strategy": "keyword"
      },
      "embedding": {
        "provider": "none"
      }
    }
  }
}

第一輪只做三件事：用測試 profile、保留預設 SQLite、明確使用 keyword 並關閉 embedding。short-term offload、TCVDB、remote embedding 都會增加變因，等基本寫入與召回穩定再加。

重新啟動 Gateway 後，先確認新 session 能載入 plugin，再進行下面的跨 session 測試。OpenClaw 的 log 指令與輸出格式可能隨版本改變，官方 README 目前沒有提供一條通用的載入檢查指令；若 plugin 沒有出現在啟動結果或完全沒有 capture，應先對照當版 README、manifest 與 Issues，不要拿 standalone／Hermes 的 memory-tencentdb-ctl health 當成 OpenClaw 驗收指令。

版本相容是現實地雷。2026 年 10 月 3 日重查時，npm 的 latest 已是 1.0.3；官方 1.0.3 release notes 說明這版修正了 OpenClaw 9.5 首次安裝可能漏寫 enabled，以及新版套件目錄造成 sqlite-vec 載入失敗的問題。若你從 1.0.1 升級，先備份資料、鎖定 1.0.3，重啟後再確認 plugin 已啟用，而且沒有降級成非向量搜尋。不要把舊教學裡的 patch 指令直接貼到新環境。

五步驗收，證明它真的能跨 session 記得

「plugin enabled」只代表載入成功，不代表 capture、extraction、聚合與 recall 全部正常。用一段不敏感、容易判斷對錯的資訊測最準，例如：「這個測試專案的 release branch 叫 pilot-release，每次合併前要先跑 dry run。」

寫入：在測試 Agent 明確說出專案規則，記錄時間與 session。
等待抽取：依設定等待 L1 pipeline 執行，檢查 logs 或可讀的記憶檔案，別自己猜完成時間。
開新 session 召回：只問「這個專案合併前要做什麼？」，不要把答案藏在問題裡。
回溯證據：從召回結果找到 Atom 與原始對話，確認內容和來源都正確。
修正與停用：刻意更改規則，確認舊資訊能被辨認；停用後再確認不會繼續 capture。

每次測試記五個欄位：正確命中、漏召回、誤召回、等待時間、人工修正次數。只測一次成功沒有意義，因為你不知道它是穩定召回，還是剛好撞到關鍵字。

Keyword 還是 Embedding，用自己的十題決定

不設定 embedding 仍可使用 keyword 路徑。 OpenClaw plugin manifest 提供 keyword、embedding、hybrid 三種 recall strategy，並寫明 embedding.provider: "none" 會停用向量搜尋。官方 CTL 文件中的 BM25 fallback 與關閉 embedding 指令則屬於 standalone／Hermes 路徑，不能直接拿來操作 OpenClaw。這讓你可以先建立低複雜度 baseline。

準備十題，不要十題都照原句問。五題保留原關鍵字，另外五題改寫語意，例如把「release branch」改成「正式發布前要合併到哪條分支」。記錄：

Top 5 裡有沒有正確答案
有沒有把其他專案的規則撈進來
查詢等待多久
是否多出 API 費用
查詢內容是否送到外部 provider

如果 keyword 已穩定命中，就沒有必要為了「比較 AI」而開 embedding。只有語意改寫持續失敗，而且你能接受新的資料流與成本，才測 hybrid。官方文件沒有讓我確認所有 embedding 設定切換時是否一律需要重建既有索引，所以這點應以你安裝版本的文件與實際 migration 提示為準。

Production 地雷圖，記憶錯了、滿了、洩漏了怎麼辦？

長期記憶不是裝完就不管的功能。它會持續收資料，也會把模型抽取結果帶進後續對話。正式使用前至少檢查這六項：

Retention：l0l1RetentionDays 預設值代表什麼，是否符合你的保存政策。
Recall budget：用 maxCharsPerMemory 與 maxTotalRecallChars 控制單次注入量，避免記憶把 context 撐滿。
Agent 隔離：用 excludeAgents 排除不該捕捉或召回的測試、評分與敏感 Agent。
備份與回滾：備份資料目錄與設定檔，確認能從副本恢復，不只確認檔案有複製。
Gateway 安全：若使用 standalone Gateway，檢查 bind 位址、認證、CORS 與憑證權限。
人工 review：定期打開 Persona 與 Scenario，刪除過期偏好，追查無來源的結論。

官方 CHANGELOG 曾列出 scene rollback、cleaner 護欄、recall 字元預算、Bearer auth 與 OpenClaw 相容性修正。這些修復是有價值的透明度，也是在提醒你，狀態清理與網路邊界不能只靠預設值。

還有三個不能從功能名稱直接推定的邊界。官方 schema 能確認 plugin 會捕捉對話、呼叫宿主 LLM，並依設定使用本機 SQLite 或遠端服務；但它沒有承諾 workspace sandbox，也沒有證明一般使用者只能看到自己的記憶。官方欄位與 CHANGELOG 提供 timeout、警告 log、備份與 rollback 線索，卻不足以證明每種中斷都能自動重試、checkpoint 或避免重複寫入。若你需要稽核軌跡、逐筆匯出或可驗證刪除，先把這三項列為上線前實測，不通過就只留在不敏感的隔離 Agent。

官方 benchmark 怎麼看，自己怎麼做 A/B？

官方 npm 頁列出 WideSearch、SWE-bench、AA-LCR 與 PersonaMem 的長時間 session 測試，也清楚說明不是單輪任務。這些數字是供應商自報，目前沒有足夠的獨立重現資料讓我把它外推成「你的專案一定省多少 token」。

把 benchmark 當測試設計比較有用。固定同一個模型、任務集、temperature 與起始資料，分別跑 plugin off/on，至少比較：總 token、任務成功率、誤召回、人工修正次數、運行成本。若只看 token 下降，卻花更多時間修錯誤記憶，那不叫省。

真正的採用證據，是同一批任務在你的環境裡變得更穩。 官方數字能證明值得測，不能替你決定是否上正式資料。

最後決策，保留、擴充或回滾

兩週試跑後，只做三選一：

保留：跨 session 命中穩定，誤召回可查可修，而且真的少了重複交代。
擴充：keyword 明顯漏掉語意改寫，資料外送與成本可接受，再測 embedding；多人或容量需求明確，才評估 TCVDB。
回滾：錯誤記憶難治理、沒有減少重複工作，或備份與升級成本高過收益，就停用 plugin 並保留乾淨的 Markdown 記憶。

回滾時先備份目前的設定與記憶資料，再把 ~/.openclaw/openclaw.json 裡 memory-tencentdb.enabled 改成 false，重啟 Gateway，開新 session 確認不再 capture 或 recall。確認停用後再決定是否解除安裝；官方文件沒有提供把既有分層記憶完整轉成 MEMORY.md 的通用 migration，也沒有足夠證據支持直接刪除某個固定 SQLite 路徑，所以不要在備份與停用驗證前清資料。

已經在 OpenClaw 跑長任務的人，先拿一個不敏感 side project 試兩週。只需要短任務或偶爾聊天的人，繼續用可讀、可版控的 MEMORY.md，反而比較踏實。記憶系統的價值不是它記得多，而是你知道它記了什麼，也能在它記錯時把路走回去。