TencentDB Agent Memory 架构拆解：告别 Agent 失忆，构建四层可追溯记忆与上下文治理系统

拆解 TencentDB Agent Memory 如何用分层记忆、上下文卸载和降级检索让 Agent 留住工作现场。原文链接AI 小老六Agent 真正难用的地方往往不是它不会调用工具而是它记不住工作现场。你刚给它讲完项目背景、编码偏好、部署约束和排障 SOP换一个会话又要从头解释一次稍微复杂的开发任务跑下来搜索结果、文件内容、测试日志和报错堆满上下文模型开始抓不住重点。于是很多记忆方案会走向两个极端要么把历史尽可能塞回上下文要么把所有内容压成摘要或向量。前者贵且吵后者省但容易丢证据。TencentDB Agent Memory的价值正在于它没有把“记忆”理解成一个简单的向量库插件而是把它做成了一套本地化的 ​Agent 记忆与上下文治理系统​。它试图同时回答两个问题跨会话经验如何沉淀避免人反复教学单次长任务如何控住 Token、保住证据、维持任务进度感项目地址https://github.com/Tencent/TencentDB-Agent-Memory.git​Memory Pipeline​记忆系统首先要解决“压缩后还能不能查证”多数 Agent Memory 的第一反应是“召回”。但在真实工程里召回之前还有一个更基础的问题被召回的信息从哪里来它有没有来源抽象错了能不能回查。几类常见做法各有价值也都带着明显短板方案能解决什么主要代价全量历史回灌细节完整几乎不丢上下文Token 快速膨胀注意力被日志和噪音冲散强摘要压缩成本低上下文短摘要不可逆关键证据一旦被丢弃很难补救扁平向量库可按语义找相似经验缺少层次关系不知道用户、场景、任务之间的结构只维护 Persona能保留长期偏好和用户画像太抽象无法支撑具体问题的证据追溯TencentDB Agent Memory 的核心判断是记忆不能只有一个形态。低层要保留原始证据高层要沉淀稳定结构中间层要能把碎片事实组织成可读场景。这样 Agent 既能从宏观层面理解用户和项目又能在需要时钻回细节。这套思路可以概括为一句话压缩可以发生但压缩结果必须可逆抽象可以存在但抽象必须带着索引。图记忆压缩不是丢弃证据而是在抽象层和原始来源之间建立可回查索引。​L0-L3 Memory Stack​把“记住”拆成四种不同职责项目把长期记忆拆成 L0、L1、L2、L3 四层。它们不是简单的缓存层级而是四种不同的信息表达方式。L3 Persona 长期稳定画像用户偏好、工作方式、长期习惯 L2 Scenario 场景块项目、任务类型、流程经验、上下文集合 L1 Atom 结构化事实明确指令、偏好、历史事件、可检索片段 L0 Conversation 原始对话完整消息与工具证据必要时回L0 是证据底座。这一层记录原始 user/assistant 消息也可以写入 JSONL、SQLite 或 VectorDB。它不急着判断哪些内容更重要而是先把干净的原始材料留下来。它的存在让上层抽取和总结有了兜底如果 L1、L2、L3 的判断不够可信还能回到源消息核对。L1 是事实抽取层。它把对话中的明确偏好、指令、历史事件抽成结构化记忆。例如{content:用户偏好使用 pnpm 管理前端依赖避免使用 npm。,type:instruction,priority:80,scene_name:前端工程规范,source_message_ids:[msg_...]}这个结构里最关键的不是content而是source_message_ids。它意味着一条事实不是凭空生成的而是能追溯到具体对话来源。L2 是场景组织层。单条 L1 事实适合检索却不适合人和 Agent 长期阅读。L2 会把相关事实整理成 Markdown 场景块比如“某业务项目的开发习惯”“某类线上排障流程”“某用户的测试偏好”。这一层让碎片记忆变成可理解的上下文。L3 是稳定画像层。它生成persona.md沉淀用户长期稳定的偏好、背景和工作方式。相比 L1 的任务相关事实L3 更像 Agent 每次进入工作状态前需要先理解的“合作对象说明书”。四层叠在一起后记忆系统不再是一个大杂烩。Agent 可以先读高层结构如果缺少证据再沿着 L3/L2/L1 的索引向下查到 L0。这个过程就是渐进式披露默认给模型最有用、最少噪音的信息只在必要时暴露更细的原文。​Retrieval Placement​召回内容放哪里比召回多少更影响工程成本很多记忆系统会停在“按相似度找几段内容”这一步。TencentDB Agent Memory 更进一步关心召回到的内容应该注入到哪里。一次 Agent 会话开始前它通常会准备几类信息当前用户输入相关的 L1 记忆。稳定的 L3 Persona。L2 场景导航或场景块。记忆工具说明告诉 Agent 必要时如何继续查 L1 或 L0。这些信息被分成​动态上下文和稳定上下文​。动态部分每轮都可能变化比如针对当前任务召回出来的 L1relevant-memories以下是当前对话召回的相关记忆不代表当前任务进程仅作为参考 - [instruction] 用户偏好使用 pnpm 管理前端依赖/relevant-memories稳定部分包括 Persona、Scene Navigation、工具指南变化频率低更适合放在 system prompt 尾部。这样做有一个很现实的收益更容易命中模型厂商的 prompt cache。高频变化的信息放在用户 prompt 附近低频稳定的信息放在可缓存区域既减少重复开销也降低上下文组织的抖动。这类细节说明它不是只在做“记忆功能”而是在做“可落地的 Agent Runtime 记忆链路”。记忆质量、注入位置、缓存命中、召回成本都会影响最终体验。​Local-First Storage​SQLite、FTS5、sqlite-vec 组成可降级检索路径这套方案默认本地运行使用 ​SQLite 保存 L0/L1 元数据​配合 FTS5 全文索引和 sqlite-vec 向量表需要时也可以接 Tencent Cloud VectorDB。检索路径不是单点依赖而是分成三种策略检索策略依赖能力适用场景keywordFTS5 BM25关键词明确或没有配置 embeddingembedding向量相似度表达不完全一致但语义接近hybridFTS 向量 RRF默认综合策略兼顾精确匹配和语义召回这里最值得注意的是​降级设计​。如果没有配置 embedding系统可以直接走 FTS如果 embedding 调用失败也不会阻塞主流程SQLite L0 写入还支持先写元数据和 FTS再后台补向量避免一次agent_end被远程 embedding 服务卡住。这类设计不炫技但很关键。记忆系统一旦进入公司内网、代理环境、权限边界和模型服务波动场景失败路径会比演示环境复杂得多。没有降级能力的 Memory很难成为 Agent 平台的基础设施。图SQLite、FTS5 与向量检索组成可降级的本地优先记忆检索路径。​Context Offload​长任务真正的 Token 黑洞是工具结果跨会话记忆解决的是“下次别让我重复说”。但在单次长任务里更常见的问题是工具结果把上下文撑爆。Agent 做研发任务时经常会遇到这些情况搜索代码返回上百个候选结果。测试失败输出几千行日志。读取大文件后整段内容进入上下文。多轮工具调用后历史记录越来越像滚雪球。如果把这些内容都留在上下文里模型会被噪音拖慢如果直接摘要又会丢掉后续排障需要的证据。TencentDB Agent Memory 的短期记忆方案选择“上下文卸载”把完整结果挪到外部文件只把任务状态和必要摘要留给模型。完整工具结果 - 写入 refs/*.md 工具调用摘要 - 写入 offload JSONL 任务状态结构 - 更新 Mermaid MMD 上下文注入 - 只放 Mermaid 任务地图 需要细节时 - 按 node_id/ref 回查原文这个链路的核心是让 Agent 不必背着所有日志继续工作。它只需要知道任务走到哪、下一步是什么、证据存在哪里。图长任务把完整工具结果外置只把任务地图和证据索引留在上下文中。一个简化后的 hook 流程大致是after_tool_call └─ 收集 ToolPair ├─ 完整结果写 refs ├─ L1 总结工具调用 ├─ L1.5 判断任务边界 ├─ L2 更新 Mermaid 图 └─ L3 根据 token 压力压缩历史上下文最终注入给 Agent 的可能不是一堆日志而是一张任务地图图Context Offload 将工具结果、任务摘要与 Mermaid 任务地图分层保存按需回查证据。每个节点背后关联node_id或ref。当 Agent 需要回看某次搜索结果、某段测试输出或某个大文件片段时再按引用回查完整材料。这其实是把“上下文窗口”从原始记录容器改造成任务状态面板。模型看到的是结构化进展而不是未经整理的工具噪声。​L1.5 Boundary Detector​任务图能不能复用取决于边界判断短期上下文卸载里有一个容易被忽视的点工具调用并不天然知道自己属于哪个任务。用户可能连续提出帮我修这个 bug 顺便看下测试为什么慢 再把刚才那个实现整理成文档这些动作可能属于同一个工作流也可能已经切到了新任务。如果所有工具调用都塞进同一个 Mermaid 文件任务地图会混乱如果每个动作都新建一张图又会打断上下文延续。L1.5 的职责就是判断任务边界当前工具调用应该复用 active MMD还是开启新的任务图。它并不负责长期记忆沉淀却直接影响短期任务态势是否可靠。这说明上下文治理不只是“少放点内容”。它还需要识别任务阶段、任务归属和状态迁移。否则再漂亮的 Mermaid 图也可能变成误导 Agent 的噪声。​Engineering Trade-offs​这套架构强在完整也复杂在完整TencentDB Agent Memory 的设计很完整但完整也意味着系统复杂度上升。几个关键模块的收益和风险可以拆开看模块工程收益可能的坑L0-L3 分层结构清晰压缩后仍可追溯Pipeline 长调试和观测门槛更高LLM 抽取 L1/L2/L3语义质量比纯规则更强模型稳定性会影响记忆质量JSONL DB 双写兼顾原始证据、索引和检索一致性边界需要设计清楚offload Mermaid节省 Token任务态势更清晰Hook 依赖强patch 或生命周期失效会影响链路多宿主抽象OpenClaw、Hermes、Gateway 等场景可复用适配层、权限、生命周期管理更复杂L2/L3 直接由 LLM 读写 Markdown 文件灵活性很高但也要求 prompt、沙箱和后处理足够稳。项目里已经有 workspace 限制、备份、软删除清理等机制如果要进入更大规模的生产场景还可以继续补场景块 schema 校验、Persona diff 审核、异常回滚策略。另一个需要评估的是成本。L1 抽取 prompt、去重判断、Persona 更新频率、召回阈值都会影响系统资源消耗。即便很多动作可以异步执行也需要按业务场景调参不是所有记忆都值得长期保存不是所有会话都需要高频抽取也不是所有任务都需要向量召回。​Platform Implication​内部 Agent 记忆不应从“向量库中心化”开始如果把这套思路迁移到企业内部 Agent 平台有三个启发比较直接。第一向量库适合做候选召回不适合承载全部记忆结构。内部研发 Agent 至少需要区分原文证据、结构化事实、场景上下文和长期画像。只有一个向量库会把“能搜到相似内容”和“真正理解工作关系”混在一起。第二压缩必须带回查链路。很多 Agent 失败不是因为没有总结而是总结丢了关键证据。更可靠的链路应该是Persona / Scene / Mermaid 提供高层结构索引负责定位原文负责核验。第三短期上下文治理和长期记忆同样重要。真实研发任务里单次 session 的工具日志爆炸比跨会话遗忘更频繁。把工具结果外置把任务状态符号化往往比盲目扩大 context window 更有性价比。结语Agent Memory 的边界决定 Agent 能不能长期协作TencentDB Agent Memory 最有价值的地方不是用了 SQLite、向量库、Mermaid 或 LLM 抽取这些技术单独看都不新。它真正值得讨论的是架构取舍原始证据要保留 结构事实要抽取 场景上下文要组织 长期画像要稳定 短期日志要卸载 压缩结果要能回查 失败路径要能降级这套设计把 Agent Memory 从“记住几段历史”推进到“管理工作现场”。它既处理跨会话经验沉淀也处理单次任务的上下文爆炸既强调高层抽象也保留低层证据既考虑召回质量也考虑缓存、降级和工程稳定性。真正落到内部研发 Agent 上还需要回答一个更细的问题哪些信息应该进入用户级长期记忆哪些应该进入项目级共享记忆哪些只应该停留在单次任务的短期地图里。这个边界一旦清晰Agent 才有可能从一次性问答工具变成懂项目、懂团队习惯、还能自己翻工作笔记的协作者。