编程 TencentDB Agent Memory 深度解析：让 AI Agent 拥有真正「记忆」的分层架构革命——从61.38% Token节省到四层金字塔的技术内幕

2026-05-18 15:13:25 +0800 CST views 4

TencentDB Agent Memory 深度解析：让 AI Agent 拥有真正「记忆」的分层架构革命——从61.38% Token节省到四层金字塔的技术内幕

当你的 AI 助手每天都要你重新解释一遍项目背景和代码规范，当长任务跑到一半 Agent 开始「健忘」重复分析，当跨会话的偏好总是被清零重来——这些问题的根源不是模型不够聪明，而是记忆架构从根本上就错了。腾讯云刚刚开源的 TencentDB Agent Memory，用一套四层金字塔架构，给出了一个让人眼前一亮的答案。

一、为什么 AI Agent 总是「健忘」？

如果你用过任何 AI 编程助手超过一周，一定遇到过这样的场景：

昨天反复确认的代码规范，今天新开会话又全忘了
任务跑到一半，Agent 开始重复分析已经处理过的问题
你说「用 TypeScript」，Agent 下次又问你用 JavaScript 还是 TypeScript

这些问题的本质是：当下主流的记忆方案都在做同一件事——把对话历史压缩成一段摘要，下次会话时注入上下文。这在短对话里够用，但在真实的长周期任务中，这套方案有三个致命缺陷：

1.1 跨会话断裂

Agent 的会话边界是硬切分的。你在昨天会话里花半小时确认的代码风格、项目约束、输出格式，今天新开会话全部归零。这不是模型的错，是存储架构压根没考虑「持久化」这件事。

1.2 事实与偏好混淆

用户说「我用 TypeScript」和用户说「帮我查一下天气」，这两条信息的价值完全不同——前者是长期偏好，后者是瞬时指令。但在现有的向量存储方案里，它们被同等对待，都被切碎成向量碎片，塞进同一个扁平的数据库里。

1.3 上下文膨胀

任务越长，堆进上下文的历史信息越多。Token 消耗持续攀升，模型的注意力也在衰减。很多「压缩方案」能砍 Token，但砍完之后任务跑偏、遗忘、重复分析的问题更严重了。

问题的根源不是「记不住」，而是「记不对」——该记的没记住，不该记的塞满了一堆。

二、TencentDB Agent Memory 的核心架构：四层金字塔

腾讯云数据库团队开源的这套方案，核心思路非常清晰：不同粒度的信息，应该放在不同的「楼层」里，而不是全部堆在一层平面上。

这套架构被形象地称为「记忆金字塔」：

┌─────────────────────────────────┐
│         L3 用户画像层           │  ← 长期偏好、工作风格、稳定特征
│      (persona.md)              │
├─────────────────────────────────┤
│         L2 场景归纳层           │  ← 任务级经验块、场景模板
│      (scenario/*.md)           │
├─────────────────────────────────┤
│         L1 原子记忆层           │  ← 事实、偏好、约束、阶段结论
│      (memory/*.jsonl)          │
├─────────────────────────────────┤
│         L0 原始对话层           │  ← 全量对话历史
│      (conversation/*.md)      │
└─────────────────────────────────┘

每一层只做一件事，层与层之间通过提取-聚合-蒸馏的管道连接。让我们逐层拆解。

2.1 L0 原始对话层：全量保留，只存不压

这一层非常简单粗暴：每一轮交互的原文本，完整保存。

文件格式是 Markdown，按会话分文件：

~/.openclaw/memory-tdai/conversations/
  ├── 2026-05-14_session_abc123.md
  ├── 2026-05-15_session_def456.md
  └── ...

为什么不一上来就压缩？因为压缩会丢失证据。当上层记忆出现偏差时，你需要能够追溯到最原始的对话，找到「这个结论到底是从哪来的」。

L0 的设计原则是：宁可多存，不可丢据。

2.2 L1 原子记忆层：自动提取「有意义的信息」

从 L0 到 L1，是第一次质变。系统会自动从对话中提取四类「原子」：

事实 (Fact)：「项目使用 TypeScript 5.0」「数据库是 PostgreSQL 18」
偏好 (Preference)：「输出用中文」「代码风格用两空格缩进」
约束 (Constraint)：「不要使用 any 类型」「接口必须有错误处理」
阶段结论 (Milestone)：「已完成用户认证模块」「性能问题定位到数据库连接池」

提取过程由 LLM 驱动，但存储格式是结构化的 JSONL：

{"type":"preference","content":"输出用中文","ts":"2026-05-14T10:30:00Z","session":"abc123"}
{"type":"fact","content":"项目使用TypeScript 5.0","ts":"2026-05-14T10:35:00Z","session":"abc123"}
{"type":"constraint","content":"不要使用any类型","ts":"2026-05-14T10:40:00Z","session":"abc123"}

这一层的关键是去重和冲突检测。如果用户在不同会话里对同一件事有不同表述，系统会标记冲突，而不是简单覆盖。

2.3 L2 场景归纳层：把原子聚合成「经验块」

L1 的原子是零散的，L2 负责把它们聚合成有意义的「场景」。比如你连续三次在做 API 开发任务时都提到了「返回值必须有统一格式」，系统会自动归纳出一个场景块：

# 场景：API 开发规范

## 核心约束
- 返回值使用 `{ code, data, message }` 格式
- 错误码使用 5 位数字
- 分页接口必须有 `hasMore` 字段

## 来源会话
- 2026-05-14 session_abc123
- 2026-05-16 session_def456
- 2026-05-18 session_ghi789

## 生成的原子数量：12
## 最后更新：2026-05-18T14:30:00Z

场景层的价值在于：把零散的经验组织成可复用的模板。当你下次启动一个 API 开发任务时，Agent 不需要再从零学习你的规范，直接加载这个场景块即可。

2.4 L3 用户画像层：稳定的长期特征

金字塔的塔尖，是用户画像。系统会定期从 L2 场景中蒸馏出最稳定、最通用的特征：

# 用户画像

## 技术背景
- 全栈开发者，主语言 TypeScript
- 熟悉 React/Vue，后端倾向 Go
- 数据库偏好 PostgreSQL

## 工作风格
- 输出用中文，代码注释用英文
- 偏好详细的代码解释
- 重视测试覆盖率

## 稳定偏好
- 两空格缩进
- 函数名使用 camelCase
- 接口命名加 I 前缀

画像层的更新频率最低，但稳定性最高。它解决的是「你是谁」的问题——Agent 只需要加载这个文件，就立刻知道你的技术栈、风格偏好、长期约束。

三、短期记忆的革命：符号化记忆与 Mermaid 画布

上面说的是长期记忆，但 Agent 还有一个更紧迫的问题：单次长任务里的信息过载。

一个真实的编程任务可能产生几十万 Token 的日志：搜索结果、代码片段、错误堆栈、工具输出……全塞进上下文，Token 直接爆炸；不塞，Agent 又会「失明」。

TencentDB Agent Memory 的解决方案是：符号化记忆 + Mermaid 任务画布。

3.1 传统方案的困境：要么全丢，要么全塞

传统方案有三种：

全量保留：把所有历史塞进上下文。问题是 Token 线性增长，模型注意力衰减。
摘要压缩：把历史压缩成摘要。问题是丢失细节，出错时无法追溯。
向量检索：把历史切片存入向量库，按需检索。问题是检索不精确，且丢失结构信息。

三种方案都在「全丢」和「全塞」之间摇摆，没有真正解决问题。

3.2 符号化记忆：用 Mermaid 编码任务状态

TencentDB Agent Memory 的方案非常聪明：把原始日志卸载到外部文件，只在上下文里保留一个轻量的「任务地图」。

这个地图用 Mermaid 语法编码：

graph TD
    A[用户请求: 实现用户认证] --> B[搜索认证方案]
    B --> C[选择 JWT 方案]
    C --> D[实现登录接口]
    D --> E{测试通过?}
    E -->|是| F[完成]
    E -->|否| G[调试错误]
    G --> D
    
    style A fill:#e1f5fe
    style F fill:#c8e6c9
    style G fill:#ffcdd2

这个 Mermaid 图只占几百个 Token，但它编码了整个任务的状态机。Agent 可以：

知道当前在哪一步
知道哪些路径已经走过
知道哪里有错误需要回溯

3.3 node_id 追溯：保留完整证据链

那原始日志去哪了？全部存在外部文件里：

~/.openclaw/memory-tdai/refs/
  ├── node_A.md    # 用户原始请求
  ├── node_B.md    # 搜索结果（完整）
  ├── node_C.md    # JWT 方案详情
  ├── node_D.md    # 实现代码
  ├── node_E.md    # 测试结果
  └── node_G.md    # 错误堆栈

每个 Mermaid 节点都有一个 node_id，Agent 需要查看细节时，通过 grep node_id 即可定位到原始文件。

这就是「符号化记忆」的精髓：上下文只保留结构，细节按需追溯。

3.4 实测效果：最高节省 61.38% Token

在 OpenClaw 的生产环境测试中，这套方案的实测数据：

Benchmark	无插件成功率	加插件成功率	相对提升	无插件 Token	加插件 Token	Token 节省
WideSearch	33%	50%	+51.52%	221.31M	85.64M	-61.38%
SWE-bench	58.4%	64.2%	+9.93%	3474.1M	2375.4M	-33.09%
AA-LCR	44.0%	47.5%	+7.95%	112.0M	77.3M	-30.98%

两条曲线同时向上：Token 下降，完成率上升。 这是因为 Agent 的注意力不再被噪音稀释，而是聚焦在真正关键的信息上。

四、异构存储与全链路可溯源

记忆系统最怕的就是「黑盒化」——你能检索到结果，但不知道这个结果是从哪来的、为什么会被检索到。

4.1 双层存储策略

TencentDB Agent Memory 采用了异构存储策略：

底层（证据层）：SQLite + sqlite-vec，存储原始数据和向量索引，支持全文检索和语义检索。
顶层（结构层）：纯 Markdown 文件，人类可读、可编辑、可审计。

~/.openclaw/memory-tdai/
  ├── db/
  │   └── memory.db          # SQLite 数据库
  ├── conversations/          # L0 对话
  ├── memories/               # L1 原子
  ├── scenarios/              # L2 场景
  ├── persona.md              # L3 画像
  └── refs/                   # 短期记忆原始文件

为什么顶层用 Markdown 而不是数据库？因为可解释性。你可以直接打开 persona.md 查看系统对你画像的理解，可以直接编辑修正。这比从黑盒数据库里捞数据要直观得多。

4.2 全链路可溯源

从画像追溯到对话，有一条完整的链路：

L3 Persona → L2 Scenario → L1 Atom → L0 Conversation

每一步都有明确的文件和索引：

Persona 里提到「偏好 TypeScript」
点击进入来源场景 scenario/api_dev.md
场景里列出来源会话
打开会话文件，定位到具体对话

当检索出错时，你可以精确知道是哪一步出了问题，而不是对着一个黑盒的向量分数发呆。

五、技术实现细节：从安装到配置

5.1 一行安装（OpenClaw）

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

安装后，插件会自动：

捕获对话内容
触发 L1 提取（默认每 5 轮对话）
生成 L2 场景（默认每 50 条新记忆）
蒸馏 L3 画像（默认每 50 条新记忆）

5.2 Hermes Agent 一键启动（Docker）

如果你用的是 Hermes Agent，一条 Docker 命令即可：

docker run -d \
  --name hermes-memory \
  --restart unless-stopped \
  -p 8420:8420 \
  -e MODEL_API_KEY="your-api-key" \
  -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \
  -e MODEL_NAME="deepseek-v3.2" \
  -e MODEL_PROVIDER="custom" \
  -v hermes_data:/opt/data \
  agentmemory/hermes-memory:latest

镜像内置腾讯云 DeepSeek-V3.2 作为默认模型，支持 linux/amd64 和 linux/arm64 双架构。

5.3 配置参数详解

系统提供了三级配置：

Level 1 · 日常调优（覆盖 90% 场景）：

{
  "storeBackend": "sqlite",           // 存储后端
  "recall.strategy": "hybrid",        // 检索策略：keyword/embedding/hybrid
  "recall.maxResults": 5,             // 每次召回数量
  "pipeline.everyNConversations": 5,  // 每 N 轮触发 L1 提取
  "persona.triggerEveryN": 50         // 每 N 条新记忆触发画像更新
}

Level 2 · 高级调优（长任务/长会话）：

{
  "offload.enabled": true,                    // 启用短期记忆压缩
  "offload.mildOffloadRatio": 0.5,            // 温和压缩触发阈值
  "offload.aggressiveCompressRatio": 0.85,   // 激进压缩触发阈值
  "offload.mmdMaxTokenRatio": 0.2,           // Mermaid 注入 Token 预算
  "bm25.language": "zh"                       // 分词语言：zh/en
}

Level 3 · 运维级配置（自定义模型/远程嵌入）：

参见 openclaw.plugin.json 的完整参数说明。

六、与其他记忆方案的对比

6.1 vs. 传统向量存储

维度	向量存储	TencentDB Agent Memory
数据组织	扁平化，切碎的片段	分层金字塔，有结构
检索方式	纯向量相似度	BM25 + 向量 + RRF 混合
可解释性	黑盒，无法追溯	白盒，全链路溯源
长期记忆	无结构，检索混乱	四层架构，偏好/事实分离
短期记忆	全量塞上下文或丢弃	符号化，结构保留

6.2 vs. MemGPT / Letta

MemGPT 是目前最知名的 Agent 记忆框架之一，它的核心思路是模拟操作系统的内存管理，用「核心记忆」「工作记忆」「归档记忆」三层结构。

TencentDB Agent Memory 的不同之处：

四层 vs 三层：增加了「场景层」，把原子记忆聚合成可复用的经验块。
异构存储：顶层用 Markdown，底层用 SQLite，兼顾可读性和检索效率。
短期记忆方案：Mermaid 符号化是独创的，MemGPT 没有类似方案。
开箱即用：一行安装，零配置启动；MemGPT 需要更多配置工作。

6.3 vs. LangChain Memory

LangChain 的记忆模块更偏向「对话历史管理」，提供多种窗口策略（固定窗口、摘要窗口、向量检索等）。

TencentDB Agent Memory 的定位更底层：

LangChain Memory 解决「对话窗口」问题
TencentDB Agent Memory 解决「持久化记忆」问题

两者可以叠加使用，但如果你需要的是「Agent 长期记住我的偏好」，TencentDB Agent Memory 是更合适的选择。

七、生产环境验证：四大场景稳定收敛

这套方案已经在 OpenClay 的生产环境中验证，覆盖四类长链路任务：

编程任务：代码生成、重构、调试，跨会话保持代码风格一致性
调研任务：信息搜集、分析报告，避免重复搜索已处理的内容
文档分析：长文档理解、信息提取，保持输出格式稳定
工作流编排：多步骤任务自动化，任务状态不丢失

在 SWE-bench 的测试中，连续 50 个任务的 session，系统依然保持稳定，Token 消耗被控制在合理范围内。

八、为什么开源？腾讯的战略考量

腾讯云数据库团队选择开源这套方案，用意很明显：

「记忆这个产品远没有标准答案，比起做一个完美的方案，我们更想和开发者一起，把产品做得更丰富、更扎实、更可用。」

这套方案的几个设计决策，明显是为开源社区考虑的：

MIT 协议：最宽松的开源协议，商业友好
无外部依赖：SQLite + sqlite-vec，不需要部署额外的向量数据库
白盒可审计：所有记忆文件都是 Markdown，可以直接查看和编辑
多平台支持：OpenClaw 和 Hermes Agent 双平台适配

九、踩坑指南：生产环境部署建议

9.1 存储空间规划

L0 对话是全量存储的，如果对话量大，需要定期清理：

# 查看存储占用
du -sh ~/.openclaw/memory-tdai/

# 配置自动清理（Level 2 参数）
"capture.l0l1RetentionDays": 30  # 保留 30 天

9.2 检索策略选择

系统支持三种检索策略：

keyword：纯 BM25，适合精确匹配场景
embedding：纯向量检索，适合语义匹配场景
hybrid（推荐）：RRF 融合，综合两种优势

默认是 hybrid，但如果你发现检索结果不稳定，可以尝试切换策略观察效果。

9.3 性能调优

关键参数：

{
  "recall.timeoutMs": 5000,           // 检索超时，超时后跳过不影响对话
  "extraction.maxMemoriesPerSession": 20,  // 单次提取数量上限
  "pipeline.l1IdleTimeoutSeconds": 600     // 空闲多久后触发 L1 提取
}

如果系统响应变慢，优先检查 recall.timeoutMs 是否设置过短。

十、未来展望：记忆层的标准化

TencentDB Agent Memory 的开源，可能会推动一个趋势：记忆层正在成为 AI Agent 的「操作系统」的一部分。

回顾过去两年的发展：

2024：Agent 框架百花齐放（LangChain、AutoGPT、OpenAI Assistants API）
2025：工具协议标准化（MCP）
2026：记忆层标准化元年？

腾讯的这套方案，至少提供了一个有生产验证的参考实现。它不是完美的，但它的分层架构、符号化记忆、全链路溯源三大特性，可能会成为后续方案的对标基准。

总结：让 Agent 记住该记住的

TencentDB Agent Memory 解决的问题，可以浓缩为一句话：

让 Agent 记住该记住的，忘记该忘记的，追溯能追溯的。

四层金字塔架构，把「你是谁」（L3）、「你做过什么」（L2）、「你说过什么」（L1）、「原始证据」（L0）分层管理。符号化记忆把「当前任务状态」压缩成几百个 Token 的 Mermaid 图，保留完整的追溯路径。

这不是一个「万能记忆」方案，而是一个「有用记忆」方案。它不需要 Agent 记住所有事，但需要让 Agent 不再问你同一件事第二遍。

项目地址：https://github.com/Tencent/TencentDB-Agent-Memory
开源协议：MIT
npm 包：@tencentdb-agent-memory/memory-tencentdb

如果你在用 OpenClaw 或 Hermes Agent，一行命令就能体验。如果你在开发自己的 Agent 框架，这套架构值得深入研究。

记忆不是让 AI 记住所有事，而是让人不必重复所有事。这才是 Agent 记忆系统的真正价值。

复制全文生成海报 AI Agent 记忆系统腾讯云开源项目架构设计