1. 为什么要在 Codex 里接一层 Hindsight 记忆Codex CLI 用久了会有一个很明显的体感单次会话里它挺聪明跨会话就失忆。昨天刚跟它敲定的接口字段命名规范、上周踩过的构建脚本坑、某个模块为什么坚持不用某个库——这些上下文在新开一个 session 之后全部归零你得重新喂一遍。对于偶尔用用的场景无所谓但一旦把 Codex 当成日常主力开发工具这种重复解释的成本会迅速累积。Hindsight 在这里扮演的角色就是给 Codex 补上一层可检索、可沉淀、可回放的长期记忆。它不是一个简单的聊天记录存档而是把发生过的事整理成结构化的记忆条目在需要的时候按相关性召回再注入到 Codex 的上下文里。你可以把它理解成给 Codex 配了一个随身笔记本而且这个笔记本会在你提问的瞬间自动翻到最相关的那几页。这篇内容适合三类人一是已经在用 Codex CLI、想让它记住项目上下文的开发者二是正在搭 Agent 记忆流程、想找一个可落地参考方案的人三是对 Agent 记忆机制好奇、想搞清楚记忆到底怎么接进推理循环的技术同学。我会从记忆流程的整体设计讲起拆到 Hindsight 的接入点、数据怎么流转、Codex 侧怎么配置最后把我在实测中踩过的坑和排查链路完整摊开。需要先说明一点Hindsight 和 Codex 的集成方式会随版本演进下面讲的是基于常见实践的合理方案核心思路是稳定的具体字段和命令请以你本地版本为准。我尽量把为什么这么设计讲透这样即使接口变了你也能自己推导出改法。2. 先搞清楚 Hindsight 和 Codex 各自负责哪一段在动手接之前必须把两个系统的职责边界划清楚否则很容易接出一个记忆污染上下文的烂摊子。我见过不少人一上来就把所有历史对话无脑塞进 prompt结果 token 爆炸、模型注意力被稀释回答质量反而下降。2.1 Hindsight 的记忆生命周期Hindsight 的核心工作可以拆成四个阶段这四个阶段构成了它的记忆生命周期写入Capture把一次交互中有价值的信息抽取出来形成记忆条目。注意是有价值不是全量转录。一次对话里可能只有两三句话值得长期记住。结构化Structure给记忆条目打上标签、时间戳、来源、类型事实/偏好/决策/待办。结构化的程度直接决定了后面能不能精准召回。存储Store落到持久化层。可以是本地文件、SQLite也可以是向量库。选哪种取决于你的检索需求。召回Recall在 Codex 发起新一轮推理前根据当前输入去检索相关记忆按相关性排序后注入上下文。这四个阶段里召回策略是最容易做砸的一环。写入多了不怕怕的是召回不准——把不相关的记忆塞进去比不塞还糟。2.2 Codex 侧的接入位置Codex CLI 的执行链路大致是接收用户输入 → 组装上下文 → 调用模型 → 解析输出 → 执行工具/返回结果。Hindsight 的接入点有两个候选位置接入位置时机优点缺点输入预处理层用户输入后、组装上下文前实现简单不侵入 Codex 内部只能拿到原始输入缺少会话状态上下文组装钩子组装 prompt 时能拿到完整会话上下文召回更准需要 Codex 提供扩展点我的建议是优先走输入预处理层因为 Codex CLI 的扩展能力在不同版本间差异较大而输入预处理是一个相对稳定的边界。你可以在调用 Codex 之前用一个包装脚本先做记忆召回把召回结果拼进输入里。这样即使 Codex 内部结构变了你的记忆层也不用跟着改。提示不要试图去 patch Codex 的源码来插入记忆逻辑。升级一次就全废维护成本极高。包装脚本 标准输入输出是最稳的接法。2.3 为什么不让 Hindsight 直接当外挂大脑有人会想既然有记忆库那干脆让模型每次都去查库不就行了这个思路的问题在于延迟和确定性。让模型自己决定要不要查记忆、查什么会引入额外的推理轮次延迟翻倍不说还经常出现该查不查、不该查乱查的情况。正确做法是由外层流程强制召回把召回结果作为既定上下文喂给模型模型只负责用不负责找。3. 记忆写入从一次 Codex 会话里抽出什么写入环节决定了记忆库的质量上限。垃圾进垃圾出如果写入的都是流水账召回再准也没用。3.1 值得写入的四类信息我在实际项目里把值得沉淀的信息归为四类每类对应不同的抽取规则项目事实技术栈、目录结构约定、命名规范、依赖版本约束。这类信息变化慢一旦写入可以长期复用。决策记录为什么选 A 不选 B。比如构建脚本坚持用 esbuild 而不是 webpack因为冷启动要控制在 200ms 内。这类信息价值极高因为它承载了推理过程下次遇到类似选择时能直接复用判断。踩坑经验某个报错的原因和修法。比如Codex 在 Windows 下路径分隔符处理有坑配置里统一用正斜杠。用户偏好代码风格、注释语言、提交信息格式。这类信息让 Codex 的输出更贴合你的习惯。反过来不值得写入的包括一次性的调试输出、临时的变量名讨论、已经被推翻的方案。判断标准很简单——这条信息在两周后的另一个会话里还有用吗没用就别写。3.2 抽取时机与触发条件抽取不应该在每轮对话后都跑那样噪音太大。我用的触发条件是会话结束时用户主动退出或显式结束检测到决策类语句时就用 X 吧、以后都按 Y 来检测到明确的踩坑修复时原来是 Z 导致的改成 W 就好了会话结束时的批量抽取是主力后两个是补充。批量抽取的好处是可以拿到完整上下文判断哪些信息是结论性的避免把中间过程也写进去。3.3 写入格式的设计记忆条目的结构我建议至少包含这几个字段{ id: mem_20250101_001, type: decision, content: 构建脚本使用 esbuild冷启动目标 200ms 以内, tags: [build, esbuild, performance], source_session: sess_abc123, created_at: 2025-01-01T10:00:00Z, confidence: 0.9 }type用于分类召回tags用于关键词过滤confidence用于排序时降权不确定的记忆。source_session保留溯源能力万一某条记忆有问题可以回溯到原始会话。注意content字段要写成自包含的完整句子不要写成依赖上下文的片段。因为召回时它是独立出现的如果写成改成 W 就好了脱离了原始会话根本不知道在说什么。4. 召回策略怎么在正确的时候捞出正确的记忆召回是整条链路里技术含量最高的部分。做得好Codex 像是有十年工龄的老员工做得差它像个刚接手项目还爱瞎猜的新人。4.1 三种召回信号的组合我实测下来单一召回信号都不够稳需要组合使用关键词匹配对当前输入做分词和记忆的tags、content做匹配。优点是快、可解释缺点是无法处理同义表达。向量相似度把当前输入和记忆都转成向量算余弦相似度。优点是能捕捉语义缺点是可能召回语义相近但实际无关的记忆。时间衰减越新的记忆权重越高。但不是简单线性衰减而是对决策类记忆衰减慢对临时状态类记忆衰减快。组合方式我推荐加权求和后取 Top-K权重可以这样设关键词 0.4、向量 0.5、时间 0.1。这个比例不是拍脑袋是我在几十次会话里调出来的——向量权重最高是因为语义匹配的召回率明显优于纯关键词但完全依赖向量又会漏掉精确匹配的场景所以关键词保留一个不低的权重。4.2 Top-K 的 K 怎么定K 太大上下文被稀释K 太小可能漏掉关键记忆。我的经验值是K5 到 8。具体取值看你的记忆库规模记忆库条目数建议 K 值理由 1003-5库小召回精度高不需要多召回100-10005-8平衡精度和覆盖 10008-12库大需要更多候选来保证覆盖还有一个技巧设置相似度阈值。低于阈值的记忆即使进了 Top-K 也丢掉。我一般把阈值设在 0.6 左右低于这个值的召回基本都是噪音。4.3 召回结果怎么注入上下文召回出来的记忆不能直接堆在 prompt 开头那样模型容易忽略。我的做法是用明确的分隔和标签包裹并且放在用户输入之前[相关记忆] - (决策) 构建脚本使用 esbuild冷启动目标 200ms 以内 - (偏好) 注释统一用中文提交信息用英文 - (踩坑) Windows 下路径分隔符统一用正斜杠 [/相关记忆] [用户输入] 帮我把构建脚本改成支持增量编译这样模型能清楚区分这是背景知识和这是当前任务。实测下来这种结构化注入比纯文本拼接的采纳率高不少。4.4 召回失败时的兜底召回不可能每次都准。当 Top-K 里所有记忆的相似度都低于阈值时宁可不注入也不要硬塞。空记忆比错记忆好。同时可以记录这类召回失败的查询定期回看往往能发现记忆库的盲区。5. 把 Hindsight 接进 Codex CLI 的具体做法前面讲的是设计这一节讲落地。我用一个包装脚本的方式演示这是最通用、最不挑版本的接法。5.1 整体架构用户输入 → 包装脚本 → [Hindsight 召回] → 拼接上下文 → Codex CLI → 输出 ↓ [会话结束] → [Hindsight 写入] → 记忆库包装脚本负责三件事召回、拼接、写入。Codex CLI 本身不需要任何改动。5.2 召回阶段的脚本实现import subprocess import json from hindsight_client import HindsightClient # 假设的客户端 def recall_memories(user_input, top_k6, threshold0.6): client HindsightClient() results client.search(user_input, top_ktop_k) # 过滤低相似度 filtered [m for m in results if m.score threshold] return filtered def build_prompt(user_input, memories): if not memories: return user_input lines [[相关记忆]] for m in memories: lines.append(f- ({m.type}) {m.content}) lines.append([/相关记忆]) lines.append() lines.append([用户输入]) lines.append(user_input) return \n.join(lines) def main(): user_input input( ) memories recall_memories(user_input) prompt build_prompt(user_input, memories) # 调用 codex cli subprocess.run([codex, exec, prompt])这段代码的关键点是召回和拼接分离。召回逻辑可以独立测试拼接格式可以独立调整互不影响。5.3 写入阶段的触发写入放在会话结束后。如果你用的是交互式 Codex可以在退出时触发如果是codex exec这种一次性调用可以在命令返回后触发。def extract_and_store(session_log): client HindsightClient() # 用一个小模型或规则抽取记忆条目 memories extract_memories(session_log) for m in memories: client.store(m)extract_memories可以用规则正则匹配决策类语句 小模型判断是否值得记忆的组合。纯规则会漏纯模型会慢组合最实用。5.4 配置项清单把可调参数集中到一个配置文件里方便调优hindsight: top_k: 6 similarity_threshold: 0.6 weights: keyword: 0.4 vector: 0.5 time: 0.1 write_triggers: - session_end - decision_detected - fix_detected storage: type: sqlite path: ~/.hindsight/memories.db提示similarity_threshold这个值不要一次调到位。先设 0.5 跑一段时间观察召回质量再逐步往上调。调太快会把有用的记忆也过滤掉。6. 实测中踩过的坑和排查链路这一节是整篇最有价值的部分。下面这些坑我都真实踩过排查过程也完整还原你可以直接对照复现。6.1 记忆污染召回了一堆无关内容现象Codex 开始答非所问明明问的是构建配置它却在回答里扯到了三个月前的接口设计。排查链路先打印召回结果看 Top-K 里都是什么。果然有几条相似度 0.55 的记忆被召回了。检查阈值配置发现是 0.5太低。把阈值提到 0.65重新跑无关记忆消失。根因阈值设太低向量相似度的语义相近被误当成了实际相关。语义相近但主题不同的记忆相似度经常在 0.5-0.6 之间这个区间是重灾区。修复阈值提到 0.65同时给记忆条目加了type过滤——当前输入是构建相关时只召回build标签的记忆。6.2 写入噪音记忆库里全是废话现象跑了一周记忆库涨到 800 多条但召回质量越来越差。排查链路随机抽 20 条记忆看内容发现大量用户询问了 X、模型回答了 Y这种流水账。检查写入逻辑发现会话结束时是全量转录没有做抽取。根因是extract_memories函数偷懒直接把对话轮次转成了记忆条目。修复重写抽取逻辑只保留四类信息事实/决策/踩坑/偏好其余全部丢弃。同时加了一个去重步骤内容相似度超过 0.9 的记忆合并。6.3 上下文超长注入记忆后模型反而变笨现象召回 10 条记忆后Codex 的回答质量明显下降经常忽略用户的实际问题。排查链路统计注入后的 prompt 长度发现记忆部分占了 40% 的 token。检查记忆内容发现有些条目写得很长一条就 200 多字。根因是记忆条目没有长度约束写入时把整段解释都存进去了。修复给记忆条目加长度上限建议 100 字以内超长的拆成多条或压缩。同时把 Top-K 从 10 降到 6。6.4 时间衰减用错老记忆永远召不回现象三个月前的一条关键决策记忆怎么都召不回来。排查链路手动查这条记忆发现它还在库里相似度也够。检查排序逻辑发现时间衰减是线性的三个月前的记忆权重被压到接近 0。根因是衰减函数没区分记忆类型。修复决策类记忆用对数衰减衰减慢临时状态类用指数衰减衰减快。改完之后老决策记忆能正常召回了。6.5 并发写入冲突现象同时开两个 Codex 会话会话结束时写入报错。排查链路看报错信息是 SQLite 的database is locked。根因是两个写入进程同时抢锁。修复写入加一个简单的文件锁或者改用支持并发写的存储。如果记忆库不大用文件锁最省事。7. 让记忆流程真正好用的几个经验踩完上面那些坑之后我总结了几条让整套流程稳定运行的经验都是文档里不会写的。7.1 记忆要定期体检记忆库不是写完就不管了。我每个月会做一次体检随机抽 50 条记忆人工判断是否还有价值把过期的、错误的删掉。同时看召回日志找出高频召回但低采纳的记忆——这类记忆往往是表述有问题需要重写。7.2 给记忆加有效期不是所有记忆都永久有效。依赖版本约束、临时的工作约定这些都有时效。我给记忆加了一个expires_at字段到期自动降权或归档。这样能避免老记忆干扰新决策。7.3 召回结果要能解释每次召回后把召回了哪些记忆、为什么召回记到日志里。出问题时这是唯一的排查依据。我用的日志格式是[recall] query改构建脚本 top_k6 - mem_001 score0.82 typedecision - mem_045 score0.71 typepreference - mem_102 score0.63 typepitfall有了这个日志6.1 那个记忆污染的问题我五分钟就定位了。7.4 别让记忆层成为单点记忆层挂了不能影响 Codex 正常使用。我的做法是召回失败时降级为空记忆让 Codex 照常工作只是没有记忆加持。写入失败就记个日志下次会话再补。记忆是增强不是依赖。7.5 从小规模开始不要一上来就追求全自动、全量记忆。先手动维护 20-30 条核心记忆把召回和注入跑通确认质量后再逐步放开自动写入。我见过太多人一上来就全自动结果一周后记忆库变成垃圾场只能推倒重来。8. 关于 Codex 与 Hindsight 集成的几个常见疑问实际交流中有几个问题被问得最多集中回答一下。QHindsight 能不能直接作为 Codex 的插件运行取决于 Codex 版本是否提供插件扩展点。目前更稳的方式还是包装脚本。插件方式耦合太深Codex 一升级就可能失效。Q记忆库用向量库还是关系库条目少于 1000 条时关系库 关键词匹配就够了简单可靠。超过 1000 条、且需要语义召回时再上向量库。不要为了用向量库而用向量库。Q召回的记忆要不要让用户看到建议在调试阶段显示方便判断召回质量。稳定之后可以隐藏但在日志里保留。用户看到一堆记忆注入会干扰阅读。Q多个项目共用一个记忆库还是分开分开。不同项目的上下文差异太大混在一起召回噪音会很高。按项目分库或者用project标签隔离。Q记忆写入用大模型还是小模型抽取阶段用规则 小模型组合最划算。大模型成本高、延迟大而且抽取这种任务小模型完全够用。只有在需要复杂判断比如这条信息是否与已有记忆冲突时才动用大模型。这套流程我在自己的项目里跑了小半年从最初的每天手动清理记忆到现在基本不用管中间踩的坑基本都在上面了。核心体会就一句记忆流程的价值不在于记得多而在于记得准、取得对。把召回质量做上去比堆记忆数量重要得多。