TencentDB Agent Memory：用 4 层渐进式流水线，给 AI Agent 装上 "会分层的大脑"

发表于 分类于 ，
腾讯云开源的本地化 Agent 记忆框架，用符号化短期记忆 + 分层长期记忆的 4 层渐进式流水线，把 token 用量砍掉 61%、长任务成功率提升 52%，且零外部 API 依赖。

TencentDB Agent Memory：用 4 层渐进式流水线，给 AI Agent 装上” 会分层的大脑”

本文 GitHub 项目地址：TencentCloud/TencentDB-Agent-Memory
今日 stars：8.3k・最新版本 v0.3.6（2026-05-28）・License: MIT
今日推荐理由：在大模型 token 成本高企、Agent 长任务跑不动的当下，它用一套” 符号化 + 分层” 的极简设计，把 token 用量打到原来的 39%，并把长任务通过率拉到 1.5 倍，且完全本地化。

一、一个问题：你的 Agent 为什么” 记不住”？

你肯定碰到过这种场景：

让 Agent 帮你做”50 个连续 SWE-bench 任务”，它跑到第 30 个时，已经完全忘了第 5 个任务里你告诉过它的” 不要改这一行”；或者它在第 10 轮的工具调用里，把前面 9 轮的原始日志原封不动塞进上下文，结果单次调用光日志就消耗了 1 万 token，推理时延飙到 8 秒，账单爆炸；再或者你想让它记住” 我是 Go 后端，习惯用 clean architecture，测试用 testify”，它只在第 1 轮记住了，到第 5 轮又问” 你用什么技术栈”。

这些问题的本质，是当前主流 Agent 框架的” 记忆” 都太原始了 —— 要么把历史日志暴力塞进 context（成本爆炸、命中靠运气），要么用一个扁平向量库做语义检索（召回质量差、无法处理” 我要的是那一轮的那一行” 这种精确问题）。一句话：它们都在用” 图书馆索引” 的方式去管 Agent 的记忆，而不是用” 人脑分层记忆” 的方式。

腾讯云开源的 TencentDB Agent Memory 给出了一个截然不同的解法：用 4 层渐进式流水线（4-tier progressive pipeline）让 Agent 拥有” 会分层的大脑”。本文就把它拆开讲清楚。

二、项目背景：腾讯云为什么做这个？

TencentDB Agent Memory 最早是为了解决 OpenClaw（腾讯内部一个长程任务执行框架）上的” 上下文膨胀 + 长期偏好丢失” 问题。它的设计目标写得很直白：

Memory is not about hoarding everything in the AI — it is about sparing humans from having to repeat themselves.
Let the Agent remember what should be remembered, so people can focus on judgment, creation, and work that truly matters.

翻译过来：记忆的目的不是把一切塞进 AI 上下文，而是让人类不用反复说同一句话。它同时拒绝两个极端：

  1. 暴力堆历史：把每一轮工具调用的完整日志都喂进 prompt；
  2. 不可逆的总结压缩：用 LLM 把 100 轮对话总结成 1 段，丢掉细节。

它要的是第三种方案：分层 + 符号化 —— 把” 原文” 和” 结构” 分开存，把” 细节” 和” 摘要” 分层管理，Agent 既能用几百 token 把握全局，又能用 node_id 在毫秒内钻回原始证据。

三、核心功能：4 层渐进式流水线

整个系统由两大支柱构成 ——Memory Layering（分层） 和 Symbolic Memory（符号化）—— 共同形成 4 层结构。

1. 短期记忆分层：raw → summary → mermaid canvas

Agent 的工作记忆（working memory）按三层切：

层级 形态 作用 存储位置
底层 原始工具输出（refs/*.md） 保留完整证据 数据库 / 文件系统
中层 步骤级摘要（jsonl） 压缩冗余、保留时序 数据库
顶层 Mermaid 状态图（state machine） 几百 token 把握全局 Markdown 文件

Agent 推理时只看顶层 Mermaid 图（几百 token），出错时通过 node_id 一键钻回底层原始日志。这就是论文里常说的 “Progressive Disclosure”（渐进式披露） —— 上下文按需展开，不一次性倾倒。

2. 长期记忆分层：L0 → L1 → L2 → L3 语义金字塔

长期偏好按语义粒度分为 4 层（Semantic Pyramid）：

1
2
3
4
L3 Persona   ←  用户画像：技术栈、风格、习惯（每天都会用）
L2 Scenario  ←  场景块：某个具体任务的处理流程
L1 Atom      ←  原子事实：一条独立的知识点
L0 Conversation ← 原始对话

日常推荐走 L3（” 你是 Go 后端”），需要细节时钻 L1（” 上次那个 webhook 重试逻辑是怎么写的”），可追溯到 L0 原文。这是一个完全可审计的金字塔，每一层都保留通往下一层的精确指针。

3. 符号化记忆：Mermaid Canvas

这是整个系统最具特色的设计。Mermaid 状态图 是一种” 对 LLM 极友好” 的高密度符号语言：

1
2
3
4
5
6
7
8
graph LR
  A[用户提问] --> B{是否需要工具?}
  B -->|是| C[调用搜索]
  B -->|否| D[直接回答]
  C --> E[解析结果]
  E --> F{信息够?}
  F -->|否| C
  F -->|是| G[生成答案]

相比自然语言，Mermaid 在表达状态转移、流程分支、节点关系时密度高 5-10 倍。把 Agent 任务流画成 Mermaid 后，几十个 token 就能装下原本需要几千 token 描述的流程。配合 node_id 定位，Agent 能用极小成本保持” 我刚才在哪个状态、接下来该跳到哪个状态”。

4. 异构存储：底层数据库，顶层 Markdown

  • 底层（事实、日志、追踪）→ SQLite + sqlite-vec 等数据库，支持全文检索；
  • 顶层（人设、场景、Canvas）→ 人读得懂的 Markdown 文件，方便人工审查和二次编辑。

设计哲学很清晰：下层保证据，上层保结构。

四、实战示例：从 0 跑起来

下面用 OpenClaw 跑一遍最简单的 demo（默认走本地 SQLite + sqlite-vec，零外部 API 依赖）。

第 1 步：装插件

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

第 2 步：启用（零配置）

编辑 ~/.openclaw/openclaw.json：

1
2
3
4
5
6
7
{
  "plugins": {
    "memory-tencentdb": {
      "enabled": true
    }
  }
}

第 3 步：开启短期压缩（v0.3.4+）

1
2
3
4
5
6
7
8
9
{
  "plugins": {
    "memory-tencentdb": {
      "config": {
        "offload": { "enabled": true }
      }
    }
  }
}

第 4 步：注册 slot + 应用 runtime patch

1
2
3
4
5
{
  "plugins": {
    "slots": { "contextEngine": ["memory-tencentdb"] }
  }
}
1
bash scripts/openclaw-after-tool-call-messages.patch.sh

至此 Agent 已经具备 4 层记忆。全部数据存本地，不发任何外部 API—— 这点对企业内网部署至关重要。

如果你用 Hermes，可以直接跑官方 Docker 镜像（hermes-agent + memory_tencentdb 一体化打包，默认 8420 端口），named volume 持久化数据。

五、Benchmark 数字：是真的还是吹的？

这是最硬核的部分 —— 腾讯在多个长程任务基准上跑了对比，结果非常显著：

记忆能力 基准 OpenClaw 原生 接入本插件后 成功率 Δ Token 用量 Δ
短期 WideSearch 33% 50% +51.52% −61.38%
短期 SWE-bench（50 连续任务） 58.4% 64.2% +9.93% −33.09%
短期 AA-LCR 44.0% 47.5% +7.95% −30.98%
长期 PersonaMem 48% 76% +59% —

两个亮点：

  1. WideSearch 上 token 用量从 2.2 亿砍到 8564 万（−61%），成功率从 33% 拉到 50%（+52%）—— 这是非常戏剧性的提升，因为它证明” 分层 + 符号化” 在复杂多步搜索任务上同时解决了成本和质量两个问题。
  2. PersonaMem 从 48% 拉到 76%（+59%）—— 长期个性化记忆一直是 Agent 的痛点，能在标准基准上拿到这个数字，说明 4 层金字塔的人设提取是真实有效的。

注意：这些数据是在连续 50 轮长程会话下测的，不是单轮隔离开来测 —— 这才是真实生产场景。

六、适用场景与限制

适合用

  • 长程任务执行：连续 10 轮以上的代码生成、运维操作、数据分析；
  • 多轮个性化助手：每天会用的写作助手、编程助手、客服机器人，需要记住用户偏好；
  • 企业内网 / 数据敏感场景：完全本地化，没有 token 外发风险；
  • 成本敏感场景：WideSearch 这类高 token 任务用本插件能直接砍掉一半以上费用。

不适合用

  • 单轮问答 / 一次性 RAG：用本插件属于杀鸡用牛刀，普通 RAG 即可；
  • 非 LLM 的纯规则系统：用不到记忆能力；
  • 超大规模分布式协作（100+ Agent）：当前实现更偏向单 Agent 长期记忆，多 Agent 共享记忆需要扩展。

已知边界

  • 当前依赖 OpenClaw / Hermes 框架（v0.3.6），其他框架接入需要自己写适配层；
  • 短期压缩对结构化任务（代码、表格）效果好，对长篇自然语言对话压缩率略低；
  • 4 层之间的指针维护需要保证一致性，目前靠文件系统 + 数据库联合约束。

七、总结：为什么这件事重要？

TencentDB Agent Memory 不是又一套” 向量记忆 + RAG”—— 它重新定义了 Agent 记忆的物理结构。

它做的最关键的一步，是把” 原文” 和” 结构” 分开存，把” 细节” 和” 摘要” 分层管。这其实和人脑的记忆机制是高度同构的：人不会把 10 年前的所有对话原封不动塞进工作记忆，而是记住” 那张图、那个流程、那个人说过的那句话”——TencentDB 在做的事情，本质上是在工程上复刻了人脑的分层记忆。

从更宏观的角度看，这是 Agent 基础设施层的关键进化。未来 12 个月里，所有严肃的 Agent 框架都会引入某种形式的” 分层 + 符号化” 记忆 —— 因为大家都会撞上 token 成本墙和长任务可靠性墙。腾讯云这次把方案直接开源 + MIT 协议，相当于给整个行业打了个样板。

如果你正在做 Agent 产品，强烈建议花 1 小时把 README 读一遍 —— 它可能帮你省下未来 6 个月的探索时间。

延伸阅读：