Conversation History Management

Relevant source files

• codex-rs/core/src/compact_remote_request.rs
• codex-rs/core/src/compact_remote_v2_attempt.rs
• codex-rs/core/src/context/token_budget_context.rs
• codex-rs/core/src/context/world_state/context_window_guidance.rs
• codex-rs/core/src/context/world_state/context_window_guidance_tests.rs
• codex-rs/core/src/context_manager/history.rs
• codex-rs/core/src/context_manager/history_tests.rs
• codex-rs/core/src/context_manager/mod.rs
• codex-rs/core/src/context_manager/normalize.rs
• codex-rs/core/src/session/rollout_reconstruction.rs
• codex-rs/core/src/session/rollout_reconstruction_tests.rs
• codex-rs/core/src/session/token_budget.rs
• codex-rs/core/src/state/auto_compact_window.rs
• codex-rs/core/src/state/session.rs
• codex-rs/core/tests/suite/catalog_permission_messages.rs
• codex-rs/core/tests/suite/resume_warning.rs
• codex-rs/core/tests/suite/snapshots/all__suite__token_budget__token_budget_new_context_window_tool_full_context.snap
• codex-rs/core/tests/suite/token_budget.rs
• codex-rs/rollout-trace/src/compaction.rs
• codex-rs/rollout-trace/src/thread_tests.rs

This document explains how Codex maintains and manipulates the conversation history that forms the model's context window. It covers the ContextManager data structure, item recording and normalization, token estimation, and history lifecycle management.

For details on summarizing and compacting conversation history when context limits are approached, see History Compaction System. For information on persisting history to disk and replaying it during session resumption, see Rollout Persistence and Replay.

---

Overview

The conversation history manager is responsible for:

• Storing ResponseItem entries (user messages, assistant messages, tool calls, tool outputs, reasoning items, and compaction summaries) codex-rs/core/src/context_manager/history.rs43
• Normalizing history to maintain invariants, such as ensuring every tool call has a corresponding output codex-rs/core/src/context_manager/normalize.rs20-130
• Tracking token usage from API responses and estimating tokens for locally-added items codex-rs/core/src/context_manager/history.rs46
• Managing the World State baseline to emit minimal diffs of environment and agent settings into the history codex-rs/core/src/context_manager/history.rs58-60
• Preparing history for prompt construction by filtering and transforming items codex-rs/core/src/context_manager/history.rs143-146

The primary entry point is the ContextManager struct, which is utilized by the SessionState to manage the transcript of a thread codex-rs/core/src/state/session.rs26-28

Sources: codex-rs/core/src/context_manager/history.rs40-60 codex-rs/core/src/context_manager/history.rs143-146 codex-rs/core/src/context_manager/normalize.rs20-130 codex-rs/core/src/state/session.rs26-28

---

ContextManager Structure

The ContextManager serves as the bridge between high-level session state and the low-level ResponseItem storage used for API communication.

ContextManager Fields

Field	Type	Purpose
items	Arc<Vec<ResponseItem>>	Ordered history from oldest to newest; uses Arc for efficient snapshots codex-rs/core/src/context_manager/history.rs43
history_version	u64	Incremented whenever history is rewritten (compaction/rollback) codex-rs/core/src/context_manager/history.rs45
token_info	Option<TokenUsageInfo>	Last API-reported token usage and context window state codex-rs/core/src/context_manager/history.rs46
world_state_baseline	Option<WorldStateSnapshot>	Most recent state appended to history for diffing codex-rs/core/src/context_manager/history.rs59

Sources: codex-rs/core/src/context_manager/history.rs40-60 codex-rs/core/src/context_manager/history.rs143-146

---

World State and Contextual Fragments

Codex uses a "World State" system to inject environment details (CWD, shell status, date) and agent instructions into the conversation history. The ContextManager handles the lifecycle of these snapshots.

1. Snapshotting: The system captures a WorldStateSnapshot of the current environment codex-rs/core/src/context_manager/history.rs95
2. Diffing: ContextManager::update_world_state compares the current snapshot against the world_state_baseline codex-rs/core/src/context_manager/history.rs97-98
3. Fragment Generation: It produces ContextualUserFragment items representing only what changed (e.g., a new CWD) codex-rs/core/src/context_manager/history.rs107
4. Rollout Tracking: It generates a WorldStateItem (Full or Patch) for persistence in the rollout file codex-rs/core/src/context_manager/history.rs98-105

Sources: codex-rs/core/src/context_manager/history.rs91-108 codex-rs/core/src/context_manager/history.rs59-60

---

Recording and Normalization

Items flow into the history manager through record_items, which accepts a TruncationPolicy codex-rs/core/src/context_manager/history.rs124-128

Item Normalization

Before history is sent to the model via for_prompt, normalize_history ensures structural integrity codex-rs/core/src/context_manager/history.rs143-146:

• Call/Output Pairing: Ensures every tool call has a corresponding output. The ensure_call_outputs_present function in normalize.rs inserts synthetic "aborted" outputs for missing ones to satisfy model requirements codex-rs/core/src/context_manager/normalize.rs20-130
• Orphan Removal: remove_orphan_outputs strips tool outputs that do not have a corresponding call in the surviving history (often after compaction) codex-rs/core/src/context_manager/normalize.rs147-174
• Modality Filtering: Unsupported image and audio content is stripped based on the model's input_modalities codex-rs/core/src/context_manager/history.rs141-143

Truncation

Tool outputs (like large file reads) are truncated based on the TruncationPolicy to prevent a single tool result from exhausting the entire context window codex-rs/core/src/context_manager/history.rs124-138

Sources: codex-rs/core/src/context_manager/history.rs124-146 codex-rs/core/src/context_manager/normalize.rs20-130 codex-rs/core/src/context_manager/normalize.rs147-174

---

Token Estimation and Budgets

Codex maintains context window usage tracking to trigger proactive management and warn the model.

• API Reported: When a model returns a response, it includes TokenUsage, which is updated in the session state and stored in token_info codex-rs/core/src/state/session.rs138-144 codex-rs/core/src/context_manager/history.rs75-77
• Heuristic Estimation: For items added locally (like tool outputs or user prompts) before the next API turn, estimate_token_count uses byte-based heuristics (via approx_token_count) to provide a lower bound codex-rs/core/src/context_manager/history.rs164-171
• Token Budget Context: Specific fragments like TokenBudgetRemainingContext and TokenBudgetReminder are injected into the "developer" role to inform the model of remaining capacity codex-rs/core/src/context/token_budget_context.rs103-171

Sources: codex-rs/core/src/context_manager/history.rs162-171 codex-rs/core/src/state/session.rs138-144 codex-rs/core/src/context/token_budget_context.rs103-171

---

History Lifecycle and Rollout Replay

History is not strictly additive. Approaches to context management include:

• Replacement: The replace method allows the Session to overwrite the entire history vector, typically used after a successful compaction codex-rs/core/src/state/session.rs114-123
• Rollout Reconstruction: When resuming a session, reconstruct_history_from_rollout scans the rollout file (newest-to-oldest) to rebuild the ContextManager state, including world_state_baseline and previous_turn_settings codex-rs/core/src/session/rollout_reconstruction.rs113-117
• Auto-Compaction Windows: The system tracks usage within an AutoCompactWindow to manage the transition between full context and summarized history codex-rs/core/src/state/session.rs158-188

For details on the summarization logic and triggers, see History Compaction System.

Sources: codex-rs/core/src/state/session.rs114-123 codex-rs/core/src/session/rollout_reconstruction.rs113-117 codex-rs/core/src/state/session.rs158-188