Codex 工程实践(四):会话持久化与长期记忆如何协作
一个 Agent 重启后还能接着聊,和它能在新任务里想起过去的经验,是两种能力。前者需要保存和重建会话状态,后者需要从历史中筛选值得复用的信息。
《Codex 源码分析》第 19、20 章恰好展示了这两条路径。它们共享历史材料,却有不同的读取方式、更新时机和正确性要求。把两者混在一起,很容易让系统既保存了大量日志,又无法稳定地继续工作。
一、四种容易被叫作“记忆”的东西
| 对象 | 主要回答什么问题 | 对应能力 |
|---|---|---|
| 会话轨迹 | 这个任务已经发生了什么? | 恢复与审查 |
| 查询索引 | 某个会话在哪里、有哪些元数据? | 列表、搜索与定位 |
| 压缩后的历史 | 当前任务怎样在有限窗口内继续? | 上下文管理 |
| 长期记忆 | 过去哪些经验对新任务仍有价值? | 跨会话复用 |
把日志全部保存,解决的是第一行的一部分。把历史压缩成摘要,解决的是第三行。两者都不能自动保证新任务会找到正确的旧经验。
二、会话保存为什么采用事件序列
参考第 19 章介绍的 rollout JSONL,一行对应一个结构化记录。记录可以携带会话元信息、模型输入输出项、回合上下文、压缩记录或运行事件。
这种形式适合追加,也方便逐条读取和处理。但不要因此理解成“所有内容都原样保存”。本次核对的上游持久化策略包含条目选择及输出裁剪逻辑;参考章节自身也讨论了事件过滤。因此,恢复得到的是实现定义的可恢复历史,不是每个内部状态的完整镜像。
可以用下面这个示意序列理解事件如何携带语义,字段和类型名称以实际版本为准:
1 | 会话元信息 |
遇到历史压缩记录时,恢复器不能把全部旧内容和替换历史一起无脑拼接;它需要按记录的语义重建当前有效历史,否则已经压缩的内容会重新膨胀,甚至重复出现。
三、日志和索引分开,意味着要处理不一致
本地 CLI 自己生成 rollout,常规会话一般在 $CODEX_HOME/sessions/ 下按日期存放。SQLite 层由运行时维护,承担会话元数据查询及部分作业状态,sqlite_home 控制数据库目录。用户通常通过 codex resume 访问会话。需要排障时,先确认运行使用的 Codex home(默认 ~/.codex)和 sqlite_home,再按实际会话 ID 查文件,数据库文件名与内部字段以安装版本为准。SQLite 状态目录设置
这两份存储可能暂时不同步:日志存在但索引尚未补齐,或索引仍然指向已经被移动的文件。参考实现包含扫描、补录、租约和进度记录等机制,用于协调这类恢复工作。
这里必须保留一个边界:能从日志重建部分索引,不代表整个数据库中的所有状态都能无损重建。记忆作业状态、调度信息或使用统计可能具有独立价值。备份与迁移应按实际组件设计,不能只复制一个数据库文件就假定历史齐全。
要定位一个普通本地会话,可以在终端设置从 /status 或 thread.started 事件取得的会话 ID,再列出文件和记录类型。以下只读操作针对传统本地 rollout 布局,已归档的会话先从归档列表确认。
1 | session_id='替换成实际的会话 UUID' |
没有找到文件时,先检查是不是用了另一个 CODEX_HOME、远程执行入口、归档会话或临时运行,再考虑索引问题。[history] 下的 persistence = "none" 控制 history.jsonl,自动化运行可用 codex exec --ephemeral 跳过会话 rollout 持久化。需要在中断后用 ID 续跑的任务,应选择普通持久化会话。历史设置 · CLI 的临时运行选项
四、用同一个会话恢复日期排序修复
沿用第二篇的练习仓库。在同一 checkout 里开一个普通 TUI 会话,用 /rename sort-dates-recovery 命名。等 Codex 修改完排序实现、尚未跑完整测试时停下,把 /status 中的会话 ID 记下来,再退出 TUI。回到原 checkout,先核对分支和差异,再按 ID 恢复。会话名可以用来找,ID 可以避免选到重名的任务。CLI 恢复与会话命名
1 | git status --short --branch |
恢复后的第一条消息可以写“先核对当前 diff 和 .task-notes/sort-dates.md,说清跑过的检查和还缺的检查,暂时只读”。验证时看它是否保留“禁止新增依赖”的要求,能否从工作树确认修改,并区分局部测试与全量测试。会话恢复重建的是聊天和执行历史,文件仍来自当前 checkout。换了 worktree 时,要另外找回实际改动。
自动化运行也可以按 ID 恢复。在第一篇的输出目录中,从 thread.started 取出 ID,回到同一 checkout 用 codex exec resume。如果第一次加了 --ephemeral,就应依靠任务交接文件和 Git 差异开启新会话。非交互事件和恢复方式
1 | session_id=$(jq -er 'select(.type == "thread.started") | .thread_id' "$run_dir/events.jsonl") |
恢复后如何处理未知结果
持久化最危险的窗口之一,是外部动作已经发生、完成记录尚未写入。
1 | 日志记录:准备发布 |
重启后如果根据“最后一条是调用请求”自动重试,就可能重复发布。恢复首先应重建已知状态,再核对实际产物。对于无法确认的操作,应保留未知结果;有幂等键或外部状态查询能力时,再据此决定后续动作。
会话 ID 也不等于磁盘进度。参考第 19 章说明了延迟创建日志文件的路径:逻辑会话已经建立时,持久化产物未必已经物化。即使执行了普通 flush,也不能不加区分地宣称获得了掉电后的完整耐久保证。
因此,对自己的 Harness,应分别定义“会话已创建”“记录已写入”“进度已满足恢复要求”的含义,避免前端拿到一个 ID 就显示所有进度已安全保存。
五、长期记忆的写入为什么分两阶段
下文的两阶段实现以这份上游管线文档为例。任务由根会话启动时触发调度,需要非临时会话、功能启用和状态数据库可用。进入调度后,还要经过候选筛选和后台处理。Memories 管线实现
第一阶段按会话抽取。系统选择符合来源、时间和空闲条件的 rollout,过滤内容,调用模型生成结构化结果,再存入状态库。结果包括较详细的 raw_memory、较简短的 rollout_summary 和可选标识。作业通过租约领取,失败后退避重试,避免多个进程重复处理同一份输入。
第二阶段做全局整合。系统选择一组有界的候选记忆,同步摘要与原始记忆材料,比较工作区变化;有变化时,再让专门的整合代理更新高层产物,例如 MEMORY.md 和 memory_summary.md。
1 | 合格 rollout |
这个拆分让局部抽取可以并行,而共享文件的整合由全局锁串行协调。它也把记忆生成成本从当前任务的主执行路径中分离出来,但后台处理仍会消耗资源,不能视为免费功能。
六、选择哪些记忆,与怎样排列材料是两回事
上游文档描述的候选选择考虑使用次数、最近使用时间和保留窗口。没有使用记录的新记忆会借助生成时间参与选择,避免它们还没被尝试就被排除。
选出候选后,合并原始记忆的排列又采用稳定的线程 ID 顺序。这样做能减少排名变化造成的文本抖动:选择策略决定谁进入集合,稳定排序决定如何展示集合。
这对基于 diff 的整合很实用。如果每次使用次数变化都打乱整份材料,整合代理看到的差异会包含大量无意义移动。
文档还明确区分了两种信号:数据库水位记录输入进度,工作区是否有实际变化则决定是否需要运行整合代理。不能仅看到水位变化,就推断必须重新生成全部记忆。
七、在新会话验证记忆的读写
参考第 20 章的读路径先提供一份受预算限制的记忆概要,其他详细材料保留为可检索文件,由代理按任务继续读取。
这与上一篇讨论的 Skill 渐进加载相似:概要负责定位,详细文件负责证据。新任务没有相关历史时,不应因为“已经有记忆”就全量读取。
本地 Codex 的记忆功能默认关闭。要练习跨会话复用,在个人 $CODEX_HOME/config.toml 合并下面的字段,再打开新会话。桌面端也可从 Settings → Personalization 启用 Codex memories。generate_memories 决定新会话能否作为提取输入,use_memories 决定以后是否注入已生成的记忆。只对当前聊天调整时,用 /memories 分别控制读取与生成。本地记忆开关和存储位置
1 | [features] |
可以这样做一组对照:
- 在普通本地会话里完成一次无敏感信息的日期排序排障,明确记录经验和适用条件,例如“跨时区样本按解析后的时间戳比较,同一时刻要保留输入顺序”。配置开启了
disable_on_external_context时,这次练习使用本地文件,避开 MCP、网页搜索和工具搜索。 - 等会话满足
memories.min_rollout_idle_hours的空闲条件,再开本地会话让后台处理有机会运行。检查$CODEX_HOME/memories/或$CODEX_HOME/memories_v2/是否生成了摘要和支撑材料。新旧客户端及迁移设置会影响目录,先以实际配置和产物为准。没有产物时检查空闲时间、来源和剩余额度门槛。 - 摘要确实包含该经验后,另开新会话询问该仓库的日期排序回归经验,先要求它报告记忆来源,再去读当前测试。用
codex -c memories.use_memories=false再开一个会话,发送同样的问题并比较来源。两次都可能从代码得到同样的答案,能否指出旧经验的记录才是这次对照要看的差异。记忆配置字段及默认值
长期记忆应当保留来源和适用范围。把“某次任务临时允许跳过检查”提炼成“这个项目可以跳过检查”,会将临时例外变成后续偏差的来源。
八、遗忘、纠正与权限边界
记忆系统不只需要新增,还需要删除和替代。过期配置、失败猜想、被用户纠正的习惯,都不应无限延续。
参考章节讨论了过滤注入片段、敏感内容处理与受限整合环境;上游文档也说明整合代理无网络、仅本地写入,并关闭递归协作。这些机制有助于限制影响,但秘密过滤不保证识别所有敏感信息,使用次数也不等于事实正确。
发现一条错误经验时,可以先把 use_memories 设为 false,让新会话停止注入现有记忆,同时把正确的团队规则写入 AGENTS.md 或测试。若还要停止把新会话交给后台提取,再把 generate_memories 设为 false。这两项分别管读入与生成,已有 rollout 和记忆文件需要按客户端提供的管理方式另行处理。摘要是派生文件,直接改其中一句可能在下一次整合时被旧材料覆盖。
对自己的系统,我会让每条经验尽可能回答:来自什么任务,在什么条件下成立,是否被后来的决定替代,以及怎样回到证据。这样新任务使用的是可核对的经验,而不是越来越难追溯的结论集合。
会话持久化让任务能够继续,压缩让当前历史保持可用,长期记忆让未来任务有机会复用经验。三条路径需要协作,也需要各自清楚地标记未知、失败和过期信息。