深度解读 TencentDB Agent Memory：让 AI Agent 真正拥有分层记忆
为什么 AI Agent 需要记忆系统？
如果你有过长时间使用 AI Agent 的经验，一定对以下场景不陌生：
- 每次新会话都要重新解释项目背景、代码规范、输出格式偏好
- 长任务执行到一半，上下文被海量工具日志塞满，Agent 开始"遗忘"早期指令
- 想让 Agent 学习你的工作习惯，却只能靠每次手写 system prompt
Memory 不是为了让 AI 存下所有东西，而是为了让人不必重复所有事情。 这是 TencentDB Agent Memory 项目的核心理念。
这个由腾讯开源的项目（MIT 协议），目前已在 GitHub 获得 2400+ Star，提供了一套完整的本地化 Agent 记忆解决方案——零外部 API 依赖，开箱即用。
核心亮点一览
项目将记忆能力拆分为两大引擎：
| 能力 | 解决的问题 | 技术手段 |
|---|---|---|
| 符号化短期记忆 | 长任务中工具日志塞满上下文 | Mermaid 符号图谱 + 上下文卸载 |
| 分层式长期记忆 | 跨会话经验无法沉淀 | L0→L3 语义金字塔 |
实测数据相当有说服力：
| Benchmark | 成功率提升 | Token 节省 |
|---|---|---|
| WideSearch | +51.52%（相对） | -61.38% |
| SWE-bench | +9.93% | -33.09% |
| PersonaMem | 准确率 48%→76% | — |
其中 SWE-bench 的测试方式是每个 Session 连续执行 50 个任务，模拟真实长程 Agent 的上下文累积压力——这比单题清空上下文的评测方式严格得多。
核心技术一：记忆分层——从 L0 到 L3 的语义金字塔
传统记忆系统将数据切片后平铺为向量，召回时如同在一堆便利贴中盲搜，缺乏宏观指引。TencentDB Agent Memory 用分层作为统一设计范式：
┌─────────────────┐
│ L3 Persona │ ← 用户画像：日常偏好、表达风格、长期目标
├─────────────────┤
│ L2 Scenario │ ← 场景块：按情境聚合的相关事实
├─────────────────┤
│ L1 Atom │ ← 原子事实：结构化的最小知识单元
├─────────────────┤
│ L0 Conversation│ ← 原始对话：完整的历史记录
└─────────────────┘这套分层设计不仅用于长期个性化，还贯穿于短期任务管理和未来的技能生成：
- 短期上下文分层：底层保留原始工具输出（
refs/*.md），中层抽取步骤摘要（jsonl），高层浓缩为 Mermaid 任务画布 - 长期个性化分层：从 L0 原始对话逐步提炼到 L3 用户画像，平时靠高层把握偏好，需要细节时下钻到 Atom
- 技能生成分层（Roadmap）：从执行轨迹中归纳解决模式，最终提炼为可复用的 Skill
关键设计原则：每一条信息都 100% 可追溯。 无论是短期中被卸载的报错日志，还是长期中总结的用户偏好，都可以沿着 Persona → Scenario → Atom → Conversation 的链路完整溯源。
底层（事实、日志、轨迹）存入数据库确保稳定检索；高层（画像、场景、画布）存为 Markdown 文件确保可读可调。低层保留证据，高层保留结构。
核心技术二：符号化记忆——用 Mermaid 表达任务状态
长任务中最消耗 Token 的往往是繁杂的过程日志——搜索结果、代码片段、报错堆栈。项目提出的符号化记忆方案思路清晰：
- 完整日志卸载到外部文件：原始工具输出保存到
refs/*.md - 提取关系并生成为 Mermaid 符号图谱：用高密度 Mermaid 语法描绘任务状态流转
- 轻量注入 Agent 上下文：Agent 只看到几百 Token 的符号图谱
- 按需溯源：需要细节时通过
node_id瞬间找回完整原文
繁杂日志(几十万Token) → 卸载原文 → 外部文件系统
→ 提取关系 → Mermaid 符号图谱(带 node_id)
→ 轻量注入 → Agent 上下文(几百 Token)
← 按 node_id 下钻恢复原文这个设计的精妙之处在于：用最少的符号表达最多的语义。Mermaid 既有足够的拓扑信息让 LLM 理解任务结构，又足够紧凑不会浪费 Token。
工程能力：不是 Demo，是可接入的插件
项目提供了两种接入方式：
方式一：OpenClaw 插件（一行命令安装）
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart安装后自动捕获对话、提取记忆、注入召回，零配置即可运行。
方式二：Hermes Gateway（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="your-api-key" \
-v hermes_data:/opt/data \
hermes-memory其他工程特性：
- 本地后端：SQLite + sqlite-vec，无需额外服务
- 混合检索：BM25 + 向量 + RRF 融合，支持关键词和语义双路召回
- Agent 工具：提供
tdai_memory_search和tdai_conversation_search两个内置工具
实战：在 Pi Coding Agent 中接入的尝试与体验
作为一个日常使用 Pi Coding Agent（一款基于 CLI 的 AI 编程助手，底层通过 OpenAI 兼容 API 调用大模型）的开发者，我尝试将它与 TencentDB Agent Memory 进行对接，以下是基于实际操作的真实记录。
接入方式：Gateway HTTP API
TencentDB Agent Memory 目前官方支持两种宿主环境：OpenClaw 插件和 Hermes Gateway。Pi Coding Agent 不在其中。不过，项目的 Gateway 模式提供了独立的 HTTP API，这是接入第三方 Agent 的可行路径。
Gateway 启动后暴露以下端点：
| 端点 | 方法 | 用途 |
|---|---|---|
/health | GET | 健康检查 |
/recall | POST | 记忆召回（注入上下文前预取） |
/capture | POST | 对话捕获（同步写入 L0） |
/search/memories | POST | L1 记忆语义搜索 |
/search/conversations | POST | L0 原始对话搜索 |
/session/end | POST | 会话结束 + 触发 pipeline flush |
/seed | POST | 批量导入历史对话 |
从架构上看，StandaloneHostAdapter 的 RuntimeContext 支持 platform 字段为任意字符串（定义中是 "openclaw" | "hermes" | "cli" | "gateway" | string），这意味着第三方框架可以以自定义 platform 身份接入。
Pi Agent 的对话以 JSONL 文件存储在 ~/.pi/agent/sessions/ 下，理论上可以通过 /seed 端点批量导入历史会话，再在每次对话时调用 /capture 写入新消息、通过 /recall 获取相关记忆注入上下文。
实际接入中遇到的情况
好的方面：
- Gateway 设计解耦干净。 核心逻辑通过
HostAdapter接口与宿主框架分离，StandaloneLLMRunner使用 Vercel AI SDK + OpenAI 兼容 API，Pi 的模型提供方（通过自定义 baseUrl 和 apiKey）可以直接对接，不需要改造。 - HTTP API 接口语义清晰。 每个端点的职责明确——capture 负责写入、recall 负责读取、search 负责查询，上手成本不高。
- 历史数据导入有现成路径。
/seed端点接受批量会话数据，Pi 的 JSONL 会话记录可以通过脚本转换为 seed 格式，无需从零积累。 - 本地运行零依赖。 SQLite + sqlite-vec 全部本地化，不需要额外部署向量数据库，对个人开发者的机器环境很友好。
不够理想的方面：
- 没有现成的 Pi 适配器。 目前只有 OpenClaw 和 Hermes（Standalone）两种 Adapter 实现，Pi Agent 需要自己写胶水代码来对接 Gateway HTTP API。这涉及拦截 Pi 的每轮对话、调用 capture 和 recall、将召回结果注入 prompt——目前 Pi 没有提供类似 OpenClaw 的 hook/plugin 机制来自动完成这一步。
- Session 管理需要手动映射。 Pi 的 session 以工作目录 + 时间戳命名（如
~/.pi/agent/sessions/--home-ssy-Projects-blog-src--/2026-05-17T...jsonl），而 TencentDB Agent Memory 使用session_key+session_id管理。需要在胶水层做一对一映射，确保记忆召回时能正确定位到对应会话。 - 模型兼容性需要验证。 Gateway 的 LLM Runner 默认用于记忆提取（L1/L2/L3 pipeline），这些任务对模型的指令遵循能力有一定要求。Pi 当前使用的模型（如 GLM-5.1）在记忆提取任务上的表现需要实际测试，项目文档中只验证了 DeepSeek-V3.2 和 GPT 系列。
- 短期记忆压缩对 Coding Agent 价值有限。 符号化短期记忆（Mermaid 画布 + 上下文卸载）主要解决的是长程任务中工具日志暴增的问题。Pi Agent 在执行代码修改时产生的工具输出通常在上下文窗口承受范围内（GLM-5.1 的上下文窗口为 200K Token），真正需要 offload 的场景相对较少。
一句话总结
TencentDB Agent Memory 的架构设计为第三方 Agent 接入留出了清晰的通道（Gateway HTTP API + 可扩展的 HostAdapter 接口），但目前仍需自行编写胶水代码完成对接。对于 Pi Coding Agent 这类 CLI 工具而言，长期记忆（用户偏好、项目上下文跨会话保留）的接入价值高于短期记忆压缩。期待项目后续推出跨框架的通用 Adapter 或 SDK，进一步降低接入门槛。
白盒可调试：记忆不是黑盒
这是该项目区别于很多记忆方案的重要特征。所有中间产物都是可读文件：
- L2 Scenario 块是 Markdown，可以直接打开检查
- L3 Persona 存放在
persona.md，可追溯到生成它的 Scenario - 短期任务画布是 Mermaid，人类和 Agent 都能读懂
- 原文、摘要、节点之间通过
result_ref和node_id关联
所有分层记忆产物存放在 ~/.openclaw/memory-tdai/ 下，调试时沿着链路逐层定位即可，不需要翻黑盒数据库。
配置参数：覆盖 90% 场景的日常调参
虽然零配置就能跑，但项目提供了三层渐进式配置体系。日常使用中最常用的几个参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
storeBackend | sqlite | 存储后端 |
recall.strategy | hybrid | 召回策略：keyword / embedding / hybrid（推荐） |
recall.maxResults | 5 | 每次召回的条目数 |
pipeline.everyNConversations | 5 | 每 N 轮触发一次 L1 记忆提取 |
persona.triggerEveryN | 50 | 每积累 N 条新记忆更新一次用户画像 |
我的推荐理由
作为一个关注 AI Agent 基础设施发展的技术人，我认为这个项目值得关注的原因：
1. 设计哲学正确。 不是简单地"存更多"，而是思考"怎么存、怎么用、怎么调"。分层和符号化是对记忆系统的结构化思考，而非暴力堆砌。
2. 完全本地化。 零外部 API 依赖意味着数据不出本地，对隐私敏感场景非常友好。SQLite + sqlite-vec 的组合对个人开发者和中小团队足够了。
3. 白盒设计。 记忆系统的可解释性直接决定了可调试性和可信赖度。所有中间产物都是人可读的，这在生产环境中极其重要。
4. 工程完成度高。 不是概念验证，而是有完整的插件体系、Docker 支持、混合检索、配置分层。项目结构清晰，代码质量在线。
5. 路线图有野心。 跨 Agent 记忆迁移、Skill 自动生成、可视化调试面板——这些都是 Agent 记忆领域的核心问题。
GitHub: https://github.com/Tencent/TencentDB-Agent-Memory
License: MIT | Language: TypeScript | Stars: 2400+
如果觉得有用，别忘了给项目点个 Star。
写在最后
AI Agent 的记忆问题远未被彻底解决。当前主流方案要么依赖外部向量数据库，要么粗暴地将历史摘要塞入 prompt——前者增加部署复杂度，后者丢失关键细节。
TencentDB Agent Memory 提供了一个值得认真对待的第三条路：通过分层存储和符号化表达，在 Token 效率、信息完整性和可调试性之间找到了一个相当好的平衡点。
对于正在构建长程 Agent 应用的开发者，这个项目值得花时间研究和试用。
