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 CLI 的扩展能力在不同版本间差异较大，而输入预处理是一个相对稳定的边界。你可以在调用 Codex 之前，用一个包装脚本先做记忆召回，把召回结果拼进输入里。这样即使 Codex 内部结构变了，你的记忆层也不用跟着改。

提示：不要试图去 patch Codex 的源码来插入记忆逻辑。升级一次就全废，维护成本极高。包装脚本 + 标准输入输出是最稳的接法。

2.3 为什么不让 Hindsight 直接当"外挂大脑"

有人会想：既然有记忆库，那干脆让模型每次都去查库不就行了？这个思路的问题在于延迟和确定性。让模型自己决定"要不要查记忆、查什么"，会引入额外的推理轮次，延迟翻倍不说，还经常出现该查不查、不该查乱查的情况。正确做法是由外层流程强制召回，把召回结果作为既定上下文喂给模型，模型只负责用，不负责找。

3. 记忆写入：从一次 Codex 会话里抽出什么

写入环节决定了记忆库的质量上限。垃圾进垃圾出，如果写入的都是流水账，召回再准也没用。

3.1 值得写入的四类信息

我在实际项目里把值得沉淀的信息归为四类，每类对应不同的抽取规则：

1. 项目事实：技术栈、目录结构约定、命名规范、依赖版本约束。这类信息变化慢，一旦写入可以长期复用。
2. 决策记录：为什么选 A 不选 B。比如"构建脚本坚持用 esbuild 而不是 webpack，因为冷启动要控制在 200ms 内"。这类信息价值极高，因为它承载了推理过程，下次遇到类似选择时能直接复用判断。
3. 踩坑经验：某个报错的原因和修法。比如"Codex 在 Windows 下路径分隔符处理有坑，配置里统一用正斜杠"。
4. 用户偏好：代码风格、注释语言、提交信息格式。这类信息让 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 太小，可能漏掉关键记忆。我的经验值是K=5 到 8。具体取值看你的记忆库规模：

还有一个技巧：设置相似度阈值。低于阈值的记忆即使进了 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_k=6, threshold=0.6): client = HindsightClient() results = client.search(user_input, top_k=top_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 开始答非所问，明明问的是构建配置，它却在回答里扯到了三个月前的接口设计。

排查链路：

1. 先打印召回结果，看 Top-K 里都是什么。果然，有几条相似度 0.55 的记忆被召回了。
2. 检查阈值配置，发现是 0.5，太低。
3. 把阈值提到 0.65，重新跑，无关记忆消失。

根因：阈值设太低，向量相似度的"语义相近"被误当成了"实际相关"。语义相近但主题不同的记忆，相似度经常在 0.5-0.6 之间，这个区间是重灾区。

修复：阈值提到 0.65，同时给记忆条目加了type过滤——当前输入是构建相关时，只召回build标签的记忆。

6.2 写入噪音：记忆库里全是废话

现象：跑了一周，记忆库涨到 800 多条，但召回质量越来越差。

排查链路：

1. 随机抽 20 条记忆看内容，发现大量"用户询问了 X"、"模型回答了 Y"这种流水账。
2. 检查写入逻辑，发现会话结束时是全量转录，没有做抽取。
3. 根因是extract_memories函数偷懒，直接把对话轮次转成了记忆条目。

修复：重写抽取逻辑，只保留四类信息（事实/决策/踩坑/偏好），其余全部丢弃。同时加了一个"去重"步骤，内容相似度超过 0.9 的记忆合并。

6.3 上下文超长：注入记忆后模型反而变笨

现象：召回 10 条记忆后，Codex 的回答质量明显下降，经常忽略用户的实际问题。

排查链路：

1. 统计注入后的 prompt 长度，发现记忆部分占了 40% 的 token。
2. 检查记忆内容，发现有些条目写得很长，一条就 200 多字。
3. 根因是记忆条目没有长度约束，写入时把整段解释都存进去了。

修复：给记忆条目加长度上限（建议 100 字以内），超长的拆成多条或压缩。同时把 Top-K 从 10 降到 6。

6.4 时间衰减用错：老记忆永远召不回

现象：三个月前的一条关键决策记忆，怎么都召不回来。

排查链路：

1. 手动查这条记忆，发现它还在库里，相似度也够。
2. 检查排序逻辑，发现时间衰减是线性的，三个月前的记忆权重被压到接近 0。
3. 根因是衰减函数没区分记忆类型。

修复：决策类记忆用对数衰减（衰减慢），临时状态类用指数衰减（衰减快）。改完之后老决策记忆能正常召回了。

6.5 并发写入冲突

现象：同时开两个 Codex 会话，会话结束时写入报错。

排查链路：

1. 看报错信息，是 SQLite 的database is locked。
2. 根因是两个写入进程同时抢锁。

修复：写入加一个简单的文件锁，或者改用支持并发写的存储。如果记忆库不大，用文件锁最省事。

7. 让记忆流程真正好用的几个经验

踩完上面那些坑之后，我总结了几条让整套流程稳定运行的经验，都是文档里不会写的。

7.1 记忆要定期"体检"

记忆库不是写完就不管了。我每个月会做一次体检：随机抽 50 条记忆，人工判断是否还有价值，把过期的、错误的删掉。同时看召回日志，找出"高频召回但低采纳"的记忆——这类记忆往往是表述有问题，需要重写。

7.2 给记忆加"有效期"

不是所有记忆都永久有效。依赖版本约束、临时的工作约定，这些都有时效。我给记忆加了一个expires_at字段，到期自动降权或归档。这样能避免老记忆干扰新决策。

7.3 召回结果要能解释

每次召回后，把"召回了哪些记忆、为什么召回"记到日志里。出问题时这是唯一的排查依据。我用的日志格式是：

[recall] query="改构建脚本" top_k=6 - mem_001 score=0.82 type=decision - mem_045 score=0.71 type=preference - mem_102 score=0.63 type=pitfall

有了这个日志，6.1 那个记忆污染的问题我五分钟就定位了。

7.4 别让记忆层成为单点

记忆层挂了不能影响 Codex 正常使用。我的做法是召回失败时降级为空记忆，让 Codex 照常工作，只是没有记忆加持。写入失败就记个日志，下次会话再补。记忆是增强，不是依赖。

7.5 从小规模开始

不要一上来就追求全自动、全量记忆。先手动维护 20-30 条核心记忆，把召回和注入跑通，确认质量后再逐步放开自动写入。我见过太多人一上来就全自动，结果一周后记忆库变成垃圾场，只能推倒重来。

8. 关于 Codex 与 Hindsight 集成的几个常见疑问

实际交流中，有几个问题被问得最多，集中回答一下。

Q：Hindsight 能不能直接作为 Codex 的插件运行？

取决于 Codex 版本是否提供插件扩展点。目前更稳的方式还是包装脚本。插件方式耦合太深，Codex 一升级就可能失效。

Q：记忆库用向量库还是关系库？

条目少于 1000 条时，关系库 + 关键词匹配就够了，简单可靠。超过 1000 条、且需要语义召回时，再上向量库。不要为了用向量库而用向量库。

Q：召回的记忆要不要让用户看到？

建议在调试阶段显示，方便判断召回质量。稳定之后可以隐藏，但在日志里保留。用户看到一堆记忆注入会干扰阅读。

Q：多个项目共用一个记忆库还是分开？

分开。不同项目的上下文差异太大，混在一起召回噪音会很高。按项目分库，或者用project标签隔离。

Q：记忆写入用大模型还是小模型？

抽取阶段用规则 + 小模型组合最划算。大模型成本高、延迟大，而且抽取这种任务小模型完全够用。只有在需要复杂判断（比如"这条信息是否与已有记忆冲突"）时才动用大模型。

这套流程我在自己的项目里跑了小半年，从最初的每天手动清理记忆，到现在基本不用管，中间踩的坑基本都在上面了。核心体会就一句：记忆流程的价值不在于记得多，而在于记得准、取得对。把召回质量做上去，比堆记忆数量重要得多。