我拆了 TencentDB Agent Memory

作者：小创 的架构，发现它和 OpenCode、Hermes 可以这样组合

上下文爆炸，是所有长程 Agent 的噩梦。

跑了 50 个任务之后，Token 消耗轻轻松松破千万，Agent 开始出现「失忆」症状——前面刚记住的偏好，后面完全不认识了。传统的解法是把历史全部塞进向量数据库，但扁平的向量堆砌召回效果差，而且「压缩即丢失」，调试起来跟开盲盒一样。

腾讯开源的 TencentDB Agent Memory 给出了一条不同的路：分层记忆 + 符号化压缩，Token 消耗降低 61%，通过率相对提升 51%。今天小创把它的架构拆透，聊一聊和 OpenCode、Hermes 组合落地的可能性。

一、核心设计：拒绝平铺，走向分层与符号化

Agent Memory 的设计哲学围绕两个关键词：记忆分层 和 符号化记忆。

1. 记忆分层：L0 → L3 语义金字塔

传统记忆系统把数据切片后平铺成向量，召回时就像在一堆毫无关联的便利贴里找线索。Agent Memory 认为——不管是长期知识、短期任务还是未来经验，记忆都不应该平铺，生成和召回都必须有层次。

它的分层结构长这样：

层级	名称	内容	用途
L0	Conversation	原始对话记录	需要考证细节时回溯
L1	Atom	结构化事实片段	需要精确事实时召回
L2	Scenario	场景块（Markdown）	高密度理解用户当前场景
L3	Persona	用户画像	把握长期偏好和习惯

关键是：每一条信息都可以完整溯源。L3 的 Persona 可以追到对应的 L2 Scenario → L1 Atom → L0 Conversation。不存在「不可逆的压缩」。

2. 符号化记忆：Mermaid 画布降 Token

长程任务中最消耗 Token 的，是繁杂的过程日志（搜索结果、代码、报错）。Agent Memory 提出了符号化记忆：

完整工具日志被卸载到外部文件系统（refs/*.md）
上下文仅保留轻量级的 Mermaid 任务地图（带 node_id）
Agent 看着 Mermaid 推理，如需核对细节，直接用 node_id 找回完整原文

降 Token 效果是实打实的：

Benchmark	原通过率	加插件后	变化	原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%
PersonaMem	48%	76%	+59%	-	-	-

超长 Session 评测是把多个任务拼接到同一个 Session 中连续执行，SWE-bench 每个 Session 连续执行 50 个任务，模拟真实长程 Agent 的上下文累积压力。

二、它能干什么？和 OpenCode/Hermes 组合的落地场景

场景 1：OpenCode + Agent Memory = 记住你的项目习惯

OpenCode 是一个代码智能体，每次新项目都要重新解释：
- 项目结构是怎样的
- 输出格式偏好（PR 规范、commit message 风格）
- 常用的技术栈和工具

接入 Agent Memory 后，这些信息会被逐轮沉淀，最终形成一个 L3 Persona。下次开新项目，Agent 直接从记忆里读你的偏好，不需要重新解释。

# OpenClaw 接入方式
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart

// ~/.openclaw/openclaw.json
{
  "memory-tencentdb": {
    "enabled": true
  }
}

零配置，开箱即用。默认用本地 SQLite + sqlite-vec 后端。

场景 2：Hermes + Agent Memory = 有记忆的长程任务执行

Hermes 本身是一个多功能的 AI Agent 网关，接入 Agent Memory 后能解决长程任务的「失忆」问题。

比如：跑一个需要 50 步的代码重构任务，中途断了。传统 Agent 需要从头开始；有 Agent Memory 之后，Agent 可以从上次中断的地方继续，并且理解「之前为什么这样做」。

# Hermes Docker 模式
docker build -f Dockerfile.hermes -t hermes-memory .

docker run -d \
  --name hermes-memory \
  --restart unless-stopped \
  -p 8420:8420 \
  -e MODEL_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 \
  hermes-memory

镜像内置腾讯云 DeepSeek-V3.2 默认值，使用该模型时 MODEL_BASE_URL / MODEL_NAME / MODEL_PROVIDER 都可以省略。

场景 3：三层记忆联动 = 让 Agent 从「工具」变成「助手」

记忆层级	在 OpenCode/Hermes 中的作用
L3 Persona	理解「你是谁，你习惯怎么工作」
L2 Scenario	理解「当前在做什么项目，用什么技术栈」
L1 Atom	召回具体的技术细节和历史决策
Mermaid 画布	长任务中实时跟踪进度，中断后可恢复

本质区别：没有 Agent Memory 的 Agent，每次对话都是「陌生人」；有了之后，每次对话是「认识你的助手」。

三、部署需要什么机器配置？

这个问题官方文档没有给具体的配置表，但小创根据架构做了推算，先说结论：

最小化部署（单节点，尝鲜体验）

组件	配置	说明
Gateway（Node 服务）	1核 / 1GB	无状态 HTTP sidecar，很轻
SQLite 本地存储	5-10GB SSD	L0-L3 语义文件 + sqlite-vec 向量
Node 版本	>= 22.16	硬性要求
内存余量	建议 2GB+	LLM 调用时 Embedding 模型会吃内存

生产级部署（多用户、多 Agent）

组件	配置	说明
Gateway	2-4核 / 2-4GB	并发多个 Agent 请求时需要
向量数据库（可选）	腾讯云 VDB	如用远程向量库，本地压力更小
Embedding 服务	独立调用	OpenAI 兼容 API，或腾讯云 bge-large-zh
LLM 服务	独立调用	可以是 OpenAI / DeepSeek / 腾讯云等
存储	50GB+ SSD	长程会话日志会积累，建议定期归档

关键依赖

Node >= 22.16 - 这是硬性要求，低版本跑不起来
Python3 - 运维脚本依赖（memory-tencentdb-ctl.sh）
npx - 用于启动 Gateway
LLM API Key - 你需要有 OpenAI / DeepSeek 或其他兼容 API 的访问权限
Embedding API - 可选（默认用 BM25 召回），如启用需要 OpenAI 兼容的 embedding 服务

网络要求

Gateway 默认监听 127.0.0.1:8420，仅本地访问
如用腾讯云 VDB，需要能访问 http://xxx-vdb.tencentclb.com:8100
如用远程 LLM/Embedding，需要能访问对应 API 端点

四、架构亮点：白盒可调试

这是小创觉得 Agent Memory 最有价值的设计细节之一——记忆不是黑盒向量。

传统的记忆系统：召回错了，只能看到一串向量分数，不知道哪里出了问题。

Agent Memory 的调试路径：

L3 Persona.md → L2 Scenario.md → L1 Atom/*.jsonl → L0 refs/*.md

所有中间产物都是可读文件：
- L2 Scenario 是 Markdown，直接打开检查
- L3 Persona 存放在 persona.md，可以追溯到对应的 Scenario
- 短期任务画布是 Mermaid，人能看，Agent 也能读
- 原文、摘要、node_id 之间有 result_ref 关联

这些分层记忆产物都存放在 ~/.openclaw/memory-tdai/ 下，可以直接打开目录逐层查看。

这对开发者来说意味着：出了问题不用靠「直觉」猜，直接翻文件定位。

五、和 OpenCode / Hermes 的本质区别

很多人会问：既然 OpenCode 和 Hermes 本身已经有 Agent 能力，Agent Memory 的价值在哪里？

对比维度	OpenCode / Hermes	Agent Memory
定位	Agent 执行框架	记忆与上下文管理层
解决的问题	「怎么做」	「记得什么、怎么记、怎么召回」
上下文处理	长程对话时 Token 持续膨胀	分层卸载 + 符号压缩
记忆能力	无（每次都是新对话）	L0-L3 分层 + 可溯源
适用场景	单次任务执行	长程、多会话、项目级协作

简单说：OpenCode/Hermes 决定 Agent 做什么，Agent Memory 决定 Agent 记住什么。两者是互补关系，不是替代关系。

六、落地建议

入门（OpenClaw 插件模式）

如果你是 OpenClaw 用户，直接装插件，零配置体验：

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

默认 SQLite 后端，不需要额外基础设施。

进阶（Hermes 集成模式）

如果你用 Hermes，希望记忆跨 session 持久化：

# 构建带记忆的 Hermes 镜像
docker build -f Dockerfile.hermes -t hermes-memory .

# 启动，记得挂载数据卷
docker run -d \
  --name hermes-memory \
  --restart unless-stopped \
  -p 8420:8420 \
  -e MODEL_API_KEY="你的KEY" \
  -v hermes_data:/opt/data \
  hermes-memory

# 启用 hermes memory provider
memory-tencentdb-ctl --hermes enable-hermes-memory

生产环境（按需开启向量库）

如果用户量上去，SQLite 向量召回性能不够，可以切换到腾讯云 VDB：

memory-tencentdb-ctl config vdb \
  --url "http://xxx-vdb.tencentclb.com:8100" \
  --api-key "YOUR-VDB-API-KEY" \
  --database "openclaw_memory" \
  --embedding-model "bge-large-zh" \
  --restart

写在最后

TencentDB Agent Memory 解决的不是「Agent 怎么干活」的问题，而是「Agent 怎么记住干活的方式」的问题。

这对长程任务、多会话协作、项目级上下文管理来说，是本质性的提升。结合 OpenCode 的代码执行能力和 Hermes 的多场景调度能力，三者组合能形成一个有记忆、能进化、懂你习惯的智能体系统。

现在还处于早期阶段（Roadmap 还有 Skill 自动生成、可视化调试面板），但核心架构已经跑通。如果你也在做 Agent 相关的事情，值得关注。

你在用 Agent Memory 吗？或者对多 Agent 协作有什么想法？评论区聊聊。

评论区预置内容

分层记忆这个设计思路很清晰
自己改写比拿来主义靠谱
省了不少时间
原来可以这样用

📄 文档管理系统

我拆了 TencentDB Agent Memory 的架构，发现它和 OpenCode、Hermes 可以这样组合