TencentDB-Agent-Memory

你有没有过这种感觉：同一个项目的背景、同一个 SOP、同一个工具习惯，每次打开新对话都要重新教 AI 一遍？

这不是你的问题，而是当前 AI Agent 架构的先天缺陷：它们天然「忘性大」—— 每次新对话都是从零开始，既无法积累经验，也无法复用历史洞察。

传统方案要么暴力把所有历史塞进上下文（成本爆炸），要么用摘要把信息压缩到不可逆（关键细节永久丢失）。

TencentDB Agent Memory 给出了第三条路：用分层结构 + 符号化压缩，让 Agent 不仅「记得多」，更要「想得清」。

图1：TencentDB Agent Memory 核心全家桶

---

为什么记忆必须分层？

先看一个真实场景：

你在做一个持续 50 步的软件开发任务（SWE-bench 真实评测集），Agent 会调用数百次搜索工具、写出数千行中间代码、产生大量错误日志。到了第 30 步时，上下文已经积累了几十万 Token，Agent 开始「糊涂」—— 分不清哪个工具调用导致的问题，也记不住最初的需求细节。

传统方案：

• 全部塞上下文：Token 成本直接爆炸，SWE-bench 实测每次 session 消耗 3474M Token
• 暴力摘要：不可逆压缩，丢了细节，后续推理缺乏依据

TencentDB Agent Memory 的解法：分层 + 符号化

短期记忆分层（单次长任务内）：

• 底层：refs/*.md，保存完整原始工具输出（证据层）
• 中层：jsonl，步骤级摘要
• 顶层：Mermaid 任务画布，轻量级状态转移图，Agent 在上下文中只需关注这一层

长期记忆分层（跨会话经验积累）：

• L0 Conversation：原始对话日志
• L1 Atom：原子事实，结构化提取
• L2 Scenario：场景块，关联的事实组合
• L3 Persona：用户画像，日积月累的偏好和习惯

图2：L0-L3 分层记忆金字塔架构

---

核心技术：符号化记忆（Mermaid Canvas）

如果说分层是「组织方式」，那么符号化就是「压缩语言」。

在真实任务中，最占 Token 的不是对话本身，而是中间过程的工具输出——搜索结果、代码片段、错误堆栈。

TencentDB Agent Memory 的做法：

1. 把完整的工具日志卸载到外部文件系统（refs/*.md）
2. 用高密度 Mermaid 语法在上下文中保留关键状态转移关系
3. 每个 Mermaid 节点携带 node_id，需要查证时直接 grep 获取原文

这样一来，上下文中的 Token 消耗大幅降低，但所有信息的追溯链路完整保留——既轻量又可审计。

集成 OpenClaw 后，效果数据非常亮眼：

任务类型	Benchmark	成功率提升	Token 节省
短期记忆	WideSearch	+51.52%	-61.38%
短期记忆	SWE-bench	+9.93%	-33.09%
长期记忆	PersonaMem	+59%	—

SWE-bench 每次 session 连续执行 50 个任务，模拟真实长程 Agent 的上下文累积压力，而非单题清空上下文的简易测试。

图3：召回与恢复 Drill-Down 链路（可追溯到原始证据）

---

存储选型：SQLite + sqlite-vec，完全本地化

很多记忆系统依赖外部向量数据库（Pinecone、Milvus 等），增加了部署复杂度和数据隐私风险。

TencentDB Agent Memory 选择了一条更「朴素」的路：

• 向量检索：使用 sqlite-vec，SQLite 插件实现的向量搜索，零外部依赖
• 数据存储：本地 SQLite，异构存储（L0/L1 用数据库，L2/L3 用 Markdown 文件）
• Embedding：支持 OpenAI 兼容接口，也可以配置本地 embedding 模型

完全本地化意味着：不依赖任何外部 API，数据不出本地网络，隐私有保障。

---

上手方式：两条路径，总有一条适合你

路径一：Docker 一键启动（推荐尝鲜）

官方提供预编译 Docker 镜像，将 Hermes Agent 和 TDAI Memory Gateway 打包在一起，只需一个 API Key 即可运行：

docker run -d \
  --name hermes-memory \
  -p 8420:8420 \
  -e MODEL_API_KEY=your-key \
  hermes-memory

# 验证 Gateway
curl http://localhost:8420/health

# 进入对话
docker exec -it hermes-memory hermes

路径二：npm 插件接入 OpenClaw（深度用户）

如果你已经在使用 OpenClaw，安装插件只需两行命令：

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

然后在配置中启用即可，零配置默认使用 SQLite + sqlite-vec 本地后端：

{
  "memory-tencentdb": { "enabled": true }
}

可选开启短期压缩（上下文卸载），进一步降低 Token 消耗，需配合一个运行时 patch 脚本使用。

---

当前局限与注意事项

1. Node.js 版本门槛较高 要求 Node.js >= 22.16，对老项目不太友好。如果你在用旧版 Node.js 生态，需要先升级。

2. OpenClaw 集成需要运行时 patch 短期压缩功能依赖 scripts/openclaw-after-tool-call-messages.patch.sh 对 OpenClaw 源码打补丁，升级 OpenClaw 后需重新应用，且 patch 属于非官方修改，可能影响稳定性。

3. Hermes 插件路径尚未完全开箱即用 虽然 Docker 方式已很成熟，但将 memory-tencentdb 手动接入已有 Hermes 安装的路径，目前文档描述有限，适合有一定动手能力的用户。

---

行业意义：让 Agent 从工具进化为助手

TencentDB Agent Memory 的出现，折射出一个更大的趋势：AI Agent 正在从「单次任务执行器」进化为「长期经验积累者」。

当 Agent 能够记住你的工作习惯、项目背景和工具偏好，它就不再只是一个被动的工具，而是一个主动的协作伙伴。

GitHub 5918 颗星，且持续有 Issue 和 PR 活跃，说明市场对「有记忆的 Agent」有真实需求。

腾讯云作为背后支撑，既提供了可信的品牌背书，也在存储层（TencenDB 向量数据库）上留有扩展空间 —— 未来可无缝从 SQLite 迁移到云端向量数据库，满足更大规模部署。