codex 学习页

codex 把 context、memory、state/history 拆成不同职责层：每个 turn 负责组装可见上下文，memory 走启动期两阶段管线，SQLite 和文件系统分别承担结构化持久化与同步。

要读懂 codex，关键不是看“有没有 memory”，而是先分清 turn context、thread history、memory pipeline 和 SQLite state 这四层。

源码事实终端型 Agent Runtime

回横向对照打开证据页

这页怎么读

先看“这一轮模型看到了什么”，建立模型视角。
再看 context 和 memory 两张图，抓主链。
最后看源码锚点和证据页，确认细节。

这一轮模型到底看到了什么

这一段只讲模型真正可见的材料，不把所有底层状态都算进 context。

context 组成图

codex 的上下文不是一次性拼好的，而是围绕 reference_context_item 做“首次全量、之后增量”。

run_turn()

每一轮从这里开始。

reference_context_item

决定本轮是全量还是增量。

ContextManager normalize

修正 turn 历史和 tool 对齐。

build_initial_context()

首次注入环境、权限、指令和人格。

clone_history().for_prompt()

生成最终 prompt 历史。

model sampling

用 window id 维持窗口身份。

模型拿到的是经过 ContextManager 规范化后的 turn 历史，不是原始聊天记录。
首次 turn 通常是全量注入；后续 turn 主要基于 reference_context_item 做增量更新。
build_initial_context() 会把模型切换、权限、developer instructions、memory prompt、协作模式、人格、应用/技能、用户指令和环境等一起注入。
clone_history().for_prompt() 才是最终送进模型的 prompt 历史。
compact 或 rollback 之后，模型看到的是重建后的窗口身份，而不是简单删减后的旧历史。
realtime 启动时会走另一条 startup context 路径，并排除 memory summaries 和 AGENTS 聚合内容。
memory tool 只读 memory_summary.md，不会直接扫完整 memories/ 目录。

context 是怎么拼起来的

先看组成块，再看顺序。这里最容易帮助普通读者分清“哪些东西会真的进模型”。

turn 上下文管理

ContextManager 负责规范化、截断、回卷和补齐 turn 历史。

runtime

全量与增量上下文

reference_context_item 决定首次全量注入还是后续只注入 settings diff。

strategy

初始上下文构成

build_initial_context() 把环境、权限、指令、人格、插件与协作模式一次性拼装进上下文。

composition

memory 启动管线

memory 不是单一数据库，而是 phase1 / phase2 的启动期流水线。

pipeline

压缩与实时启动

compact 重建窗口身份，realtime_context 走独立 startup context 路径。

boundary

持久化分层

SQLite、history.jsonl 和 memories/ 分别承担结构化状态、全局历史和记忆产物。

storage

run_turn() 启动一次 turn。
record_context_updates_and_set_reference_context_item() 记录上下文更新，并决定这次是全量还是增量。
ContextManager 先做 normalize，过滤非 API item，补齐 tool call/output，去掉 orphan output 和不支持模型中的 image 内容。
clone_history().for_prompt() 生成真正要送进模型的历史上下文。
模型采样时，window_generation 和 x-codex-window-id 维持窗口身份。
如果触发 compact 或 rollback，就重写 history 并重新注入 initial context。
realtime 场景会改走 realtime_context，按独立路径组装 startup context。

memory 是怎么形成、保存、再被取回的

不要把记忆想成一个抽象黑盒。这里直接按时间顺序讲“它什么时候生成、存哪、怎么再回来”。

memory 流程时间线

memory 更像启动期后台流水线：先抽，再合，再同步，而不是每轮都直接写一个统一数据库。

startup task

只有满足条件才会启动。

phase1 claim & extract

先抢任务，再做抽取。

stage1_outputs

中间结果先落到 state DB。

phase2 consolidation

再做全局 consolidation。

MemoryConsolidation agent

统一整理长期记忆。

memories/ + summary

最后同步到文件系统和摘要入口。

仅在 ephemeral、启用 MemoryTool、且不是 subagent root session 时启动 memory startup。
start_memories_startup_task() 拉起整个记忆管线。
phase1 先 claim startup jobs，再 build request context，并行做 extraction。
phase1 把 rollout_summary、rollout_slug、raw_memory 等结果写入 state DB 的 stage1_outputs。
phase2 再 claim global consolidation job，读取筛选后的输入，启动 MemoryConsolidation agent 做全局 consolidation。
phase2 将结果同步到 codex_home/memories/，并更新 raw_memories.md / summaries。
发生 fresh start 时，会清 state DB 和记忆目录，并可把已有 thread 的 memory_mode 关掉。

存储分层图

很多误解都来自把 transcript、summary、文件、数据库和向量库混成一层看。

存储分层图

state、logs、history 和 memories 分层得很清楚，不能混成一个“数据库”。

logs_2.sqlite

日志层。

state_5.sqlite

线程、作业、stage1_outputs、spawn edges 等结构化运行态。

history.jsonl

全局 append-only 历史流。

codex_home/memories/

长期记忆文件同步层。

memory_summary.md

memory tool 的读取入口。

CODEX_SQLITE_HOME/state_5.sqlite：结构化运行态，重点是 threads、stage1_outputs、jobs、thread_spawn_edges 和 memory_mode。
CODEX_SQLITE_HOME/logs_2.sqlite：日志层，和结构化 state 分开。
codex_home/history.jsonl：全局 append-only 历史文件，更像审计流，不等于 state。
codex_home/memories/：记忆产物落盘与同步的文件系统层。
codex_home/memories/memory_summary.md：memory tool 的读取入口，是摘要层，不是全量 memory root。
stage1_outputs / jobs：记忆生命周期里的中间状态层，承载抽取结果、租约和 watermark。