---

腾讯开源 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 有三个关键理由：

1. LLM 天然可读写——Mermaid 是 GitHub 广泛使用的图描述语言，主流大模型的训练数据中大量包含 Mermaid 语法，理解和生成都不是问题
2. 纯文本格式——不需要序列化/反序列化，直接拼接进 Prompt
3. 人类可读——开发者可以直接渲染查看任务状态

画布中的每个节点携带 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 执行过程：

1. 每次工具调用（网页搜索、内容抓取）完成后，完整结果被卸载到外部文件
2. 上下文中逐步生成一张 Mermaid 任务画布，标记每个搜索步骤的完成状态
3. 最后生成对比表格时，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

---

感谢阅读，记得点赞、关注、收藏，欢迎各位评论区交流！！！