codex 证据页

# `codex`

## 仓库定位

`codex` 里的 `context / memory` 相关实现主要分成三层：`core` 负责每个 turn 的可见上下文组装，`state` 负责 thread / memory 的 SQLite 持久状态，`core/memories` 负责 stage1 / phase2 memory 启动管线与文件系统同步。

## 源码架构树

```text

codex

├─ codex-rs/core/src/codex.rs

│ ├─ build_initial_context()

│ ├─ record_context_updates_and_set_reference_context_item()

│ └─ run_turn()

├─ codex-rs/core/src/context_manager/

│ ├─ history.rs

│ ├─ normalize.rs

│ └─ updates.rs

├─ codex-rs/core/src/memories/

│ ├─ start.rs

│ ├─ phase1.rs

│ ├─ phase2.rs

│ ├─ storage.rs

│ └─ prompts.rs

├─ codex-rs/state/src/runtime/

│ ├─ threads.rs

│ └─ memories.rs

└─ codex-rs/core/src/message_history.rs

```

## 关键结论摘要

- `ContextManager` 保存的不是原始聊天记录，而是一个会规范化、截断、回滚修剪的 turn 历史容器。

- turn 级 context 是“首次全量注入，之后按基线做增量更新”，基线由 `reference_context_item` 决定。

- `memory` 不是单一长期库，而是 startup 时跑起来的 phase1 / phase2 管线：先抽取 stage1 输出，再做全局 consolidation，并同步到 `codex_home/memories/`。

- `state` 与 `history` 是分层的：SQLite 负责 thread / job / stage1 outputs 等结构化状态，`history.jsonl` 则是全局 append-only 消息历史。

## 专题文档

- [01-架构与范围](./codex/01-%E6%9E%B6%E6%9E%84%E4%B8%8E%E8%8C%83%E5%9B%B4.md)

- [02-context管理](./codex/02-context%E7%AE%A1%E7%90%86.md)

- [03-memory实现](./codex/03-memory%E5%AE%9E%E7%8E%B0.md)

- [04-存储与状态](./codex/04-%E5%AD%98%E5%82%A8%E4%B8%8E%E7%8A%B6%E6%80%81.md)

- [05-调用链、压缩与边界](./codex/05-%E8%B0%83%E7%94%A8%E9%93%BE%E3%80%81%E5%8E%8B%E7%BC%A9%E4%B8%8E%E8%BE%B9%E7%95%8C.md)

## 关键源码索引

- `codex-rs/core/src/codex.rs:1654-2091`

- `codex-rs/core/src/codex.rs:3744-3991`

- `codex-rs/core/src/codex.rs:6146-6795`

- `codex-rs/core/src/context_manager/history.rs:34-452`

- `codex-rs/core/src/context_manager/updates.rs:14-224`

- `codex-rs/core/src/memories/mod.rs:3-120`

- `codex-rs/core/src/memories/phase1.rs:81-211`

- `codex-rs/core/src/memories/phase2.rs:41-160`

- `codex-rs/state/src/runtime.rs:91-216`

- `codex-rs/state/src/runtime/memories.rs:32-544`

## 阅读提示

先读 `02-context管理`，再读 `03-memory实现`。`codex` 最容易混淆的不是“有没有 memory”，而是 turn context、thread history、memory pipeline 和 SQLite state 其实是四个不同层次。

# `codex`：架构与范围

## 1. 三层主干

`codex` 的相关实现可以按三层理解：

- `core`：组装 turn 级可见 context，驱动采样、compact、memory startup。

- `state`：把 thread、memory jobs、stage1 outputs、spawn edges 等元数据落到 SQLite。

- `core/memories`：定义 phase1 / phase2 memory 管线，并把结果同步到文件系统 memory root。

### 源码锚点

- `codex-rs/core/src/codex.rs:3744-3991`

- `codex-rs/state/src/runtime.rs:91-216`

- `codex-rs/core/src/memories/mod.rs:3-120`

## 2. 范围边界

本组文档重点覆盖：

- `codex-rs/core`

- `codex-rs/state`

- `codex-rs/cli`

`sdk` 只有在改变 thread/context 语义时才会顺带说明，不把外围示例、项目说明、营销文档当成实现依据。

### 源码锚点

- `codex-rs/cli/src/main.rs:1252-1294`

- `codex-rs/cli/tests/debug_clear_memories.rs:1-135`

## 3. 关键边界

- `ContextManager` 不是“历史文件”，而是 turn 级历史容器。

- `history.jsonl` 不是 SQLite state。

- `memories/` 目录不是唯一真相，SQLite `stage1_outputs` 与 `jobs` 也保存 memory 生命周期。

- `memory tool` 的读路径只看 `memory_summary.md`，不会直接扫整个 `memories/` 目录。

### 源码锚点

- `codex-rs/core/src/context_manager/history.rs:34-120`

- `codex-rs/core/src/message_history.rs:48-100`

- `codex-rs/state/src/runtime/memories.rs:32-544`

- `codex-rs/core/src/memories/prompts.rs:233-249`

# `codex`：context 管理

## 1. `ContextManager` 是 turn 历史容器

`ContextManager` 保存 `ResponseItem` 历史、`reference_context_item` 基线和 token 信息。写入时只接受 API message 类 item，过滤掉非 API message 与 `GhostSnapshot`；用于 prompt 时再统一做 normalize，保证 tool call / output 成对，删除 orphan output，并在不支持图片的模型上剥离 image 内容。

### 源码锚点

- `codex-rs/core/src/context_manager/history.rs:34-120`

- `codex-rs/core/src/context_manager/history.rs:360-452`

- `codex-rs/core/src/context_manager/normalize.rs:14-197`

## 2. 全量与增量 context 的分界

turn 级 context 的关键分界是 `reference_context_item`：

- 没有基线时，`record_context_updates_and_set_reference_context_item()` 走 `build_initial_context()`，做全量注入。

- 有基线时，只走 `build_settings_update_items()`，发送环境、权限、协作模式、personality、model 指令等差异项。

### 源码锚点

- `codex-rs/core/src/codex.rs:3961-3991`

- `codex-rs/core/src/codex.rs:3744-3917`

- `codex-rs/core/src/context_manager/updates.rs:196-224`

## 3. `build_initial_context()` 注入什么

源码里明确列出了全量上下文的组成：

- 模型切换说明

- 权限说明

- session 级 developer instructions

- memory tool developer prompt

- collaboration mode

- realtime 说明

- personality

- apps / skills / plugins

- git commit trailer

- user instructions

- environment context

这套注入结构说明 `codex` 的 context 是可枚举的 runtime 产物，不是单个静态 system prompt。

### 源码锚点

- `codex-rs/core/src/codex.rs:3744-3917`

- `codex-rs/core/src/context_manager/updates.rs:14-224`

## 4. compact 与 window generation

历史被 compact 或 rollback 后，`ContextManager` 会被重写，必要时连 `reference_context_item` 一起清空。`ModelClient` 还维护 `window_generation`，并把 `conversation_id:window_generation` 作为 `x-codex-window-id` 发给模型侧。

这意味着 compact 不是单纯删消息，而是重建“上下文窗口的身份”。

### 源码锚点

- `codex-rs/core/src/codex.rs:3685-3709`

- `codex-rs/core/src/context_manager/history.rs:428-452`

- `codex-rs/core/src/client.rs:148-165`

- `codex-rs/core/src/client.rs:350-365`

## 5. realtime 启动上下文是另一条路径

`realtime_context.rs` 会从当前 thread 历史、最近 threads 和 workspace tree 生成 startup context，并明确排除 memory summaries 与 AGENTS 聚合内容。这条路径与普通 turn context 相关，但不等同。

### 源码锚点

- `codex-rs/core/src/realtime_context.rs:25-107`

# `codex`：memory 实现

## 1. memory 子系统是 phase1 / phase2 管线

`codex-rs/core/src/memories/mod.rs` 明确把 memory 拆成两阶段：

- `phase1`：从 rollout 里抽取 raw memory / rollout summary，写入 state DB。

- `phase2`：从 state DB 选择输入，做全局 consolidation，并同步到 `codex_home/memories/`。

### 源码锚点

- `codex-rs/core/src/memories/mod.rs:3-120`

- `codex-rs/core/src/memories/start.rs:14-39`

## 2. phase1：候选选择与抽取

phase1 的顺序是源码写死的：claim startup jobs -> build request context -> 并行 extraction -> 记录指标。输出 schema 包含 `rollout_summary`、`rollout_slug` 和 `raw_memory`，并会过滤掉某些不应进入 memory 的 contextual user fragment。

### 源码锚点

- `codex-rs/core/src/memories/phase1.rs:81-158`

- `codex-rs/core/src/memories/phase1.rs:196-211`

- `codex-rs/core/src/contextual_user_message.rs:50-58`

## 3. phase2：全局 consolidation 与文件同步

phase2 会 claim 全局 consolidation job，读取 `get_phase2_input_selection()` 的结果，更新 `rollout_summaries/` 与 `raw_memories.md`，再启动 `MemoryConsolidation` 子 agent 做 consolidation。

代码还明确禁止 consolidation 线程再递归回馈 phase1 或继续 delegate。

### 源码锚点

- `codex-rs/core/src/memories/phase2.rs:41-160`

- `codex-rs/core/src/memories/phase2.rs:287-298`

- `codex-rs/core/src/memories/storage.rs:23-42`

- `codex-rs/core/src/memories/storage.rs:98-171`

## 4. memory tool 的读取入口

`build_memory_tool_developer_instructions()` 只会读取 `codex_home/memories/memory_summary.md`，并截断到固定 token 上限。也就是说，memory tool 的读取入口不是整个 memory 目录，而是摘要文件。

### 源码锚点

- `codex-rs/core/src/memories/prompts.rs:233-249`

## 5. 另一条 memory 输入链：trace -> raw memory

`memory_trace.rs` 支持把 JSON array 或 JSONL trace 文件转成 `RawMemory` 输入，再调用 `summarize_memories()` 生成 `BuiltMemory`。这是独立于 startup 管线的 memory 输入路径。

### 源码锚点

- `codex-rs/core/src/memory_trace.rs:29-79`

- `codex-rs/core/src/memory_trace.rs:100-225`

- `codex-rs/core/src/client.rs:504-547`

# `codex`：存储与状态

## 1. 运行时目录

运行时状态至少分成三块：

- `CODEX_SQLITE_HOME` 下的 `state_5.sqlite`

- `CODEX_SQLITE_HOME` 下的 `logs_2.sqlite`

- `codex_home/history.jsonl`

- `codex_home/memories/`

### 源码锚点

- `codex-rs/state/src/lib.rs:20-61`

- `codex-rs/state/src/runtime.rs:91-216`

- `codex-rs/core/src/message_history.rs:48-100`

- `codex-rs/core/src/memories/storage.rs:12-42`

## 2. SQLite state 的重点表

源码和 migration 表明，和本任务最相关的结构包括：

- `threads`

- `stage1_outputs`

- `jobs`

- `thread_spawn_edges`

其中 `threads.memory_mode` 决定某个 thread 是否参与 memory 生成，`stage1_outputs` 保存 rollout 对应的 raw memory / summary，`jobs` 维护 memory stage1 / global consolidation 的租约和 watermark。

### 源码锚点

- `codex-rs/state/migrations/0001_threads.sql:1-18`

- `codex-rs/state/migrations/0006_memories.sql:1-22`

- `codex-rs/state/migrations/0016_memory_usage.sql:1-2`

- `codex-rs/state/migrations/0021_thread_spawn_edges.sql:1-8`

- `codex-rs/state/src/runtime/memories.rs:32-544`

## 3. `history.jsonl` 的角色

`message_history.rs` 维护的是全局 append-only 历史文件，带并发锁和尺寸控制。它和 SQLite state 是分开的：前者更像全局历史审计流，后者更像结构化 runtime 状态。

### 源码锚点

- `codex-rs/core/src/message_history.rs:48-100`

- `codex-rs/core/src/message_history.rs:169-276`

## 4. 清理与 fresh start

`debug clear-memories` 会同时清 state DB 里的 memory 数据并删除 `memories/` 目录。`reset_memory_data_for_fresh_start()` 则更进一步，会把已有 thread 的 `memory_mode='enabled'` 改成 `disabled`，避免旧 rollout 立刻重新进入 memory pipeline。

### 源码锚点

- `codex-rs/cli/src/main.rs:1252-1294`

- `codex-rs/cli/tests/debug_clear_memories.rs:1-135`

- `codex-rs/state/src/runtime/memories.rs:32-74`

# `codex`：调用链、压缩与边界

## 1. turn 级主调用链

主链路可以概括为：

`run_turn()` -> `record_context_updates_and_set_reference_context_item()` -> `clone_history().for_prompt()` -> 模型采样。

其中 `clone_history().for_prompt()` 才是实际送给模型的 prompt 历史。

### 源码锚点

- `codex-rs/core/src/codex.rs:6146-6795`

- `codex-rs/core/src/codex.rs:3961-3991`

- `codex-rs/core/src/context_manager/history.rs:360-452`

## 2. compact 如何改写历史

当模型切换导致窗口变化，或历史超窗时，compact 会重建压缩历史，并重新注入 initial context。`replace_compacted_history()` 后，`window_generation` 会推进，后续 turn 会基于新的上下文窗口身份继续。

### 源码锚点

- `codex-rs/core/src/compact.rs:45-291`

- `codex-rs/core/src/compact_remote.rs:34-203`

- `codex-rs/core/src/codex.rs:3685-3709`

- `codex-rs/core/src/client.rs:338-365`

## 3. memory startup 的调用链

memory startup 的主链路是：

`start_memories_startup_task()` -> `phase1::run()` -> `phase2::run()` -> 文件系统同步 / consolidation agent。

它只会在非 ephemeral、启用 MemoryTool、且不是 subagent 的 root session 上启动。

### 源码锚点

- `codex-rs/core/src/memories/start.rs:14-39`

- `codex-rs/core/src/memories/phase1.rs:81-136`

- `codex-rs/core/src/memories/phase2.rs:41-160`

## 4. 关键边界

- turn context 不等于 memory pipeline。

- SQLite state 不等于 `history.jsonl`。

- `memory_summary.md` 是 memory tool 读入口，不等于完整 memory root。

- realtime startup context 与普通 turn context 相关，但不是同一条构造路径。

### 源码锚点

- `codex-rs/core/src/context_manager/updates.rs:196-224`

- `codex-rs/state/src/runtime/memories.rs:370-544`

- `codex-rs/core/src/memories/prompts.rs:233-249`

- `codex-rs/core/src/realtime_context.rs:25-107`