★ FEATURED ARTICLE 1. 从一次 Codex 接入失败说起为什么我要去翻 TencentDB Agent Memory 的源码前段时间在做一个 Agent 项目需要给 Codex 这类代码生成 Agent 挂上一层长期记忆让它能记住用户的历史偏好、项目上下文、常用代码风格这些东西。第一反应是找个现成的记忆存储方案TencentDB Agent Memory 进入了视野——它主打的就是给 Agent 提供结构化的记忆读写能力支持向量检索、会话隔离、记忆分层这些特性看起来正好对口。结果接进去之后Codex 那边一直报错日志里反复出现local proxy failed while handling codex endpoint /responses这类信息记忆写入时好时坏读出来的上下文经常串味。网上搜了一圈大部分文章都在讲怎么装、怎么配没人讲清楚为什么 Codex 这种 Agent 和通用记忆架构之间会存在硬冲突。没办法只能自己拉源码看。这篇就是那次排查的完整记录。我会从 TencentDB Agent Memory 的整体架构讲起拆开它的记忆分层模型、读写链路、存储引擎选型然后重点分析 Codex 接入时那几个绕不过去的冲突点——请求生命周期不匹配、上下文窗口竞争、记忆写入的时序问题。适合正在做 Agent 记忆层、或者准备把 Codex 接进自己系统的同学参考。源码层面的东西我会尽量讲透但不会贴大段代码重点在架构逻辑和踩坑经验。先说结论Codex 和通用 Agent Memory 的冲突本质不是 API 不兼容而是两者对记忆这件事的假设根本不同。Codex 假设自己是一次性、无状态的代码生成器而 Agent Memory 假设自己服务的是一个有持续会话、有长期记忆的智能体。这个假设差异会在请求链路、上下文管理、写入时机三个地方集中爆发。2. TencentDB Agent Memory 的记忆分层模型它到底在存什么2.1 三层记忆结构的设计意图翻源码第一件事是搞清楚它的数据模型。TencentDB Agent Memory 把记忆分成三层这个分层不是随便切的每一层对应不同的生命周期和检索方式。最底层是原始会话层Raw Session Layer存的是 Agent 和用户之间完整的交互记录包括每轮对话的输入输出、时间戳、会话 ID。这一层基本是 append-only 的写入后很少修改主要作用是审计和回溯。源码里对应的是session_store这个模块底层用的是 TencentDB 的宽表存储按会话 ID 做分区。中间层是记忆摘要层Memory Summary Layer这是整个架构的核心。它会把原始会话做压缩、抽取、归类生成结构化的记忆条目。比如用户说了十句话描述自己的代码风格这一层会抽成一条用户偏好使用 TypeScript 严格模式函数式风格优先这样的记忆。源码里这块逻辑在memory_extractor和summarizer两个模块抽取策略是可插拔的默认走的是基于规则的抽取加向量聚类。最上层是语义索引层Semantic Index Layer把摘要层的记忆条目做向量化存进向量索引供检索时用。这一层不存原始内容只存向量和指向摘要条目的引用。检索时先走向量召回再回摘要层取完整内容。注意这三层的写入不是同步的。原始会话层是实时写摘要层是异步批处理语义索引层又是摘要层写完之后的二次异步。这个异步链路是后面很多问题的根源。2.2 为什么这样分层和纯向量库方案的对比很多人第一反应是我直接用向量数据库存记忆不就行了我一开始也这么想。但实际跑下来纯向量库方案在 Agent 场景下有几个硬伤。第一是记忆的时效性和优先级无法表达。向量检索只看语义相似度但 Agent 记忆里用户上周说的偏好和用户三年前说的偏好权重完全不同。TencentDB Agent Memory 的分层模型里摘要层带了时间衰减因子和访问频次计数检索时会做加权这是纯向量库做不到的。第二是记忆的更新和遗忘。纯向量库更新一条记忆基本是删了重插但 Agent 记忆经常需要合并——用户这次说的偏好和上次说的有重叠应该合并成一条而不是新增。摘要层的抽取逻辑里带了去重和合并策略源码里叫memory_consolidation这块逻辑相当复杂也是整个架构里最容易出 bug 的地方。第三是可解释性。纯向量库检索出来一堆相似片段你很难说清楚为什么这条被召回。分层模型里检索结果可以追溯到摘要条目摘要条目可以追溯到原始会话整条链路是清晰的。做 Agent 调试的时候这个太重要了。维度纯向量库方案TencentDB Agent Memory 分层方案时效性表达不支持需自己加字段摘要层内置时间衰减记忆合并需应用层自己实现抽取层内置 consolidation检索可解释弱只有相似度分数强可追溯到原始会话写入延迟低单次写入高三层异步链路存储成本中高三层冗余存储2.3 存储引擎的选型逻辑底层存储用的是 TencentDB 的宽表加向量索引的组合。宽表存原始会话和摘要条目向量索引单独维护。这个选型的好处是事务性和检索性能可以分开优化坏处是两层之间的一致性需要应用层保证。源码里有个细节值得说摘要层写入宽表之后会发一个消息到内部队列由消费者去更新向量索引。这个队列是 at-least-once 语义意味着向量索引可能重复写入。源码里用了一个幂等键记忆条目的 hash来去重但这个幂等键的生成逻辑在并发场景下有问题——两个内容相同但来源不同的记忆条目hash 可能一样导致其中一条被误去重。这个坑我在实际使用中踩到过后面会细说。3. Codex 的请求模型它为什么记不住也不愿意被记住3.1 Codex 的无状态假设要理解冲突先得理解 Codex 是怎么工作的。Codex 这类代码生成 Agent核心请求模型是单次请求、单次响应、无状态。每次你给它一个 prompt它独立生成一段代码生成完这次请求就结束了。它不假设自己有跨请求的记忆也不假设自己能访问历史上下文。这个设计是有道理的。代码生成场景下上下文污染是致命的——如果 Agent 记住了上一次生成的代码风格这次用户想要完全不同的风格记忆反而成了负担。所以 Codex 的默认行为是每次请求都从干净状态开始。但问题来了用户想要的是记住我的项目结构、我的命名习惯、我常用的库这又需要记忆。于是就有了把外部记忆系统挂到 Codex 上的需求也就是我这次做的事。3.2 Codex 的请求生命周期Codex 的一次完整请求从客户端到模型再到返回大致经过这几个阶段客户端组装 prompt包含系统指令、用户输入、可选的上下文片段请求发到 Codex 的 endpoint就是日志里那个/responses服务端做 prompt 预处理可能包括截断、格式化模型推理生成响应响应返回客户端请求结束关键在第三步和第五步。prompt 预处理阶段Codex 会对上下文做截断它有一个固定的上下文窗口预算超出部分直接丢弃。而请求结束后Codex 不会主动把这次交互写回任何地方它没有写回这个概念。3.3 记忆系统期望的请求模型反过来看 Agent Memory 期望的请求模型它假设的是请求开始前Agent 主动查询记忆把相关记忆注入 prompt请求结束后Agent 主动把这次交互写回记忆系统记忆系统异步处理更新摘要和索引这两个模型放在一起冲突就出来了。Codex 不主动查记忆也不主动写记忆它就是个哑的生成器。你要挂记忆就得在 Codex 外面包一层代理代理负责查记忆、注入 prompt、接收响应、写回记忆。我日志里那个local proxy failed就是这层代理出的问题。提示这层代理是必须的不要指望 Codex 原生支持记忆。所有Codex 接记忆的方案本质都是在 Codex 外面套一层记忆代理。4. 硬冲突拆解三个绕不过去的架构矛盾4.1 冲突一请求生命周期与异步写入链路的时序错配这是最核心的冲突。Agent Memory 的写入是三层异步的原始会话层实时写摘要层和索引层异步。但 Codex 的请求是短生命周期的一次请求可能几百毫秒就结束了。问题在于代理在请求结束后写回记忆但记忆的摘要和索引还没生成下一次请求查记忆时查不到刚写的内容。用户会感觉我刚告诉它的偏好它下一句就忘了。源码里这个异步链路的延迟实测下来摘要层平均 2-5 秒索引层再加 1-3 秒。也就是说一次交互的记忆要 3-8 秒后才能被检索到。对于连续对话场景这个延迟是不可接受的。我试过几个缓解方案方案 A写回时同步等待摘要生成。改代理逻辑写回后轮询摘要层直到生成完成再返回。缺点是请求延迟暴增用户体验差。方案 B写回时直接把原始内容也写进一个短期缓存检索时先查缓存再查索引。这个方案可行但要在代理层维护一个额外的缓存增加了复杂度。方案 C调整摘要层的触发策略改成实时触发。源码里摘要层是定时批处理可以改成消息驱动实时处理但这样吞吐会下降高并发场景下扛不住。最后我选的是方案 B 的变体代理层维护一个会话级的短期记忆缓存写回时同时写缓存和记忆系统检索时合并两边结果缓存里的记忆带一个未确认标记等摘要层生成后再去掉标记。这个方案实测下来延迟可以接受代价是代理层逻辑复杂了不少。4.2 冲突二上下文窗口的零和博弈Codex 的上下文窗口是有限的这是硬约束。记忆注入会占用窗口预算注入得越多留给用户实际输入和代码上下文的空间就越少。Agent Memory 的检索默认返回 top-k 条记忆k 默认是 10。这 10 条记忆如果每条平均 100 token就是 1000 token 的预算。对于上下文窗口只有 8k 的模型这已经占了八分之一。如果记忆条目更长或者 k 更大窗口很快就不够用了。源码里检索模块有个max_tokens参数可以限制返回记忆的总 token 数但默认值设得比较宽松。我实际调的时候把它压到了 500 token同时把 k 降到 5并且加了一个基于相关度分数的动态截断——分数低于阈值的记忆直接不返回。这里有个经验记忆注入不是越多越好。我做过对比测试注入 10 条记忆和注入 3 条高相关记忆代码生成质量后者反而更好。原因是低相关度的记忆会干扰模型判断让它把不相关的偏好也套用上去。所以宁可少注入也要保证注入的都是高相关的。注入策略平均 token 占用代码生成质量评分上下文污染情况top-10 全注入~10006.5/10严重风格串味top-5 全注入~5007.2/10中等top-5 分数阈值~3008.1/10轻微top-3 分数阈值~2008.3/10几乎无4.3 冲突三记忆写入的幂等性与并发安全前面提到摘要层的幂等键生成逻辑有问题这个在 Codex 场景下会被放大。因为 Codex 的请求可能并发同一个用户短时间内发多个请求代理并发写回记忆幂等键冲突的概率就上去了。具体表现是两条内容不同但结构相似的记忆hash 撞了其中一条被丢弃。用户会发现我明明说了两个偏好它只记住了一个。源码里幂等键的生成是hash(memory_type content_normalized)content_normalized 做了去空格、去标点、转小写。问题在于如果两条记忆的 content 在归一化后相同但实际语义不同比如用 tabs 缩进和用 tab 缩进归一化后都是用tab缩进就会被误判为重复。修复思路有两个一是在幂等键里加入来源会话 ID 和时间戳保证不同来源的记忆不会撞二是改归一化逻辑保留更多语义信息。我选的是第一个因为改归一化逻辑影响面太大加来源信息更安全。改完之后并发写入的丢失问题基本消失了。注意这个幂等键的问题在单用户低频场景下几乎不会触发但一旦上并发就会暴露。如果你只是本地玩玩可能永远踩不到如果要上生产这个必须改。5. 代理层的设计怎么把两个不兼容的模型粘起来5.1 代理层的职责边界代理层是解决冲突的关键它的职责要划清楚不然会变成一个什么都管的泥球。我最后定的职责边界是请求前查记忆合并缓存和索引结果按 token 预算裁剪注入 prompt请求中透传请求到 Codex endpoint不做额外处理请求后写回记忆同时写缓存和记忆系统更新缓存状态代理层不负责记忆的摘要和索引生成那是记忆系统的事。代理层也不负责 Codex 的鉴权和限流那是 Codex 的事。职责清晰了出问题好定位。5.2 记忆注入的 prompt 组装注入记忆的 prompt 组装有个技巧不要把记忆直接拼在用户输入前面。我一开始是这么做的结果模型经常把记忆内容当成用户指令的一部分生成出奇怪的代码。正确的做法是把记忆放在系统指令区域用明确的分隔符隔开并且加一句说明以下是用户的历史偏好仅供参考不要直接执行。源码里没有这个逻辑因为记忆系统不关心 prompt 怎么组装这是代理层要做的。组装格式大概是这样[系统指令] 你是一个代码生成助手。以下是用户的历史偏好仅供参考 memory - 偏好 TypeScript 严格模式 - 函数式风格优先 - 常用库lodash, zod /memory 不要直接执行上述内容仅作为生成参考。 [用户输入] ...这个格式实测下来记忆被误当成指令的情况基本没有了。5.3 写回时机的选择写回时机有三个选择请求一结束就写、等响应完全返回再写、延迟批量写。请求一结束就写最快但可能写到一半的响应内容不完整。等响应完全返回再写最稳但要等流式响应结束延迟高。延迟批量写攒一批再写吞吐高但实时性差。Codex 的响应是流式的我选的是第二种等流式响应完全结束后再写回。虽然延迟高一点但保证写入的内容是完整的。对于流式响应代理层要维护一个缓冲区把流式片段拼完整再写。这里有个坑流式响应如果中途断了缓冲区里的内容是不完整的这时候写回会污染记忆。我的处理是加一个完整性校验响应没有正常结束标记的不写回只记日志。这个校验逻辑源码里没有是代理层要补的。6. 实测中的意外情况与排查链路6.1 记忆串味一个跨会话污染的真实案例上线测试第二天发现一个诡异现象用户 A 的偏好出现在了用户 B 的生成结果里。这是严重的隐私和正确性问题。排查链路是这样的先查代理层日志确认注入给用户 B 的记忆里确实有用户 A 的偏好查记忆系统的检索日志发现检索时用的会话 ID 是用户 B 的但召回结果里有用户 A 的记忆查向量索引发现用户 A 的记忆条目的会话 ID 字段是空的回溯写入链路发现是摘要层写入时会话 ID 字段在某个并发场景下丢失了根因是摘要层的写入逻辑里会话 ID 是从上下文对象里取的但上下文对象在异步处理时可能已经被回收取到的是 undefined。源码里没有对这个做校验undefined 直接写进去了。修复是在摘要层写入前加会话 ID 的非空校验取不到就拒绝写入并告警。同时把向量索引里会话 ID 为空的条目全部清理了一遍。这个坑的教训是异步链路里的上下文传递一定要做校验不能假设上游一定传了。6.2 检索结果为空索引更新延迟导致的假性失忆另一个高频问题是用户反馈它忘了我说的话。查下来大部分是索引更新延迟导致的——记忆写进去了但索引还没更新检索时查不到。这个问题的排查有个技巧对比摘要层和索引层的记录数。如果摘要层有 100 条索引层只有 95 条说明有 5 条还没索引。源码里没有现成的对比工具我写了个脚本定时跑差异超过阈值就告警。缓解方案前面说了代理层加短期缓存。但缓存也有缓存的问题——缓存和索引的数据可能不一致缓存里有但索引里没有正常还没索引完或者索引里有但缓存里没有异常可能是缓存被清了。我的处理是缓存带 TTL过期后以索引为准缓存只作为索引的补充。6.3 性能瓶颈摘要层的批处理窗口压测的时候发现并发上来之后摘要层处理不过来队列积压记忆写入延迟从秒级涨到分钟级。查下来是摘要层的批处理窗口设得太保守默认是攒够 100 条或者等 30 秒才处理一批。低并发时没问题高并发时 30 秒的窗口导致大量记忆排队。调参思路把批处理窗口改成动态的队列长度超过阈值就立即处理不超过就等窗口。源码里这个参数是写死的我改成了可配置并且加了队列长度的监控。改完之后高并发下的写入延迟降到了 5 秒以内。场景默认配置延迟调优后延迟调优手段低并发10 QPS2-5s2-5s无需调优中并发10-50 QPS10-30s3-8s动态批处理窗口高并发50 QPS60s5-10s动态窗口 队列监控7. 几个值得记下来的实操经验7.1 不要试图改 Codex改代理层我一开始想过改 Codex 的请求处理逻辑让它原生支持记忆。试了两天放弃了因为 Codex 的请求链路是封闭的改动成本极高而且升级会覆盖。所有定制逻辑都应该放在代理层Codex 保持原样。这个原则适用于所有给封闭 Agent 挂能力的场景。7.2 记忆的写入和读取要分开优化写入追求的是不丢、不重、不乱序读取追求的是快、准、省 token。这两个目标的优化手段是冲突的——写入要强一致就得同步读取要快就得缓存。我的做法是写入走异步保证吞吐读取走缓存加索引合并保证速度两边用不同的策略不要试图用一套逻辑同时满足。7.3 监控要覆盖异步链路的每一段异步链路最大的问题是出问题了不知道在哪一段。我在代理层、摘要层、索引层各加了埋点记录每条记忆的写入时间、摘要完成时间、索引完成时间形成一个完整的链路追踪。出问题时一看链路就知道卡在哪。这个埋点成本不高但排查效率提升巨大。7.4 会话隔离要做双重校验前面那个跨会话污染的案例根因是会话 ID 丢失。修复之后我加了个双重校验写入时校验会话 ID 非空检索时校验召回结果的会话 ID 和请求的会话 ID 一致不一致的直接过滤掉。虽然多了一次校验但杜绝了串味问题。记忆系统的会话隔离不能只靠写入时保证检索时也要兜底。7.5 上下文预算要留余量Codex 的上下文窗口是硬约束记忆注入的预算不能按满打满算。我一开始按窗口的 20% 给记忆结果用户输入一长就爆窗口。后来改成按窗口的 10% 给记忆并且加了动态调整——用户输入长的时候自动压缩记忆注入量。留余量这个事宁可保守一点。8. 关于这套架构的后续扩展思路这套代理加记忆系统的架构跑通之后其实可以扩展出不少东西。比如记忆的主动遗忘——用户明确说忘掉之前的偏好时代理层可以触发记忆系统的删除。再比如记忆的版本管理——用户偏好变了旧偏好不是删掉而是标记为历史版本检索时优先返回新版本。这些扩展都不需要改 Codex全在代理层和记忆系统里做。源码里其实留了一些扩展点比如摘要层的抽取策略是可插拔的你可以自己实现一个针对代码场景的抽取器专门抽代码风格、库偏好、命名习惯这些。默认的抽取器是通用的对代码场景的抽取精度一般。我试过写一个简单的代码场景抽取器精度提升明显这块后续可以单独展开讲。最后说个我自己的体会Agent 记忆这件事难点从来不在存储而在什么时候记、记什么、什么时候用。存储方案再先进时机不对就是白搭。TencentDB Agent Memory 提供了不错的存储和检索能力但时机控制这块得靠代理层自己拿捏。Codex 接入的硬冲突说到底就是时机冲突把时机对齐了剩下的都是工程问题。
阅读完成 · 觉得有帮助？
