TencentDB-Agent-Memory 项目实践：把 Agent 记忆做成分层、符号化、可回溯的结构

谢白羽

502人浏览 · 2026-05-26 16:06:39

谢白羽 · 2026-05-26 16:06:39 发布

TencentDB-Agent-Memory 项目实践：把 Agent 记忆做成分层、符号化、可回溯的结构

一句话定位：TencentDB-Agent-Memory 把 Agent Memory 从 flat storage 改造成分层系统：短期任务用 Mermaid Canvas 压缩，长期记忆用 L0 Conversation → L1 Atom → L2 Scenario → L3 Persona 逐层抽象。

项目：Tencent/TencentDB-Agent-Memory（约 3.8k Star）
npm：@tencentdb-agent-memory/memory-tencentdb
类型：本地 Agent Memory 插件 / 分层记忆系统
语言：TypeScript
协议：MIT
适合读者：正在做长程 Agent、OpenClaw / Hermes 集成、上下文压缩、用户画像和可追溯记忆系统的工程师。

项目导读

TencentDB-Agent-Memory 的核心判断是：Agent Memory 不应该只是 flat storage，而应该做 layering and symbolization。它把短期任务记忆和长期个性化记忆分开处理：短期任务里，完整工具日志下沉到 refs/*.md，步骤摘要进入 jsonl，上下文里只保留高密度 Mermaid 任务图；长期记忆里，原始对话逐步抽象为 Atom、Scenario 和 Persona。

如果把 Agent Memory 分成三层，TencentDB-Agent-Memory 对应第二层：分层管结构。它解决的不是「记忆怎么被所有 Agent 捕获」，也不是「记忆怎么进 attention」，而是记忆如何被组织、压缩、验证和回溯。

1. 核心结论

TencentDB-Agent-Memory 的关键词是分层：短期任务上下文分层，长期用户记忆也分层。
它用 Mermaid Canvas 表示任务状态，让 Agent 在上下文里看高密度符号图，而不是反复吞掉完整工具日志。
它用 L0 / L1 / L2 / L3 做长期记忆金字塔：Conversation 保存原文，Atom 保存原子事实，Scenario 保存场景块，Persona 保存稳定用户画像。
它非常重视可追溯性：node_id 和 result_ref 让高层摘要可以下钻到原始证据。
它不是单纯向量库。向量和 BM25 只是召回手段，真正的核心是结构化记忆组织。

2. 它要解决什么问题

长程 Agent 的上下文问题通常有两类。

第一类是 短期任务上下文膨胀。

Agent 在一个任务中会产生大量中间材料：

工具调用结果；
搜索结果；
代码片段；
错误堆栈；
测试输出；
文件 diff；
反复尝试的命令。

这些内容都可能有用，但全部塞进 prompt 会很贵，也会干扰模型注意力。

第二类是 长期记忆结构混乱。

如果把所有历史对话切块后放进向量库，系统确实能做语义召回，但很难回答：

这是原始证据，还是模型摘要？
这条偏好来自哪几次对话？
某个用户画像能不能回到具体事实？
当前任务状态和长期偏好是否混在一起了？
出错时如何快速定位原始工具输出？

TencentDB-Agent-Memory 的答案是：用分层结构把不同生命周期、不同抽象层级的记忆拆开。

3. 总体架构：短期一条线，长期一条线

可以把系统分成两条主线：

短期主线的目标是：让当前任务可继续、可压缩、可下钻。

长期主线的目标是：让用户偏好、场景经验和事实证据逐层沉淀。

4. 短期任务记忆：Mermaid Canvas + context offloading

长任务最容易浪费 token 的地方，是工具调用日志。

TencentDB-Agent-Memory 的做法不是简单总结整个历史，而是三层处理：

层级	载体	作用
底层	`refs/*.md`	保存完整原始工具输出、搜索结果、错误堆栈
中层	`jsonl`	保存步骤级摘要和结构化节点
顶层	Mermaid Canvas	保存当前任务状态、节点关系和转移路径

Agent 平时只需要读顶层 Mermaid Canvas。例如它知道：

当前任务到哪一步了；
哪些节点成功；
哪些节点失败；
哪个错误需要回看；
下一个动作应该接在哪个节点后面。

如果顶层符号图不够，Agent 再通过 node_id 或 result_ref 下钻到底层证据。

这条路线的关键不是 Mermaid 本身，而是 高层结构和底层证据分离。

LLM 使用 Mermaid 的方式更像人看流程图，而不是像程序查询 Neo4j。

它会先读节点，理解任务做过什么；再看箭头，理解步骤顺序、依赖关系和状态转移；然后看节点上的 node_id 或 result_ref，判断哪里能回到原始证据；最后决定下一步要继续查哪个节点、哪个摘要或哪个 refs 文件。

例如一个登录问题的短期任务图可以是：

这张图不负责执行查询，也不负责保存大规模实体关系。它负责把当前任务压缩成 LLM 可读的路线图：节点是步骤摘要，箭头是任务关系，result_ref 是证据入口。

5. 为什么用 Mermaid，而不是普通 JSON

公开 README 里强调了一个思路：Maximum Semantics in Minimum Symbols。

Mermaid 的优势在于：

紧凑：比自然语言历史摘要更短。
结构明确：节点、边、状态转移天然适合任务图。
人可读：开发者可以直接打开检查。
模型可读：LLM 能理解 Mermaid 的流程结构。
可下钻：节点可以绑定 node_id / result_ref。

普通 JSON 当然也能表达结构，但 JSON 往往会变得冗长，而且不如 Mermaid 适合直接展示任务状态图。对 Agent 来说，短上下文里的一张符号图，比大段日志更容易抓住任务主线。

因此，Mermaid 在这里不是底层索引，而是上下文里的“可读状态索引”。真正的底层检索仍然可以用 BM25、向量、SQLite 或文件路径；Mermaid 负责告诉 LLM 当前任务地图长什么样，以及应该沿哪条引用链继续下钻。

6. 长期记忆：L0 → L1 → L2 → L3

长期记忆采用四层金字塔：

层级	名称	中文理解	作用
L0	Conversation	原始对话	保存原始上下文和证据
L1	Atom	原子事实	抽取具体事实、偏好、事件
L2	Scenario	场景块	把相关事实组织成任务、生活、项目场景
L3	Persona	用户画像	沉淀长期稳定偏好、目标、习惯

可以这样理解：

L0：用户说过什么
L1：里面有哪些事实
L2：这些事实属于什么场景
L3：长期看，这个人有什么稳定偏好和画像

这套结构比 flat chunk 更适合个性化 Agent，因为用户画像不应该直接从某一句话得出，而应该能回溯到多个场景和原子事实。

7. 术语速查表

术语	中文理解	作用
Mermaid Canvas	任务画布	用 Mermaid 表示短期任务状态和步骤关系
context offloading	上下文卸载	把冗长日志放到文件里，上下文只保留摘要或符号图
`refs/*.md`	原始材料文件	保存工具输出、搜索结果、错误日志等完整证据
`jsonl`	步骤摘要	每行一个结构化事件或节点，供下钻时读取
`node_id`	节点 ID	连接 Mermaid 节点、摘要和原始材料
`result_ref`	结果引用	指向原始结果或文件路径，便于回溯
L0 Conversation	原始对话层	保存未经抽象的对话记录
L1 Atom	原子事实层	把对话抽成可检索事实
L2 Scenario	场景层	按项目、任务、生活场景组织事实
L3 Persona	用户画像层	保存长期偏好、习惯和稳定目标
RRF	融合排序	融合 BM25 和向量召回结果

8. 召回策略：先看高层，必要时下钻

TencentDB-Agent-Memory 的一个重要思想是：不同问题先查不同层。

问题类型	优先看	需要细节时
日常偏好、长期目标、用户语气	L3 Persona / L2 Scenario	下钻到 L1 Atom / L0 Conversation
具体事实、日期、项目细节	L1 Atom / L0 Conversation	扩大时间范围或语义召回
继续当前长任务	Active Mermaid task canvas	查 jsonl，再查 `refs/*.md`
恢复历史任务	任务元数据 / Mermaid canvas	通过 `node_id` 和 `result_ref` 找原文

这和传统向量库的区别很大。传统方式是「问题来了，全库 top-k」。分层方式是先判断应该看哪一层，再决定是否下钻。

9. 检索不等于结构

项目公开资料里也提到 BM25 + vector + RRF 的混合召回，默认本地后端是 SQLite + sqlite-vec，BM25 tokenizer 支持中文和英文。

但要注意：检索只是工具，不是架构本身。

TencentDB-Agent-Memory 真正有价值的是：

召回结果属于哪一层；
高层摘要是否能回到底层证据；
原始材料是否被完整保存；
Agent 是否能先看结构，再按需查细节。

如果只把它理解成「又一个 BM25 + 向量检索」，就低估了它的设计重点。

10. 安装与集成面

公开资料显示，它主要面向两个集成：

OpenClaw 插件：通过 @tencentdb-agent-memory/memory-tencentdb 安装。
Hermes Agent Docker 镜像：把 Hermes、插件和 TDAI Memory Gateway 打包在一个容器里。

OpenClaw 插件启用示例接近：

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

短期上下文 offloading 需要额外配置开关，并注册对应 context engine slot。也就是说，它不只是一个简单检索库，而是深入到 Agent 执行上下文管理里。

11. Agent 能看到的工具

公开资料里提到会暴露两个会话工具：

工具	作用
`tdai_memory_search`	搜索 L1 Atom、L2 Scenario 和 L3 Persona
`tdai_conversation_search`	搜索原始 L0 Conversation 历史

返回结果会带 node_id 和 result_ref，这是它和普通摘要记忆的关键差异：记忆不是孤立文本，而是带引用的结构节点。

12. Benchmark 怎么看

公开解读中提到的 Tencent 自评结果包括：

Benchmark	基线	接入插件后	变化
WideSearch	33%	50%	pass rate 提升，token 降低约 61.38%
SWE-bench	58.4%	64.2%	pass rate 提升，token 降低约 33.09%
AA-LCR	44.0%	47.5%	pass rate 小幅提升，token 降低约 30.98%
PersonaMem	48%	76%	长期记忆准确率提升

这些数字来自项目方或相关公开解读，应该当作方向性参考，而不是跨项目绝对比较。

更重要的是 benchmark 设计思路：它测的是连续长程 session 下的上下文累积压力，而不是孤立单轮问答。

13. 和 agentmemory 的区别

agentmemory 和 TencentDB-Agent-Memory 很容易被放在一起比较，但它们重点不同。

维度	agentmemory	TencentDB-Agent-Memory
核心定位	外部记忆基础设施	分层记忆组织
捕获方式	hooks / MCP / REST，跨 Agent	OpenClaw 插件 / Hermes 集成
短期任务	自动记录工具事件	Mermaid Canvas + refs/jsonl 分层
长期记忆	压缩、索引、图和混合检索	L0 / L1 / L2 / L3 语义金字塔
重点	治理、检索、共享、viewer	结构、符号化、证据回溯