腾讯开源 Agent Memory：上下文卸载 + Mermaid 任务画布

本文目标：理解 TencentDB Agent Memory 的核心设计------上下文卸载与 Mermaid 任务画布如何协同工作，并完成一个基于通义千问 + OpenClaw 的可运行 Demo

文章目录

[腾讯开源 Agent Memory：上下文卸载 + Mermaid 任务画布](#腾讯开源 Agent Memory：上下文卸载 + Mermaid 任务画布)
- [1. 问题与背景](#1. 问题与背景)
- [2. 核心设计：四层分层记忆](#2. 核心设计：四层分层记忆)
- [3. 核心机制：上下文卸载 + Mermaid 任务画布](#3. 核心机制：上下文卸载 + Mermaid 任务画布)
- - [3.1 上下文卸载（Context Offloading）](#3.1 上下文卸载（Context Offloading）)
  - [3.2 Mermaid 任务画布](#3.2 Mermaid 任务画布)
  - [3.3 协同工作流](#3.3 协同工作流)
- [4. 实操：OpenClaw + 通义千问接入 Agent Memory](#4. 实操：OpenClaw + 通义千问接入 Agent Memory)
- - [4.1 环境准备](#4.1 环境准备)
  - [4.2 配置通义千问模型后端](#4.2 配置通义千问模型后端)
  - [4.3 启用短期记忆压缩](#4.3 启用短期记忆压缩)
  - [4.4 注册上下文卸载槽位](#4.4 注册上下文卸载槽位)
  - [4.5 运行验证](#4.5 运行验证)
  - [4.6 查看记忆数据](#4.6 查看记忆数据)
- [5. 验证结果与实验数据](#5. 验证结果与实验数据)
- [6. 面试要点](#6. 面试要点)
- [7. 风险、边界与局限](#7. 风险、边界与局限)
- [8. 总结](#8. 总结)
- 参考资料

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，形成如下结构：
#mermaid-svg-Yw81BlTTl3yfqhHl{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Yw81BlTTl3yfqhHl .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Yw81BlTTl3yfqhHl .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Yw81BlTTl3yfqhHl .error-icon{fill:#552222;}#mermaid-svg-Yw81BlTTl3yfqhHl .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Yw81BlTTl3yfqhHl .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Yw81BlTTl3yfqhHl .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Yw81BlTTl3yfqhHl .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Yw81BlTTl3yfqhHl .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Yw81BlTTl3yfqhHl .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Yw81BlTTl3yfqhHl .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Yw81BlTTl3yfqhHl .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Yw81BlTTl3yfqhHl .marker.cross{stroke:#333333;}#mermaid-svg-Yw81BlTTl3yfqhHl svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Yw81BlTTl3yfqhHl p{margin:0;}#mermaid-svg-Yw81BlTTl3yfqhHl .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Yw81BlTTl3yfqhHl .cluster-label text{fill:#333;}#mermaid-svg-Yw81BlTTl3yfqhHl .cluster-label span{color:#333;}#mermaid-svg-Yw81BlTTl3yfqhHl .cluster-label span p{background-color:transparent;}#mermaid-svg-Yw81BlTTl3yfqhHl .label text,#mermaid-svg-Yw81BlTTl3yfqhHl span{fill:#333;color:#333;}#mermaid-svg-Yw81BlTTl3yfqhHl .node rect,#mermaid-svg-Yw81BlTTl3yfqhHl .node circle,#mermaid-svg-Yw81BlTTl3yfqhHl .node ellipse,#mermaid-svg-Yw81BlTTl3yfqhHl .node polygon,#mermaid-svg-Yw81BlTTl3yfqhHl .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Yw81BlTTl3yfqhHl .rough-node .label text,#mermaid-svg-Yw81BlTTl3yfqhHl .node .label text,#mermaid-svg-Yw81BlTTl3yfqhHl .image-shape .label,#mermaid-svg-Yw81BlTTl3yfqhHl .icon-shape .label{text-anchor:middle;}#mermaid-svg-Yw81BlTTl3yfqhHl .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Yw81BlTTl3yfqhHl .rough-node .label,#mermaid-svg-Yw81BlTTl3yfqhHl .node .label,#mermaid-svg-Yw81BlTTl3yfqhHl .image-shape .label,#mermaid-svg-Yw81BlTTl3yfqhHl .icon-shape .label{text-align:center;}#mermaid-svg-Yw81BlTTl3yfqhHl .node.clickable{cursor:pointer;}#mermaid-svg-Yw81BlTTl3yfqhHl .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Yw81BlTTl3yfqhHl .arrowheadPath{fill:#333333;}#mermaid-svg-Yw81BlTTl3yfqhHl .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Yw81BlTTl3yfqhHl .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Yw81BlTTl3yfqhHl .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Yw81BlTTl3yfqhHl .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Yw81BlTTl3yfqhHl .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Yw81BlTTl3yfqhHl .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Yw81BlTTl3yfqhHl .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Yw81BlTTl3yfqhHl .cluster text{fill:#333;}#mermaid-svg-Yw81BlTTl3yfqhHl .cluster span{color:#333;}#mermaid-svg-Yw81BlTTl3yfqhHl div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Yw81BlTTl3yfqhHl .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Yw81BlTTl3yfqhHl rect.text{fill:none;stroke-width:0;}#mermaid-svg-Yw81BlTTl3yfqhHl .icon-shape,#mermaid-svg-Yw81BlTTl3yfqhHl .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Yw81BlTTl3yfqhHl .icon-shape p,#mermaid-svg-Yw81BlTTl3yfqhHl .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Yw81BlTTl3yfqhHl .icon-shape .label rect,#mermaid-svg-Yw81BlTTl3yfqhHl .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Yw81BlTTl3yfqhHl .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Yw81BlTTl3yfqhHl .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Yw81BlTTl3yfqhHl :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 📋 理解任务：分析用户需求
🔍 搜索资料
📄 读取文档A
📄 读取文档B
✍️ 撰写初稿
✅ 交付结果

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：

bash 复制代码

# 安装 OpenClaw
npm install -g openclaw

# 验证安装
openclaw --version

安装 Agent Memory 插件：

bash 复制代码

# 一行安装
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb

# 重启 gateway
openclaw gateway restart

4.2 配置通义千问模型后端

编辑 ~/.openclaw/openclaw.json：

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 启用短期记忆压缩

json 复制代码

{
  "memory-tencentdb": {
    "enabled": true,
    "config": {
      "offload": {
        "enabled": true
      }
    }
  }
}

offload.enabled: true 开启上下文卸载功能，工具调用结果会自动卸载到外部文件，上下文只保留 Mermaid 任务画布。

4.4 注册上下文卸载槽位

让 OpenClaw 把上下文卸载请求路由到 Agent Memory 插件：

json 复制代码

{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

4.5 运行验证

启动 OpenClaw 后，执行一个多步任务来验证记忆机制是否生效：

bash 复制代码

# 进入交互模式
openclaw chat

# 模拟一个长任务
> 帮我调研"阿里云百炼平台最新的 Agent 开发能力"，
> 搜索 5 篇相关文章，每篇提取核心观点，最后生成一份对比表格。

观察 Agent 执行过程：

每次工具调用（网页搜索、内容抓取）完成后，完整结果被卸载到外部文件
上下文中逐步生成一张 Mermaid 任务画布，标记每个搜索步骤的完成状态
最后生成对比表格时，Agent 通过 node_id 按需回溯原文细节

验证记忆跨会话保持：

bash 复制代码

# 结束当前会话，开启新会话
/exit
openclaw chat

> 刚才调研的阿里云百炼 Agent 能力，把结论写成一篇 Markdown 报告。

如果 Agent Memory 工作正常，Agent 会基于之前记忆中的信息继续完成任务，而不是从头开始。

4.6 查看记忆数据

Agent Memory 默认使用 SQLite 存储，可以直接查看：

bash 复制代码

# 查看记忆数据库位置
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

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