腾讯开源 Agent Memory：上下文卸载 + Mermaid 任务画布
腾讯开源 Agent Memory：上下文卸载 + Mermaid 任务画布
本文目标：理解 TencentDB Agent Memory 的核心设计——上下文卸载与 Mermaid 任务画布如何协同工作，并完成一个基于通义千问 + OpenClaw 的可运行 Demo
1. 问题与背景
2026 年，Agent 不再是 Demo 里的玩具。代码开发 Agent 一次任务可能触发 50+ 次工具调用，网页搜索 Agent 单轮就拉回数万字原始 HTML，研究分析 Agent 的上下文里堆满了中间推理和日志——每多塞一段信息，就是 Token 消耗和推理质量的双重损失。
具体来说，现有 Agent 在长任务中面临三个致命问题：
| 问题 | 表现 | 根因 |
|---|---|---|
| 跨会话断裂 | 昨天调整的代码规范，今天新开会话全忘 | 记忆不跨 Session |
| 事实与偏好混淆 | "我用 TypeScript"和"帮我查天气"被同等对待 | 缺乏信息分层 |
| 上下文膨胀 | 20 次工具调用后上下文窗口已满，模型注意力衰减 | 线性堆砌历史 |
腾讯云数据库团队在 2026 年 5 月 13 日正式开源了 TencentDB Agent Memory——一套面向 AI Agent 的分层记忆引擎，核心思路是用"上下文卸载 + Mermaid 任务画布"把长任务过程转化为可管理的结构化记忆。
核心数据（超长 Session 实验）：
- Token 消耗最高节省 61.38%
- 任务通过率从 33% 提升到 50%，相对提升 51.52%
- PersonaMem 准确率从 48% 提升到 76%
这套方案已作为 OpenClaw 插件在生产环境验证，MIT 协议开源。本文将从原理拆解到实操跑通，完整覆盖。
2. 核心设计：四层分层记忆
TencentDB Agent Memory 不把"记忆"当成一段摘要，而是构建了一个四层渐进式记忆管道：
L3 用户画像层 ← 持续蒸馏出稳定的长期画像
↑
L2 场景归纳层 ← 按任务自动聚合
↑
L1 原子记忆层 ← 自动提取事实、偏好、约束、阶段结论
↑
L0 原始对话层 ← 全量保留每一轮交互
每一层只做一件事，层与层之间通过 提取→聚合→蒸馏 的管道连接。这意味着：
- L0 是"证据"，绝不丢失
- L1 是"事实"，可检索
- L2 是"场景"，可导航
- L3 是"画像"，可复用
任何一层都可以独立升级或替换，Agent 不会因为换了一次会话就忘掉你是谁。
可溯源是这套设计的底线。任何一段摘要都不是"不可逆的黑盒"，开发者可以沿链路逐层追溯：
高层符号（Persona/画布）→ 中层索引（Scenario/JSONL）→ 底层原文（L0 Conversation/refs）
3. 核心机制：上下文卸载 + Mermaid 任务画布
这是本文的重点。长任务中最消耗 Token 的不是用户指令，而是工具调用的中间结果——网页内容、代码日志、报错堆栈。一段报错日志动辄数千 Token，几十次工具调用下来，上下文窗口已被垃圾信息塞满。
3.1 上下文卸载（Context Offloading）
核心思想：把完整信息搬到外部文件系统，上下文里只保留摘要和索引。
原始工具结果（数万 Token）
│
├── 完整内容 → 外部文件系统（refs/*.md）
│
└── 摘要 + 索引 → 保留在 Agent 上下文中（数百 Token）
工具调用完成后，网页内容、日志和中间结果不会继续长期占用上下文窗口，而是转移到外部文件系统。上下文中仅保留摘要和索引信息，需要时按需恢复。
对比传统做法：
| 传统做法 | 上下文卸载 | |
|---|---|---|
| 网页搜索结果 | 全部塞进上下文 | 存文件，上下文只放摘要 |
| 报错日志 | 全部保留 | 存文件，只保留关键错误类型 |
| 代码生成中间产物 | 累积 | 存文件，按 node_id 索引 |
| Token 趋势 | 线性增长 | 接近常数 |
3.2 Mermaid 任务画布
光卸载不够。Agent 还需要知道自己"走到哪了"。
20 次工具调用之后，上下文里堆着一长串线性历史。Agent 能看到"做过什么"，但不容易判断哪些是并行分支、哪些步骤有前置依赖、当前处于哪个阶段。
流水账适合记录，地图适合导航。
腾讯云团队用 Mermaid Flowchart 把任务执行过程组织成一张可导航的任务画布。选择 Mermaid 有三个关键理由：
- LLM 天然可读写——Mermaid 是 GitHub 广泛使用的图描述语言，主流大模型的训练数据中大量包含 Mermaid 语法，理解和生成都不是问题
- 纯文本格式——不需要序列化/反序列化，直接拼接进 Prompt
- 人类可读——开发者可以直接渲染查看任务状态
画布中的每个节点携带 node_id，形成如下结构：
Agent 看这张画布就能直接判断：当前在"撰写初稿"阶段，前置依赖是"搜索资料"和"读取文档A/B"，下一步是"交付结果"。
需要核对细节时，直接 grep 画布上的 node_id 即可瞬间找回完整原文。
3.3 协同工作流
上下文卸载和任务画布不是两套独立方案，而是协同运作：
┌─────────────────────────────┐
工具调用原始结果 │ 1. 完整内容 → 外部存储 │
（数万 Token） │ 2. 提取关系 → Mermaid 画布 │
│ 3. 摘要+画布 → Agent 上下文 │
└─────────────────────────────┘
│
Agent 上下文（仅数百 Token）
├── 任务画布（含 node_id）
└── 关键摘要
│
需要细节？← grep node_id → 原文
这套机制实现了三个目标：
- Token 不线性增长：上下文大小基本恒定
- 结构可导航：Agent 知道自己处于任务图谱的哪个位置
- 100% 可追溯：通过 node_id 随时找回原始证据
4. 实操：OpenClaw + 通义千问接入 Agent Memory
接下来跑一个可运行的 Demo。我们使用阿里云百炼平台的通义千问（Qwen）作为模型后端，OpenClaw 作为 Agent 框架，接入 TencentDB Agent Memory。
4.1 环境准备
前置条件：
- Python 3.10+
- Node.js 18+
- 阿里云百炼 API Key（https://bailian.console.aliyun.com 申请）
- OpenClaw 已安装
安装 OpenClaw：
# 安装 OpenClaw
npm install -g openclaw
# 验证安装
openclaw --version
安装 Agent Memory 插件：
# 一行安装
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
# 重启 gateway
openclaw gateway restart
4.2 配置通义千问模型后端
编辑 ~/.openclaw/openclaw.json：
{
"model": {
"provider": "openai-compatible",
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKey": "你的百炼API-KEY",
"model": "qwen-plus"
},
"memory-tencentdb": {
"enabled": true
}
}
配置说明：
baseUrl：阿里云百炼的兼容 OpenAI 接口地址model：推荐使用qwen-plus（性价比高）或qwen-max（能力更强）memory-tencentdb.enabled: true：启用记忆插件，默认使用本地 SQLite + sqlite-vec 后端
4.3 启用短期记忆压缩
{
"memory-tencentdb": {
"enabled": true,
"config": {
"offload": {
"enabled": true
}
}
}
}
offload.enabled: true 开启上下文卸载功能，工具调用结果会自动卸载到外部文件，上下文只保留 Mermaid 任务画布。
4.4 注册上下文卸载槽位
让 OpenClaw 把上下文卸载请求路由到 Agent Memory 插件：
{
"plugins": {
"slots": {
"contextEngine": "memory-tencentdb"
}
}
}
4.5 运行验证
启动 OpenClaw 后，执行一个多步任务来验证记忆机制是否生效：
# 进入交互模式
openclaw chat
# 模拟一个长任务
> 帮我调研"阿里云百炼平台最新的 Agent 开发能力"，
> 搜索 5 篇相关文章，每篇提取核心观点，最后生成一份对比表格。
观察 Agent 执行过程：
- 每次工具调用（网页搜索、内容抓取）完成后，完整结果被卸载到外部文件
- 上下文中逐步生成一张 Mermaid 任务画布，标记每个搜索步骤的完成状态
- 最后生成对比表格时，Agent 通过 node_id 按需回溯原文细节
验证记忆跨会话保持：
# 结束当前会话，开启新会话
/exit
openclaw chat
> 刚才调研的阿里云百炼 Agent 能力，把结论写成一篇 Markdown 报告。
如果 Agent Memory 工作正常，Agent 会基于之前记忆中的信息继续完成任务，而不是从头开始。
4.6 查看记忆数据
Agent Memory 默认使用 SQLite 存储，可以直接查看：
# 查看记忆数据库位置
ls ~/.openclaw/data/memory/
# 典型文件：
# memory.db —— 主记忆库
# refs/ —— 卸载的原始工具结果
# scenarios/ —— 场景归纳
5. 验证结果与实验数据
腾讯云官方在四个公开评测集上同时跑通了两条曲线：Token 下降，完成率上升。
| 场景 | Token 节省 | 成功率提升 | 说明 |
|---|---|---|---|
| 网页搜索 | 最高 61.38% | 相对 +52% | 长链路多轮搜索场景 |
| 代码修复 | 最高 33% | 完成率 +10% | 中间产物多的编程任务 |
| 复杂长文档 | 最高 31% | 准确率 +8% | 长文档分析场景 |
| PersonaMem | — | 48%→76% | 用户画像记忆准确性 |
为什么不同场景节省幅度差异大？
核心变量是工具调用中间结果的膨胀程度。网页搜索场景中，每次搜索返回数千字 HTML 原文，卸载效果最明显；代码修复场景的中间产物相对精简，节省幅度略低。
6. 面试要点
如果你正在准备 Agent/大模型相关岗位面试，以下知识点高频出现：
Q1：Agent 长任务中 Token 爆炸的根本原因是什么？
工具调用的中间结果（网页内容、代码日志、报错堆栈）会被线性堆砌进上下文窗口。每次工具调用都在往上下文中追加新内容，导致 Token 消耗线性增长、模型注意力衰减。
Q2：上下文卸载和常规摘要压缩有什么区别？
常规摘要压缩会丢失原始信息，是不可逆的。上下文卸载将完整信息保留在外部存储，上下文中只放索引和摘要，通过 node_id 可以 100% 追溯到原文。
Q3：Mermaid 任务画布解决了什么问题？
解决了 Agent 在长任务中的"迷路"问题。线性历史是流水账，Agent 难以判断自己处于哪个阶段、哪些步骤有前置依赖。结构化任务画布提供了可导航的任务地图。
Q4：分层记忆（L0-L3）的设计哲学是什么？
低层保留证据，高层保留结构。每一层只做一件事，层间通过提取-聚合-蒸馏管道连接。任意一层可独立升级或替换，既保证了信息不丢失，又实现了高效检索。
7. 风险、边界与局限
| 维度 | 说明 |
|---|---|
| 适用场景 | 长任务（多轮工具调用）、多 Session 连续任务、需要用户画像沉淀的场景 |
| 不适用场景 | 简单单轮问答、对延迟极度敏感的场景（文件 I/O 有额外开销） |
| 存储成本 | 默认 SQLite 本地存储，大规模并发需评估是否切换到云存储后端 |
| 模型要求 | 需要模型具备 Mermaid 语法的读写能力，主流大模型（通义千问、DeepSeek、GPT-4 等）均可 |
| 框架支持 | 目前官方插件支持 OpenClaw 和 Hermes，其他框架需自行适配 |
8. 总结
TencentDB Agent Memory 解决的是一个看似简单但长期被忽视的问题：Agent 不是记不住，而是被信息淹没了。
- 上下文卸载：把膨胀的中间结果搬到外部存储，上下文保持轻量
- Mermaid 任务画布：把线性历史折叠为结构化地图，Agent 始终知道自己走到哪
- 四层分层记忆：证据→事实→场景→画像，低层保留证据，高层保留结构
- 100% 可追溯：node_id 索引确保任何摘要都可以还原为原文
在 Agent 工程化加速落地的 2026 年，记忆不再是"加分项"，而是决定 Agent 能否从 Demo 走向生产的标配组件。这套方案 MIT 开源，与 OpenClaw、Hermes 深度集成，值得每个 Agent 开发者关注和试用。
参考资料
- TencentDB Agent Memory 正式开源：让 Agent 沉淀经验，让人专注创造 —— 腾讯云官方原文
- GitHub 仓库：TencentDB-Agent-Memory
- Agent Memory 节省 61% Token 提升 52% 成功率的诀窍：Mermaid 无限画布 × 上下文卸载 —— 腾讯技术工程详细分析
- OpenClaw 官方文档
- 阿里云百炼大模型平台
- NPM 包：@tencentdb-agent-memory/memory-tencentdb
感谢阅读，记得点赞、关注、收藏，欢迎各位评论区交流！！！
欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！
更多推荐
10
0- 0
已为社区贡献6条内容
所有评论(0)