Why does Codex forget what it was doing after compaction?

Codex replaces earlier turns with a summary and continues from it once the context reaches model_auto_compact_token_limit, and when that setting is unset the threshold follows the model's default (Codex configuration reference). /status shows the session's configuration and token usage, and /compact summarizes the visible chat by hand to free tokens (Codex CLI commands).

The summary is written by a prompt you can replace, inline with compact_prompt or from a file with experimental_compact_prompt_file (marked experimental). Both override the built-in prompt, so write a whole prompt and test it on a throwaway session first.

# ~/.codex/config.toml
# The token count at which Codex compacts (an example value, pick your own)
model_auto_compact_token_limit = 150000

# Optional: your own summary prompt, kept in a file
experimental_compact_prompt_file = "/path/to/compact_prompt.md"

What gets lost is whatever the summary leaves out. One report, opened on 30 October 2025, is still open, and later reports were closed as duplicates of it. In it, Codex had been editing files for over an hour when an automatic compaction left the edits out of the summary. It stopped in the middle of the task, and when asked, it said it had not edited any files (#5957). A report from 28 September 2026, open as of 23 October 2026, describes Codex losing the active Goal after automatic compaction and going back to a problem it had already solved (#49022). Another, from June 2026, reports project rules and task state lost after compaction in long tasks, with reported progress falling from about 97% to 42% and nearly finished work opened again (#25792).

Keep the state of the task in a file in the repository, where compaction cannot touch it, and make Codex read that file again after every compaction. These steps use only Codex's own features:

1. Keep a plan file. OpenAI's cookbook describes ExecPlans, design documents written to the rules in a PLANS.md file, each with a progress list of checkboxes and written so that it is always possible to restart from the plan alone (OpenAI Cookbook). A shorter PLAN.md with the goal, one checkbox per step and the files changed does the same job for a single task.
2. Tell Codex in AGENTS.md to read the plan before each step and tick it after each one. Codex builds its instructions from the AGENTS.md chain at the start of each run (AGENTS.md docs). Rules can be lost in a compaction too (#25792), so the hook in the next step is the part that puts the plan back.
3. Add a SessionStart hook with the matcher compact that prints the plan. The docs say such a hook runs after a session is compacted and before the next model request. They also say plain text it prints is added to the model's context, up to roughly 2,500 tokens by default. Past that the model gets a head-and-tail preview and the path of a file holding the full text, so keep PLAN.md short (Codex hooks). The setting that raises that cap, additionalContextLimit, applies only to additionalContext according to the docs, and they do not say whether plain-text output counts as that. Project hooks load only when the project's .codex/ folder is trusted, and a new or changed hook runs only after you review and trust it in /hooks.
4. Test the hook once with /compact, then check that the next reply knows the plan. Until the report was closed as completed on 20 July 2026, a compact hook fired by an automatic compaction in the middle of a turn was delivered only on a later turn, so the agent kept working without the restored plan (#28736). The hooks docs now say the context reaches the immediate continuation, and a build from before the fix may still behave the old way.
5. If Codex already lost the thread, tell it what it did. Point it at the plan file, and at git diff and git log for edits it says it never made, as in #5957.
6. Compact at a point you choose. Update the plan, then run /compact between phases, so the summary happens after a finished step instead of in the middle of one.
7. Start a new phase clean. /new starts a new chat inside the same CLI session (Codex CLI commands), and the first prompt can be to read the plan and continue.

## Plans
For any task longer than one step, keep the plan in PLAN.md at the repository root:
the goal, one checkbox per step, and the files you changed.
Read PLAN.md before starting a step. Tick the box and list the files when the step is done.
After a compaction, read PLAN.md before doing anything else.

# <repo>/.codex/config.toml
[[hooks.SessionStart]]
matcher = "^compact$"

[[hooks.SessionStart.hooks]]
type = "command"
command = 'cat "$(git rev-parse --show-toplevel)/PLAN.md"'

A rule Codex ignores may never have loaded. Codex stops reading project instructions at a size limit, so a rule past it is missing from the first turn, before any compaction, and the loss is easy to blame on compaction.

Codex reads at most project_doc_max_bytes of project instructions, 32 KiB by default, and stops adding files once the combined size reaches it (AGENTS.md docs). It reads one global file from ~/.codex (AGENTS.override.md if it exists, otherwise AGENTS.md), then at most one file per directory from the project root down to where you started it, joined in that order, so files closer to your working directory come later and override earlier ones.

The cut gives no visible warning. A request for one was closed as not planned on 2 March 2026 (#7138), and the open follow-up reports that instructions past the limit never reach the model, with no warning in the terminal UI, codex exec or the VS Code extension (#13386). A commenter there traced the limit in the source to one budget shared by the whole chain and spent from the root down, so a long root file can crowd out a nested one.

1. Measure the chain. Add up the bytes of the one file Codex reads in each directory between the project root and the directory you work in, which is AGENTS.override.md where it exists and AGENTS.md otherwise.
2. Raise the limit if you need the length, with project_doc_max_bytes in ~/.codex/config.toml. The source comment quoted in #7138 says the limit is there so instructions do not take up too much of the context window, so a longer file leaves less room for the task.
3. Or split it. Move rules that only matter in one part of the repository into an AGENTS.md in that directory, where Codex reads it only when it starts there or below. A run started there still counts that file in the same 32 KiB budget as the files above it, so splitting shortens the chain only for runs started elsewhere, and raising the limit is the fix for a deep chain.
4. Check what loaded. The docs suggest codex --ask-for-approval never "Summarize the current instructions.", and for nested files the same with --cd subdir and the prompt "Show which instruction files are active." If the summary leaves out your last rules, check the chain's size against the limit.
5. Start a new run after editing. Codex builds the instruction chain once per run, which in the terminal UI usually means once per launched session, and the docs say to restart Codex in the target directory if instructions look stale.

# ~/.codex/config.toml
project_doc_max_bytes = 65536   # 64 KiB, an example value

Codex Memories carry context from earlier chats into later work. They are built only after a chat has gone idle, so they do not bring back what a compaction dropped in the session you are in. They are off by default. Turn them on with memories = true under [features] in config.toml, or under Settings, Personalization in the ChatGPT desktop app, and use /memories to control them for one chat (Codex Memories).

The idle wait is 6 hours by default (memories.min_rollout_idle_hours, configuration reference), and the files are kept in a memories folder under ~/.codex. The docs ask you to keep required guidance in AGENTS.md or checked-in docs and to treat memories as a recall layer, not the only source for rules that must always apply (Codex Memories). Other kinds of agent memory are compared in which kind of memory a coding agent should use.