给 AI Agent 装上记忆：TencentDB-Agent-Memory 上手指北
让 Agent 记住该记住的，人才有精力做判断、创造和真正重要的事。
最近逛 GitHub 发现腾讯开源了一个有意思的项目：TencentDB-Agent-Memory——给 AI Agent 装上分层记忆系统。花了一个下午踩坑装上，记录一下。
为什么需要 Agent 记忆？
用 Agent 最烦的就是重复解释。每次新对话都要重新交代项目背景、工具约定、输出格式——这些东西不该每次都讲，但直接全塞进上下文窗口又是 token 地狱。
现在的"记忆"方案大多是把对话切碎丢进向量库，召回靠相似度盲搜。问题是：
- 碎片化：失去了对话的层次和结构
- 不可追溯：召回了什么、为什么召回、原始证据在哪——全是黑盒
- 压缩不可逆：摘要一旦生成，原文就丢了，细节无法恢复
TencentDB 这个方案做得不一样。
核心思路：分层 + 符号化
1. 分层长期记忆
不是扁平向量堆，而是四层金字塔：
L0 原始对话 → 完整保留，可追溯
L1 原子事实 → 从对话中提取的独立事实
L2 场景块 → 相关事实聚合为场景（项目、习惯、偏好）
L3 用户画像 → persona.md，你的"说明书"
关键设计：上层做判断，下层做证据。任何时候都能从 Persona → Scenario → Atom → Conversation 一路追溯到底，不是黑盒。
2. 符号化短期记忆（Mermaid Canvas）
长任务里真正吃 token 的是工具调用的中间日志。这套系统把冗长的搜索结果、代码、错误栈压缩成 Mermaid 图，原文通过 node_id 索引到外部文件，需要时 grep 回捞。
原始日志（几十万 token）
→ 1. 原文转存到 refs/*.md
→ 2. 提取关系 → Mermaid 图（几百 token）
→ 3. 轻量注入上下文
→ 4. 需要细节时通过 node_id 回查
实际数据
在 OpenClaw 上跑出来的 benchmark：
| 场景 | 原始通过率 | 加记忆后 | 提升 |
|---|---|---|---|
| WideSearch | 33% | 50% | +51.52% |
| SWE-bench | 58.4% | 64.2% | +9.93% |
| PersonaMem 准确率 | 48% | 76% | +59% |
token 用量最多砍掉 61.38%——不是省一点，是对半砍。
安装踩坑记录
它是 OpenClaw 原生插件，理论上一条命令搞定：
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
但实际装的时候碰到几个坑：
坑 1：npm install 超时。 插件依赖多（better-sqlite3、sqlite-vec 等原生模块），openclaw plugins install 自带的 npm install 超时机制不够长，连试两次都在装依赖时被 kill。
解法：手动 npm pack → 解压 → 进目录 pnpm install --prod。用 pnpm 快不少。
坑 2：残留安装目录。 openclaw plugins install 失败后会留下 .openclaw-install-stage-* 临时目录，重启 gateway 时自动扫描导致 duplicate plugin id 报错。
解法：rm -rf ~/.kimi_openclaw/extensions/.openclaw-install-stage-*
坑 3：白名单。 插件装好了但默认不在 plugins.allow 列表里，状态是 disabled。
解法：在 openclaw.json 的 plugins.allow 中加上 memory-tencentdb，并在 plugins.entries 里显式 enabled: true。
坑 4：Kimi 桌面端管控。 我用的是 Kimi 桌面版，gateway 生命周期由桌面端 supervisor 管理，不能直接 openclaw gateway restart——会导致双 owner 冲突 gateway 挂掉。
解法：Cmd+Q 彻底退出 → 重新打开，让桌面端自行拉起 gateway。
装好后的状态
重启后插件自动创建了记忆目录：
~/.kimi_openclaw/memory-tdai/
├── conversations/ # L0 原始对话
├── records/ # L1 原子记忆
├── scene_blocks/ # L2 场景块
└── vectors.db # SQLite + sqlite-vec 混合检索
默认每 5 轮对话触发一次 L1 提取，每 50 条新记忆生成 L3 用户画像。零配置开箱即用，SQLite 本地存储，不上传任何数据。
另外多了两个工具：tdai_memory_search 和 tdai_conversation_search，Agent 可以在对话中主动搜记忆。
暂时没开的功能
短时压缩（Context Offload）——就是那个 Mermaid 图 + token 砍半的功能——默认关闭。开启需要注册 slot + 打 runtime patch，偏侵入式。打算先用基础记忆跑一周，稳定了再考虑。
总结
这个项目的设计理念我挺认同的：记忆不该是扁平碎片堆，也不该是不可逆的信息压缩。它用分层保证可追溯，用符号化压缩节省 token，两者形成闭环。
跟 Anthropic 推的 Agent Skills 是一个方向的互补——一个管"记住做过什么"，一个管"能做什么"。以后 Agent 生态的标配大概就是 Skills + Memory 双轨。
跑一段时间再回来更新实际体验。
2026-05-19 · 基于 v0.3.5
