这段时间我在做一件听起来顺理成章、做起来却很折磨人的事把腾讯云 TencentDB Agent Memory 当作 Codex CLI 的长期记忆后端让同一个编码 Agent 在不同会话之间记得项目背景、记得上次改过哪几个文件、记得已经踩过的坑。单元测试里记忆写入和向量检索都正常召回结果也漂亮可真接到 Codex 上思维链路跑得通代码照写唯独“记忆”像根本不存在。查了两天把两边关键源码翻完结论不是配置写错也不是网络时延而是架构层面的硬冲突——两边对“记忆”这个词的理解完全不是一个东西。这篇文章把整个梳理过程、源码定位和最终采用的桥接方案完整记下来给同样想给 Agent 接持久记忆的人一个参考。1. 先别急着调参还原一下冲突现场1.1 我最初设想的集成路径先说背景。我手上有个长期维护的代码库用 Codex CLI 在终端里做日常编码辅助。Codex 本身只有会话内上下文关掉终端它就“失忆”了所以我想给它加一层长期记忆把每次会话里产生的关键信息——需求背景、文件结构、踩坑记录、决定用的方案——抽出来写进 TencentDB Agent Memory。我最初的架构设想很直白Codex CLI 作为交互入口通过 MCP 协议暴露一个记忆工具集供 Codex 在对话中调用记忆工具内部走 TencentDB Agent Memory 的 SDK做向量化、写入、检索每次会话结束后把本地会话记录汇总、固化回记忆库。这个方案在当时看起来是最“正统”的MCP 是 Codex 官方支持的扩展方式TencentDB Agent Memory 官方也主打“给 Agent 用的一站式记忆存储”。结果一联调就露馅。1.2 冲突的三种典型表现我在不同阶段踩到了三种非常典型的现象现象一新会话对历史完全没有感知。我手动把一批记忆写进库向量检索单独测都能搜到。但只要开一个新的 Codex 会话问“我们之前是不是定过这个模块的命名规范”模型一律回答“我没有之前会话的记录”。现象二记忆明明被工具搜到了模型却不会用。我换了思路让模型在开场时主动调用记忆检索工具。工具确实返回了文本但模型经常把检索结果当成“工具输出”来看待不会把它当作背景知识吸收进推理。更麻烦的是返回内容一旦长了回答风格还会被带偏好像突然换了个说话习惯。现象三自动注入记忆后上下文直接被挤爆。我试过在启动脚本里预取记忆、强行拼进 prompt结果长会话里记忆块占了几千 token本来够用的上下文窗口变得捉襟见肘代码文件反而放不进去了。这三件事指向同一个结论不是我不会调参数而是这两个系统的数据模型和运行机制不匹配。1.3 为什么我愿意称之为“硬冲突”“硬冲突”这个说法是我在翻源码之后才敢用的。它区别于“软冲突”——软冲突调调参数、换个 prompt 模板就能解决硬冲突是接口契约层面的分歧除非改一端的实现否则绕不过去。具体来说TencentDB Agent Memory 眼里的“记忆”是一个个可独立度量的条目有内容、有重要性、有访问时间、有向量表示可以被精确检索。而 Codex 眼里的“记忆”是线性消息流一条条消息按顺序排列靠模型窗口硬记。这两套模型之间没有天然的翻译层这才是所有问题的根源。2. TencentDB Agent Memory 的架构拆解2.1 存储模型一行记忆里到底塞了什么先把 TencentDB Agent Memory 这一侧拆清楚。它本质是一个“为 Agent 设计的数据库”底层兼顾了结构化数据和向量数据。以我手头接触到的 SDK 为例一条记忆记录的核心字段大概是这样字段类型说明memory_id字符串记忆唯一 ID写入时自动生成agent_id字符串属于哪个 Agent租户级隔离session_id字符串来源会话 ID可空content文本记忆正文模型直接可读content_type枚举fact / decision / error / preference 等embedding向量文本向量用于相似度检索importance浮点重要性评分比如 0.0~1.0access_count整数被检索次数用于温热管理created_at / last_access_at时间记录时间与最后访问时间metadataJSONB自定义扩展字段按需过滤这个设计有一个很关键的点记忆是“扁平条目”不是“对话消息”。它不关心这条记忆来自哪一轮对话的哪一条消息只关心它本身的内容、权重和可检索性。这是一个面向“查找”的数据模型而不是面向“重放”的数据模型。2.2 写入链路谁在负责把对话变成记忆实际写入流程比我预想的更复杂。调用方给出一条文本SDK 内部大致做了四件事对文本做向量化生成 embedding做近似去重计算新文本与已有记忆的余弦相似度超过阈值比如 0.92就认为是重复把向量、元数据、正文组装成一个事务写入数据库返回新的 memory_id。这套链路在 LangChain、LlamaIndex 这类框架里通常是以 Memory 抽象类或 Retriever 接口提供的。你只要调add()或save_context()框架层面会处理向量化和去重。但这里有个容易被忽略的隐含假设写入之前必须有人负责“提炼”。数据库只做存储和检索它不会自动把一段几千字的对话总结成“项目决定使用 X 方案”这样一句话。这个“提炼”动作要么由 orchestration 层的 LLM 做要么由调用方手动做。在传统 LangChain 应用里RunnableWithMessageHistory 这类组件会替你完成提炼但在 Codex 这种模型主动驱动的 Agent 里没有人替你做这件事。2.3 检索链路数据库是怎么把记忆捞出来的检索链路才是 TencentDB Agent Memory 的核心价值所在。一次查询大概走这几步用户拿到一个自然语言查询查询文本向量化在向量索引上找 top-K 相近的候选比如 K20用 metadata 过滤掉不符合条件的条目比如限定 agent_id、时间范围、importance 下限对剩余结果按相似度和其他规则排序返回最终 top-N。这一步会暴露另一个隐含假设调用方是“主动查询”的。检索是被动触发的必须有一个外部逻辑决定“现在该查记忆了”然后把查询词准备好。这个假定在 LangChain 里成立因为编排器控制每一步但放到 Codex 里这个编排器变成了模型自己它想不想查记忆、什么时候查完全不受你控制。2.4 它天生适合当“记忆”的几个设计点TencentDB Agent Memory 能被官方定位成 Agent 专用存储是有道理的混合存储向量和元数据在一套库里不用像老方案那样“向量库管语义、关系库管元数据”搞两套系统同步托管运维扩缩容、备份、监控都不用自己管TTL 和重要性支持按时间衰减、按重要性过滤避免记忆无限膨胀租户隔离不同项目、不同 Agent 可以完全隔离。这些能力单独拿出来都是好用且必要的。问题在于这些设计面向的是“应用方自己编排记忆流程”的场景而 Codex 不是这种场景。3. Codex 的会话模型与记忆扩展点3.1 Codex 眼里的“记忆”是什么很多人以为 Codex 有记忆能力其实它的“记忆”来自三个地方项目上下文文件主要是 AGENTS.md由用户在项目里显式书写属于静态文本本地会话记录每次会话存成一个 JSONL 文件记录全部消息和工具调用但只是在本地躺着默认不参与新会话上下文窗口模型当前能看到的所有内容包括系统提示、历史消息、工具结果。换句话说Codex 的“记忆”是瞬态的、线性的依靠上下文窗口硬存。它没有“长期记忆”的概念也不存在一个对外暴露记忆增删改查的接口。如果你希望它“记得”上上次的会话内容唯一原生手段是手动把历史录进新的提示词或者把关键信息写进 AGENTS.md。这就是第一块拼图Codex 的设计哲学里记忆是上下文工程的一部分而不是存储架构的一部分。3.2 从 CLI 启动到单轮请求的完整链路为了定位冲突我把 Codex CLI 的主链路读了一遍。简化后的执行流程是读取配置包括模型参数、MCP 服务器配置、工作区信息创建或恢复会话会话内容从本地 JSONL 读入进入 turn loop对话轮次循环每一轮构造请求上下文 → 调用模型 → 如果模型要求调用工具就执行工具并把结果追加进上下文 → 重复用户输入结束或达到终止条件后退出循环把完整会话写入本地 JSONL。关键在第 4 步的“构造请求上下文”。Codex 在这里做的事情是把 AGENTS.md 内容、系统提示、历史消息、最近工具结果按顺序拼成一个请求体送给 Responses API。整个过程是同步、一次性的。它没有一个“在构造上下文之前执行外部代码”的钩子。我用伪代码表示一下这个 turn loopdef run_turn(user_input): context build_context( system_promptload_system_prompt(), project_docsload_project_docs(), # AGENTS.md 等 transcriptload_current_transcript(), ) response call_responses_api(context) while response.has_tool_calls(): for call in response.tool_calls: result execute_tool(call) # MCP 工具在这里才执行 response call_responses_api(context result) return response注意这个顺序工具调用发生在模型“决定调用”之后而不是上下文构造之前。这对记忆是致命的。3.3 Codex 官方留下的三条扩展路径Codex 不是完全不能扩展它给了三条路AGENTS.md写死在项目里的说明文件模型每轮都会读到。它是注入静态知识的合法渠道但只能放静态内容无法动态查库MCP 工具通过codex mcp add注册外部工具模型在对话中决定是否调用。这是动态能力接入的官方通道但受制于“模型必须主动调用”这个前提SDK 定制用官方提供 Codex 的 Python/TypeScript 包自己封装交互流程在调用底层接口前做任何想做的事。这是自由度最高的路径但需要放弃现成的 CLI 交互体验。这三条路我都试了一遍最后确认只靠其中任何一条都接不好持久记忆。真正的解法是把多条路径组合起来再在外部补一个“会话结束沉淀”的环节。这个后面细说。4. 读源码之后我定位到的四个硬冲突4.1 冲突一记忆是“片段”Codex 要的是“消息”这是第一个在数据模型层面撞上的冲突。TencentDB Agent Memory 返回的检索结果是扁平文本片段天然没有“这条记忆是用户说的还是助手说的”这种角色属性也没有“它应该插在对话序列的哪个位置”的顺序属性。而 Codex 提交给 Responses API 的上下文是一个严格有序的 messages 数组每条消息都有明确的 rolesystem / user / assistant / tool。这就导致一个尴尬的问题你想把记忆塞进去塞在哪塞进 system模型会把记忆内容当成系统指令有时照搬执行很危险塞进 user模型可能把它当成当前用户输入产生错误的对话流塞进 assistant等于伪造了自己的发言后续引用会出问题。我试过最“不坏”的做法是把记忆块打包成一条 user 消息前面加一句“以下是从长期记忆中检索到的历史信息仅供参考”。实测能用但污染消息流而且一旦多条记忆内容互相矛盾模型会陷入混乱。这个冲突我在前面提的“现象二”里就是这么踩出来的。4.2 冲突二拉取的时机对不上请求的时机记忆检索是个“事前动作”但 Codex 的上下文构造是个“同步封装”。你需要记忆来支撑本轮回答所以理想时序应该是用户输入 → 查记忆 → 组装上下文 → 调模型。但 Codex 的内部逻辑是用户输入 → 组装上下文 → 调模型 → 模型决定调工具 → 才查记忆 → 再把结果喂回模型。这就多了一个“模型的中间决策环节”。如果模型这一轮压根没想到要查记忆那这轮回答就是无记忆的而如果我们硬把记忆查询做成一个工具让模型“必须调用”那每次对话都额外消耗一次模型往返延迟和成本都上去了。更麻烦的是工具调用返回的记忆本质上是“事后补救”。模型看到检索结果时可能已经基于无记忆的上下文写出了第一版推理不一定会回头修正。4.3 冲突三写回的路径根本不存在读 TencentDB Agent Memory 的 SDK 时我发现一个问题它提供了完美的写入接口但没有提供一个“接住 Codex 会话结束事件”的挂载点。Codex 这边每次会话结束只是默默把 JSONL 写到本地TencentDB Agent Memory 这边add()接口安安静静等着被调用。两边之间没有任何机制自动触发“把这次会话沉淀成记忆”。理论上Codex 可以在对话过程中让模型自己调用memory_add工具来写记忆但让模型“自觉做记忆管理”这件事本身就很不可靠它可能在无关紧要的地方疯狂写入也可能整个会话一份都不写。靠 prompt 约束效果全看模型心情。这就是为什么我在最终方案里增加了一个“会话结束后的外部固化脚本”而不是依赖模型自觉。4.4 冲突四检索排序逻辑和 Codex 的 token 预算打架TencentDB Agent Memory 的检索排序优化目标是“语义相似度”。它默认只关心“这条记忆和查询像不像”不关心“在固定的 token 预算下哪些记忆值得占用空间”。可 Codex 的上下文是一个有限资源。一个中等规模项目AGENTS.md 加历史消息就能花掉几万 token。这时候你再往里面塞 top-5 的记忆每条记忆平均 300 token就是 1500 token 的额外开销。如果检索结果里有几条只是“字面相似但实际毫无用途”的旧记录浪费就更明显。我在源码里也确认了 TencentDB Agent Memory 的检索结果是带score和importance的但 Codex 这一侧没有任何消费这些元数据的逻辑。两边各自的“排序指标”不对齐结果就是数据库觉得“这条最相关”Codex 却觉得“这玩意占地方”。所以后面桥接方案里我必须在网关层自己做一道“二次筛选”按重要性和新鲜度压缩记忆块再交给模型。5. 我采用的桥接方案用 MCP 包一层“记忆网关”5.1 方案选型为什么不改 Codex 源码面对四个硬冲突最直接的思路是 fork Codex 改源码在上下文构造前硬插一个记忆检索步骤。这确实能打通“事前注入”的问题但我不推荐。原因有三个第一Codex 迭代很快我 fork 的版本撑不过两轮升级第二改源码需要重新编译和维护个人项目扛不住第三Codex 上游其实也在演进记忆能力现在做深度定制很可能做几个月就被官方功能覆盖了。所以我的选择是保留 Codex CLI 原样在 MCP 工具层解决“动态读”在外部脚本层解决“自动写”在 AGENTS.md 层解决“模型自觉性”再用一个轻量 Python 服务把三者串起来。这样所有改动都在“外围”升级 Codex 不受影响。5.2 记忆网关的组成与实现整个桥接方案由四块组成一个 MCP 服务器暴露三个工具memory_search、memory_add、memory_recent一份 Codex 的 MCP 配置把记忆网关挂上去一份 AGENTS.md告诉模型“什么时候查、什么时候写”一个会话结束后的固化脚本把本地 JSONL 里的关键信息提炼成记忆条目。先看 MCP 服务器的核心代码我用 Python 写尽量精简# memory_bridge.py from mcp.server.fastmcp import FastMCP import agent_memory_sdk as sdk # TencentDB Agent Memory 的 Python SDK示例命名 mcp FastMCP(memory-bridge) mcp.tool() def memory_search(query: str, limit: int 5) - str: 按语义检索与当前问题相关的历史记忆返回文本列表。 hits sdk.search(queryquery, top_klimit, agent_idmy-project) if not hits: return 没有检索到相关记忆。 return \n---\n.join(f[重要性 {h.importance:.1f}] {h.content} for h in hits) mcp.tool() def memory_add(content: str, importance: float 0.5) - str: 把一条值得长期保留的信息写入记忆库。 sdk.add(contentcontent, metadata{importance: importance}) return 已写入记忆。 mcp.tool() def memory_recent(hours: int 24, limit: int 10) - str: 获取最近指定时间内写入的记忆用于会话开始时的背景补全。 items sdk.recent(hourshours, agent_idmy-project, top_klimit) if not items: return 最近没有写入记忆。 return \n---\n.join(i.content for i in items)然后把它挂进 Codex 的配置我这边用的是~/.codex/config.toml[mcp_servers.memory] command python args [memory_bridge.py]AGENTS.md 里我写了一份很明确的规范让模型的行为可预期## 记忆使用规范 - 每次会话开始先调用 memory_recent 查看近期进展再调用 memory_search 检索与本任务直接相关的记忆。 - 当确定了关键决策、踩坑经验、模块约定时调用 memory_add 写入importance 按影响范围给 0.3~0.9。 - 记忆检索结果只作为背景参考如果与当前代码冲突以当前代码为准。 - 不要写入临时性细节如当前行号、临时调试输出不要写入显而易见的事实。这一步把“记忆读取”从系统级前置动作变成了模型可执行的工具调用。虽然不是 100% 可靠但配合 AGENTS.md 的强制语气实测大多数会话都会遵守。5.3 会话结束时的记忆固化脚本模型自觉写记忆靠不住所以我还做了一个外部兜底用一个包装脚本包住codex exec命令会话结束后自动解析最新生成的 JSONL 会话记录让一个便宜的总结模型提炼出该保留的条目统一写入记忆库。简化版本的思路是这样的codex exec $ LATEST_SESSION$(ls -t ~/.codex/sessions/*.jsonl | head -1) python summarize_session.py $LATEST_SESSIONsummarize_session.py里做的事情不复杂把会话里所有 user 消息和 assistant 消息抽出来喂给一个文本模型让它输出三条以内的“值得长期保留的事实”每条不超过 80 字然后逐条调memory_add写入importance 由总结模型给定。实测下来有几个注意点去重要控制好同一个项目反复跑很容易写出重复记忆。我利用 TencentDB Agent Memory 的相似度去重机制把去重阈值调高了一些保证同义表述也能命中。只总结决策与坑不总结过程会话里大部分内容是“改了这个函数再跑测试”这种过程性内容没有长期价值固化前就要过滤掉。时间粒度要统一固化脚本建议用 cron 或终端集成跑不要每次手动执行否则坚持不下来。5.4 实测效果与仍然存在的边界接入之后效果是肉眼可见的新会话开头模型会主动说“我先查一下相关记忆”然后给出之前定过的规范和踩坑记录。至少“同一个问题问两遍”这种蠢事很少再发生了。但也要说实话这个方案不是银弹。边界很清楚依赖模型自觉AGENTS.md 能提高自觉率但不是 100%偶尔还是会忘时效性差固化脚本是“会话结束后”才写记忆的会话中途崩溃、被强杀本轮内容就丢了并发会话会打架同一个项目同时开两个 Codex 会话时记忆写入需要额外的锁和版本控制否则后写的把先写的覆盖了检索结果仍可能“占着位置没用”网关层的二次压缩只是缓解没有根治排序指标不对齐的问题。这个方案我用了大概三周整体收益大于成本尤其是对跨天、跨周的项目维护场景价值很明显。6. 常见问题排查与速查表把这段时间踩过的坑整理成一张速查表遇到问题先对号入座症状可能原因排查与解决Codex 从不调用记忆工具AGENTS.md 没被加载或规范语气不强确认 AGENTS.md 在项目根目录且命名正确把“先查记忆”写成命令式语气memory_search 总是返回空agent_id 过滤过严或记忆库里本来就空先不传 agent_id 试一次检查固化脚本是否真的成功写入了模型把记忆当用户输入记忆以 user 角色注入模型无法分辨改用 MCP 工具返回值注入不要直接拼进消息流上下文长度经常超限记忆检索 top_k 太大或记忆块本身过长调小 limit在网关层按 importance 截断只保留摘要部分重复写入大量相同记忆去重阈值太低同义句被判为不同内容调高相似度阈值固化脚本里先 search 再 add会话中途崩溃本轮记忆全丢固化脚本只在会话正常结束时执行把固化逻辑改成轮询本地 JSONL 文件变化增量更新如果你也想复现这套方案我的建议是先把最小闭环跑起来——只接一个 MCP 服务器手动memory_add几条记忆然后在新会话里问“有没有关于 X 的记录”。确认模型能搜到、能引用之后再加自动化固化脚本。千万不要一上来就把四个组件全铺开出了问题根本不知道是哪一环坏了。我个人在这几天的实践里最大的体会是给 Agent 接记忆难的从来不是存储而是“时机的适配”。数据库做得再好如果 Agent 的运行时没有在正确的时机给你入口一切能力都等于不存在。所以在选型前先花时间读一读 Agent 的 turn loop 源码搞清楚它在哪里暴露钩子、在哪里是封闭的能帮你省掉后面几周的折腾。