Codex 工程实践(四):会话持久化与长期记忆如何协作

一个 Agent 重启后还能接着聊,和它能在新任务里想起过去的经验,是两种能力。前者需要保存和重建会话状态,后者需要从历史中筛选值得复用的信息。

《Codex 源码分析》第 19、20 章恰好展示了这两条路径。它们共享历史材料,却有不同的读取方式、更新时机和正确性要求。把两者混在一起,很容易让系统既保存了大量日志,又无法稳定地继续工作。

一、四种容易被叫作“记忆”的东西

对象主要回答什么问题对应能力
会话轨迹这个任务已经发生了什么?恢复与审查
查询索引某个会话在哪里、有哪些元数据?列表、搜索与定位
压缩后的历史当前任务怎样在有限窗口内继续?上下文管理
长期记忆过去哪些经验对新任务仍有价值?跨会话复用

把日志全部保存,解决的是第一行的一部分。把历史压缩成摘要,解决的是第三行。两者都不能自动保证新任务会找到正确的旧经验。

二、会话保存为什么采用事件序列

参考第 19 章介绍的 rollout JSONL,一行对应一个结构化记录。记录可以携带会话元信息、模型输入输出项、回合上下文、压缩记录或运行事件。

这种形式适合追加,也方便逐条读取和处理。但不要因此理解成“所有内容都原样保存”。本次核对的上游持久化策略包含条目选择及输出裁剪逻辑;参考章节自身也讨论了事件过滤。因此,恢复得到的是实现定义的可恢复历史,不是每个内部状态的完整镜像。

可以用下面这个示意序列理解事件如何携带语义,字段和类型名称以实际版本为准:

1
2
3
4
5
6
7
会话元信息
用户提出任务
模型发起工具调用
工具返回结果
回合完成
历史压缩,记录替换历史
用户提出下一步任务

遇到历史压缩记录时,恢复器不能把全部旧内容和替换历史一起无脑拼接;它需要按记录的语义重建当前有效历史,否则已经压缩的内容会重新膨胀,甚至重复出现。

三、日志和索引分开,意味着要处理不一致

本地 CLI 自己生成 rollout,常规会话一般在 $CODEX_HOME/sessions/ 下按日期存放。SQLite 层由运行时维护,承担会话元数据查询及部分作业状态,sqlite_home 控制数据库目录。用户通常通过 codex resume 访问会话。需要排障时,先确认运行使用的 Codex home(默认 ~/.codex)和 sqlite_home,再按实际会话 ID 查文件,数据库文件名与内部字段以安装版本为准。SQLite 状态目录设置

这两份存储可能暂时不同步:日志存在但索引尚未补齐,或索引仍然指向已经被移动的文件。参考实现包含扫描、补录、租约和进度记录等机制,用于协调这类恢复工作。

这里必须保留一个边界:能从日志重建部分索引,不代表整个数据库中的所有状态都能无损重建。记忆作业状态、调度信息或使用统计可能具有独立价值。备份与迁移应按实际组件设计,不能只复制一个数据库文件就假定历史齐全。

要定位一个普通本地会话,可以在终端设置从 /status 或 thread.started 事件取得的会话 ID,再列出文件和记录类型。以下只读操作针对传统本地 rollout 布局,已归档的会话先从归档列表确认。

1
2
3
4
5
session_id='替换成实际的会话 UUID'
codex_dir="${CODEX_HOME:-$HOME/.codex}"
find "$codex_dir/sessions" -name "rollout-*-$session_id.jsonl" -print
# 用上一条返回的实际路径,查看记录类型而非输出对话正文。
jq -r '.type' /path/to/rollout.jsonl | sort | uniq -c

没有找到文件时,先检查是不是用了另一个 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
2
3
git status --short --branch
git diff -- src/sort-dates.mjs tests/sort-dates.test.mjs
codex resume "$session_id"

恢复后的第一条消息可以写“先核对当前 diff 和 .task-notes/sort-dates.md,说清跑过的检查和还缺的检查,暂时只读”。验证时看它是否保留“禁止新增依赖”的要求,能否从工作树确认修改,并区分局部测试与全量测试。会话恢复重建的是聊天和执行历史,文件仍来自当前 checkout。换了 worktree 时,要另外找回实际改动。

自动化运行也可以按 ID 恢复。在第一篇的输出目录中,从 thread.started 取出 ID,回到同一 checkout 用 codex exec resume。如果第一次加了 --ephemeral,就应依靠任务交接文件和 Git 差异开启新会话。非交互事件和恢复方式

1
2
3
4
5
session_id=$(jq -er 'select(.type == "thread.started") | .thread_id' "$run_dir/events.jsonl")
if [ -n "$session_id" ]; then
codex exec resume -c 'approval_policy="never"' -c 'sandbox_mode="read-only"' "$session_id" \
"先核对当前 diff 和已运行的检查,只报告待办。"
fi

恢复后如何处理未知结果

持久化最危险的窗口之一,是外部动作已经发生、完成记录尚未写入。

1
2
3
日志记录:准备发布
外部系统:发布成功
进程崩溃:尚未来得及保存完成结果

重启后如果根据“最后一条是调用请求”自动重试,就可能重复发布。恢复首先应重建已知状态,再核对实际产物。对于无法确认的操作,应保留未知结果;有幂等键或外部状态查询能力时,再据此决定后续动作。

会话 ID 也不等于磁盘进度。参考第 19 章说明了延迟创建日志文件的路径:逻辑会话已经建立时,持久化产物未必已经物化。即使执行了普通 flush,也不能不加区分地宣称获得了掉电后的完整耐久保证。

因此,对自己的 Harness,应分别定义“会话已创建”“记录已写入”“进度已满足恢复要求”的含义,避免前端拿到一个 ID 就显示所有进度已安全保存。

五、长期记忆的写入为什么分两阶段

下文的两阶段实现以这份上游管线文档为例。任务由根会话启动时触发调度,需要非临时会话、功能启用和状态数据库可用。进入调度后,还要经过候选筛选和后台处理。Memories 管线实现

第一阶段按会话抽取。系统选择符合来源、时间和空闲条件的 rollout,过滤内容,调用模型生成结构化结果,再存入状态库。结果包括较详细的 raw_memory、较简短的 rollout_summary 和可选标识。作业通过租约领取,失败后退避重试,避免多个进程重复处理同一份输入。

第二阶段做全局整合。系统选择一组有界的候选记忆,同步摘要与原始记忆材料,比较工作区变化;有变化时,再让专门的整合代理更新高层产物,例如 MEMORY.md 和 memory_summary.md。

1
2
3
4
5
6
合格 rollout
→ 按会话抽取
→ 状态库中的候选记忆
→ 选择、同步、比较变化
→ 全局整合
→ 可供以后任务读取的记忆产物

这个拆分让局部抽取可以并行,而共享文件的整合由全局锁串行协调。它也把记忆生成成本从当前任务的主执行路径中分离出来,但后台处理仍会消耗资源,不能视为免费功能。

六、选择哪些记忆,与怎样排列材料是两回事

上游文档描述的候选选择考虑使用次数、最近使用时间和保留窗口。没有使用记录的新记忆会借助生成时间参与选择,避免它们还没被尝试就被排除。

选出候选后,合并原始记忆的排列又采用稳定的线程 ID 顺序。这样做能减少排名变化造成的文本抖动:选择策略决定谁进入集合,稳定排序决定如何展示集合。

这对基于 diff 的整合很实用。如果每次使用次数变化都打乱整份材料,整合代理看到的差异会包含大量无意义移动。

文档还明确区分了两种信号:数据库水位记录输入进度,工作区是否有实际变化则决定是否需要运行整合代理。不能仅看到水位变化,就推断必须重新生成全部记忆。

七、在新会话验证记忆的读写

参考第 20 章的读路径先提供一份受预算限制的记忆概要,其他详细材料保留为可检索文件,由代理按任务继续读取。

这与上一篇讨论的 Skill 渐进加载相似:概要负责定位,详细文件负责证据。新任务没有相关历史时,不应因为“已经有记忆”就全量读取。

本地 Codex 的记忆功能默认关闭。要练习跨会话复用,在个人 $CODEX_HOME/config.toml 合并下面的字段,再打开新会话。桌面端也可从 Settings → Personalization 启用 Codex memories。generate_memories 决定新会话能否作为提取输入,use_memories 决定以后是否注入已生成的记忆。只对当前聊天调整时,用 /memories 分别控制读取与生成。本地记忆开关和存储位置

1
2
3
4
5
6
7
[features]
memories = true

[memories]
generate_memories = true
use_memories = true
disable_on_external_context = true

可以这样做一组对照:

  1. 在普通本地会话里完成一次无敏感信息的日期排序排障,明确记录经验和适用条件,例如“跨时区样本按解析后的时间戳比较,同一时刻要保留输入顺序”。配置开启了 disable_on_external_context 时,这次练习使用本地文件,避开 MCP、网页搜索和工具搜索。
  2. 等会话满足 memories.min_rollout_idle_hours 的空闲条件,再开本地会话让后台处理有机会运行。检查 $CODEX_HOME/memories/ 或 $CODEX_HOME/memories_v2/ 是否生成了摘要和支撑材料。新旧客户端及迁移设置会影响目录,先以实际配置和产物为准。没有产物时检查空闲时间、来源和剩余额度门槛。
  3. 摘要确实包含该经验后,另开新会话询问该仓库的日期排序回归经验,先要求它报告记忆来源,再去读当前测试。用 codex -c memories.use_memories=false 再开一个会话,发送同样的问题并比较来源。两次都可能从代码得到同样的答案,能否指出旧经验的记录才是这次对照要看的差异。记忆配置字段及默认值

长期记忆应当保留来源和适用范围。把“某次任务临时允许跳过检查”提炼成“这个项目可以跳过检查”,会将临时例外变成后续偏差的来源。

八、遗忘、纠正与权限边界

记忆系统不只需要新增,还需要删除和替代。过期配置、失败猜想、被用户纠正的习惯,都不应无限延续。

参考章节讨论了过滤注入片段、敏感内容处理与受限整合环境;上游文档也说明整合代理无网络、仅本地写入,并关闭递归协作。这些机制有助于限制影响,但秘密过滤不保证识别所有敏感信息,使用次数也不等于事实正确。

发现一条错误经验时,可以先把 use_memories 设为 false,让新会话停止注入现有记忆,同时把正确的团队规则写入 AGENTS.md 或测试。若还要停止把新会话交给后台提取,再把 generate_memories 设为 false。这两项分别管读入与生成,已有 rollout 和记忆文件需要按客户端提供的管理方式另行处理。摘要是派生文件,直接改其中一句可能在下一次整合时被旧材料覆盖。

对自己的系统,我会让每条经验尽可能回答:来自什么任务,在什么条件下成立,是否被后来的决定替代,以及怎样回到证据。这样新任务使用的是可核对的经验,而不是越来越难追溯的结论集合。

会话持久化让任务能够继续,压缩让当前历史保持可用,长期记忆让未来任务有机会复用经验。三条路径需要协作,也需要各自清楚地标记未知、失败和过期信息。

参考阅读

系列回顾:使用漂移 · 上下文压缩与拼接 · 工具、权限与沙箱。