TencentDB Agent Memory · 中文技术教程

TencentDB Agent Memory · 中文技术教程

让 Agent 沉淀经验，让人专注创造——讲透「记忆资产逐层生长、按身份装配、按需调用」背后的工程架构

这本教程讲什么

本教程是腾讯开源项目「TencentDB Agent Memory」的体系化中文教程。它要回答一个很实际的问题:怎样减少使用 Agent 时的重复工作?

项目背景讲过了,不该换个 Session 再讲;文档读过了,不该每个 Agent 从第一页重读;一套做法已经跑通,不该下次再摸索一遍。所以这里的 Memory 不只是「记住对话」——凡是能让下一个 Agent 少走弯路的信息,都应该被保存、组织并复用。 这是它和普通 RAG 最根本的区别:RAG 解决「能查到什么」,而 Agent Memory 还要解决「谁可以用、哪个版本有效、应该给哪个 Agent」。

它的硬核之处藏在三个设计决策里。第一,记忆不是平铺记录,而是逐层生长——对话先作为 L0 原始上下文保存,再由异步 Pipeline 提炼为 L1 事实原子、L2 场景知识块、L3 长期画像,平时用 L2 / L3 快速进入语境,需要具体事实时再用 BM25 + 向量 + RRF 混合检索回退到 L1 / L0,召回结果还要过条数、字符、超时三道预算闸门。第二,记忆不是全局 Prompt,而是 Agent 的 Loadout(装备)——四类资产(Chat Memory / Skill / Wiki / CodeGraph)统一登记为 Memory Asset,通过 Fixed Binding + ACL 按 Team、User、Agent、可见性缩小范围再召回,团队可以共享经验却不必共享全部隐私。第三,知识不整库注入,而是按需调用——文档被整理为可搜索、可沿链接下钻的 Wiki,代码被索引为含符号、调用关系、影响路径的 CodeGraph,Agent 先用 /v3/tools/list 发现能力,再用 /v3/tools/call 读取所需片段,它们平时只是可用工具,只有真正需要时才进入上下文。

本教程不教你如何在网页面板上点按钮,而是带你读它的工程图纸:四组件如何分工、对话如何逐层长出记忆、透明代理如何让 Coding Agent 零改造拥有记忆、五类 Agent 框架如何接入同一套记忆、一支会成长的 Agent 队伍怎么组起来。全书最硬核的两章是第 6 章(MemoryCore 抽取 Pipeline 源码精读)与第 8 章(MemoryProxy 八步请求管道源码精读),它们给出前述三大设计命题的工程实现。

学习路径一览

本教程按「跑起来 → 看懂架构 → 概念基础 → 服务精读 → 接入开发 → 场景实战 → 进阶」的递进逻辑组织,共十二章加一个附录:

第 1 章 环境准备与首次跑通 ── 5 分钟起三件套,接入第一个 Coding Agent
   一键起 · 接入 Claude Code · 第一次记忆会话 · 验收
        │
第 2 章 核心概念与整体架构 ── 建立全局地图(全书地图)
   动机 · 四类资产 · 四组件拓扑 · 控制流旅程 · 与 RAG 差异
        │
第 3 ~ 5 章 记忆的「是什么」── 资产、分层、治理
   资产统一模型 · L0-L3 四层 · Memory Hub 操作台
        │
第 6 ~ 8 章 服务的「怎么实现」── 三服务源码精读(硬核三连)
   Core 抽取 Pipeline · Wiki/CodeGraph 引擎 · Proxy 八步管道
        │
第 9 ~ 10 章 接入开发 ── 把记忆接到你的 Agent 上
   SDK 四步法(双语言) · 五类 Agent 框架实战
        │
第 11 ~ 12 章 实战与进阶 ── 从用起来到跑稳
   组队装配与 Loop 复利 · 可观测 / 限流 / 安全 / 部署
        │
附录 A 术语表 · 速查 · 排错
​

如果你想快速试用,看第 1 章;想理解整体设计,第 2 章是地图;想知道 Agent 怎么拥有记忆,重点读第 4 章(四层记忆)与第 8 章(Proxy 管道);想看最硬核的源码,读第 6 章与第 8 章;想把记忆接到自己的代码里,看第 9 章 SDK 四步法;想组一支会成长的 Agent 队伍,看第 11 章。

章节目录

第 1 章 环境准备与首次跑通
技术栈与环境要求、一键起三件套(memory-core + memory-hub + proxy)、接入第一个 Coding Agent、完成第一次记忆会话与验收。读完你能把整套系统跑起来并验证记忆生效。

第 2 章 核心概念与整体架构(全书地图)
为什么需要 Agent 记忆、四类记忆资产总览、四组件拓扑与职责边界、一次记忆召回的控制流旅程、与 RAG / 聊天历史 / Mem0 的差异定位。读完你能画出整张架构图并解释每一层的存在理由。

第 3 章 记忆资产统一模型
一切记忆如何被登记为 Memory Asset、Owner / 版本 / 状态的资产生命周期、可见性模型(private / team / restricted / agent)、Fixed Binding + ACL 从权限范围到召回。读完你能解释团队如何共享经验却不必共享全部隐私。

第 4 章 四层记忆架构详解
L0 Conversation 原始上下文、L1 Atom 抽取与去重、L2 Scenario 场景知识块、L3 Core / Persona 长期画像、分层生成与分层召回 + 召回预算控制。读完你能解释对话如何逐层生长为可复用记忆。

第 5 章 MemoryHub 控制台
团队与角色体系、资产管理与审核分享、Agent Loadout 装配背包、Knowledge 工坊构建 Wiki 与 CodeGraph。读完你能解释人如何在操作台上治理团队记忆。

第 6 章 MemoryCore 抽取 Pipeline 精读(全书硬核核心之一)
Pipeline 全景从 L0 录制到异步提炼、L1 抽取与去重实现、L2 scene 与 L3 persona 沉淀机制、召回引擎 BM25 + 向量 + RRF 混合检索、召回预算三道闸门。读完你能解释原话如何被异步提炼并精确召回。

第 7 章 知识引擎:Wiki 与 CodeGraph
Wiki ingest 结构化页面与链接图谱、CodeGraph 符号 / 文件 / 调用关系 / 影响路径、按需调用 /v3/tools/list 与 /v3/tools/call、Auto-Sync FIFO 队列与 worker pool。读完你能解释文档与代码如何变成按需调用的记忆。

第 8 章 MemoryProxy 八步管道精读(全书硬核核心之一)
透明代理定位与八步管道全景、auth + systemUser + sessionInit 身份与交互式表单、injection 策略 inject 注入 vs toolize 工具化、rateLimit + forward + extract 限流转发与回写、存储抽象五后端降级链与 Credit 计费。读完你能解释透明代理如何让 Coding Agent 零改造拥有记忆。

第 9 章 SDK 接入开发:四步法
接入四步总览与 SDK 速查、召回注入两区块 prepend / append、捕获工具暴露与对话回写、工程坑召回污染还原与 sanitize 清洗、错误降级三原则与性能建议。读完你能用 Python 或 TypeScript SDK 把记忆接进自己的 Agent。

第 10 章 Coding Agent 接入实战
Claude Code 与 CodeBuddy 接入、Hermes 适配器生命周期映射与熔断背压、OpenClaw 插件三层架构、通用 OpenAI 兼容接入。读完你能让五类 Agent 框架接入同一套记忆。

第 11 章 场景实战:组队、装配与 Loop 复利
组队建 Team 招 Agent 定角色、冷启动读档导入代码库 / 文档 / Session、装配 Loadout 少给噪音多给所需、Loop 复利每一轮继承上一轮成果。读完你能组起一支会成长的 Agent 队伍。

第 12 章 进阶:可观测、限流、安全与部署
三路可观测 Langfuse / Opik / ClickHouse、OpenTelemetry trace 传播、v3 严格隔离四元组、安全 API Key / CORS / 凭证注入 / 租户隔离、部署形态与 v2 → v3 数据迁移。读完你能把这套体系交付到生产并理解其工程保障。

附录 A 术语表 · 速查 · 排错
全书术语词典(中英对照)、高频 API 与命令速查、报错 → 原因 → 排查三列表。

适合读者

本教程适合想读懂一个工业级 Agent 记忆平台的工程师与架构师:

• 在用 Claude Code / CodeBuddy / Cursor 等 Coding Agent,想让它们记住项目经验、减少重复工作的开发者
• 想为团队搭建可复用「经验资产库」的平台工程师与技术负责人
• 研究 Agent 记忆、长期上下文管理、混合检索架构的工程师与研究者
• 对 LLM 应用的可观测、限流计费、租户隔离、透明代理等工程化议题感兴趣的后端工程师
• 想二次开发或贡献代码的开源爱好者

前置知识:

• 熟悉至少一门后端语言(Python 或 TypeScript),了解 HTTP / REST 基本概念
• 用过任意 Coding Agent(如 Claude Code),了解「会话」「上下文」「工具调用」的基本概念
• 了解「向量检索」「RAG」的基本概念会有帮助但非必需——本教程在第 2 章会做对比铺垫
• 了解 Docker 基本用法会有帮助(部署章节涉及)

阅读约定

• 本教程对照的原文来自 TencentDB Agent Memory 开源项目。若你使用的版本与本教程有差异,请以本地源码为最终依据。
• 为遵循平台规范,正文不引用具体文件名或代码路径,改用「记忆核心服务」「代理层」「抽取模块」「知识引擎」等功能性描述;公开 API 真名(如 start-all.sh、/v3/tools/call、x-tdai-user-key)会保留,但不与仓库私有路径绑定。
• 章节之间允许交叉引用(如「详见第 8 章」),但不使用任何超链接语法,提及外部资源时用纯文字描述。
• 代码示例为说明原理的概念性片段,可能做简化;实际编码时请以本地源码与官方文档为准。
• 每章先读「支柱页」建立全局观,再逐节深入。硬核两章(第 6、8 章)信息密度高,建议结合本地源码对照阅读。
• 中文标点全角(,。:;""——),命令、配置、公开 API 名称用半角并包裹于反引号。