Codex compaction is not one summary call. The model writes a handoff summary. The harness runs pre- and post-compaction hooks, keeps recent user messages inside a token budget, rebuilds the runtime instructions, drops old history when the request still overflows, and recounts tokens. The useful question is whether the next model still knows the goal, the constraints, the progress, the evidence, and the next action. Prose quality is secondary. Other Codex branches use token-budget or remote encrypted compaction.
I assumed compaction was simple: the chat hit a limit, the model summarized it, and work continued. The prompt is indeed short. The harness around it is where the mechanism lives.
What is Codex actually doing?
It replaces the active message history with a smaller working set. The model gets the current history plus a compaction prompt and writes a summary. The harness adds a handoff prefix, keeps some recent user messages, reattaches the runtime instructions, and swaps the old history for the new one. Old messages leave the model's active view. They are not necessarily deleted from local logs.
Compaction does not enlarge the context window or train the model. It buys room for the next step.
Why does the window fill up so fast?
Most of the window is work residue: search results, test output, stack traces, and files the agent read once and may need again. The chat is the thin layer on top. That is why "summarize the conversation" misses the problem.
What does the default prompt ask for?
Codex keeps a default prompt at codex-rs/prompts/templates/compact/prompt.md:
You are performing a CONTEXT CHECKPOINT COMPACTION. Create a handoff summary for another LLM that will resume the task.
Include:
- Current progress and key decisions made
- Important context, constraints, or user preferences
- What remains to be done (clear next steps)
- Any critical data, examples, or references needed to continue
Be concise, structured, and focused on helping the next LLM seamlessly continue the work.The key word is handoff. A chat summary says what was discussed. A handoff says where the task stands and where the next model starts. "We discussed email classification and changed some code" is a weak summary. A useful one says the classifier is wired in, unit tests pass, the mailbox integration test has not run, sending is not authorized, and the next step is a read-only integration test.
The prompt sets a direction. It does not guarantee that every run keeps all of it.
What does the harness add?
Copying the prompt does not reproduce Codex compaction. In the public text path, the client does several jobs around the model call.
| Stage | What the program does |
|---|---|
| Before compaction | Runs the PreCompact hook and decides whether to continue |
| Build the request | Copies the current history, appends the prompt, and adds relevant tool records |
| Generate the summary | Asks the model for the handoff |
| Handle errors | Retries some failures; if the request still overflows, removes the oldest history items |
| Assemble new history | Adds the handoff prefix and keeps recent user messages within a budget |
| Restore runtime context | Reassembles the base context and replaces the active history |
| Finish | Records metadata, recounts tokens, runs the post-compaction hook, and emits a completion event |
The model decides what is worth saying. The program decides what remains, how the next request is assembled, and what happens on failure. Which messages survive is program logic, not a model output.
What survives the handoff?
The harness also adds a fixed prefix before the summary, from codex-rs/prompts/templates/compact/summary_prefix.md:
Another language model started to solve this problem and produced a summary of its thinking process. You also have access to the state of the tools that were used by that language model. Use this to build on the work that has already been done and avoid duplicating work. Here is the summary produced by the other language model, use the information in this summary to assist with your own analysis:
"Another language model" is a handoff phrase. It does not prove the model ID changed. "Access to the state of the tools" does not prove every external process is still alive.
| Before compaction | After compaction |
|---|---|
| Runtime instructions and environment information | Rebuilt by the harness |
| User messages | Recent ones kept within a budget |
| Assistant replies, tool calls, and exploration | Key information carried by the prefix and summary |
Ask "where are we?" and the summary can answer. Ask "what does this function look like now?" and the agent should re-read the file. Replacing active context does not roll back files on disk.
Does a real case keep its direction?
One long HereToo conversation changed direction several times: from an app to hardware, from bedtime-only back to everyday action problems, then to a help mode inside HereToo. A summary that only remembered the early wording would send the next model back to a bedside device. The useful summary recorded which framing was rejected and why. It also kept the state that changes the next action: the learning plan exists, implementation has not started, competitor notes came from public material, and the code still needs a fresh look.
There is one caveat. Finding a decision in the summary does not prove the agent will never forget it. The source checked visible summary content, not a full regression test across the boundary.
Is text summarization the only path?
No. The public source has TokenBudget and remote Compaction V2 branches. OpenAI's native endpoint returns compacted items, including encrypted items that carry prior state in fewer tokens.
- Encrypted does not mean lossless.
- Unreadable does not mean we know the encoding.
- The open-source prompt is not the server's internal prompt.
So "Codex compaction is summarization" explains one path, not the system.
What should you copy in your own agent?
Ask which detail, if lost, would make the next action wrong. These pairs matter more than prose quality:
- Ready to edit, or already edited?
- Edited, or tested?
- Unit tests pass, or production verified?
- Allowed to prepare, or allowed to execute?
- An option still valid, or already rejected?
A few words separate these states. Record "plan to migrate" as "migration completed" and the next turn may skip the work. Keep active context, compaction, task state, and long-term memory separate. A state file is only useful if the next context can open it.
Do not judge by compression ratio alone. Watch missed constraints, repeated work, false completion claims, and extra reads after a resume. Only compute a ratio if you have consistent token counts on both sides.
The prompt is short. Most of the engineering sits in the handoff: what the next context can assume, and what it must check again.
Long agent sessions also have a model bill attached. If you want a predictable coding plan for that work, the Kimi guide on our site has the details.