# AGENTS.md too large: what Codex cuts off and how to split it

> Source: https://minniai.com/learn/agents-md-too-large (canonical HTML page)

[Guides](https://minniai.com/learn)


Codex reads AGENTS.md files up to a combined size, project_doc_max_bytes, which is 32 KiB by default. It adds files from the repo root down to your working directory and stops once the chain reaches the cap. The files nearest your working folder are added last, so they are the ones at risk. The fix is a shorter chain: cut what the agent can read from the code, nest files per folder, and move task-specific notes into files it opens only when needed.

Updated 2026-11-11

## How Codex builds the chain

Codex builds its instructions once when a session starts. [OpenAI’s AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md) describes the order:

- **Your user file.** In your Codex home folder, Codex reads `AGENTS.override.md` if it exists, otherwise `AGENTS.md`. Only the first file that is not empty is used.
- **The project files.** Starting at the project root, usually the Git root, Codex walks down to your current working directory. In each folder it looks for `AGENTS.override.md`, then `AGENTS.md`, and takes at most one file.
- **The join.** The files are joined from the root down. A file closer to your working directory comes later in the text, so its rules take precedence.

Nothing in this chain loads on demand. Whatever makes it in is sent with each request for the rest of the session.

## The cap, and what gets left out

Codex stops adding files once the combined size reaches `project_doc_max_bytes`, 32 KiB by default. Because the walk goes from the root down, a large file at the root can use the whole budget before Codex reaches the folder you are working in. The rules you wrote for that folder are then the ones the agent never sees.

An override file can hide instructions too. An `AGENTS.override.md` in a folder replaces that folder’s `AGENTS.md` completely. If someone left one behind, the regular file next to it is not read.

## How to see what loads

- **Check the sizes.** Add up the bytes of your user file and each AGENTS.md from the repo root to the folder you start Codex in. If the total is near the cap, you are at risk.
- **Ask the agent.** In a new session, ask Codex to list the instruction files it was given. A rule that should be there and is not points to the cap or an override.
- **Use a map.** `minnimemory init` prints the chain for the folder you run it in: each file, its size, whether it loads, and the cap in force. `doctor` flags a file past the cap and an override file hiding an `AGENTS.md`.

## Five ways to get back under the cap

### 1. Cut what the agent can find itself

Folder layouts, lists of dependencies and descriptions of what each file does can be read from the repo. Keep what the code cannot tell the agent: the commands to run, the rules that are not obvious, the things it must never do.

### 2. Nest files per folder

Put the rules for one service or package in an AGENTS.md inside that folder. A session started elsewhere does not load it. OpenAI suggests this for larger projects.

### 3. Move task-specific notes out

A release checklist or a database migration guide is needed on a few turns, not all of them. Put each in its own file and leave one line in AGENTS.md that says when to open it. The agent reads it when the task calls for it.

### 4. Raise the cap

You can set a larger `project_doc_max_bytes` in your Codex config. It stops the cut, but it does not make the chain cheaper: every byte is still sent with each request.

~/.codex/config.toml

```
project_doc_max_bytes = 65536
```

### 5. Split it with a tool

[MinniMemoryMCP](https://minniai.com/minnimemorymcp) does fixes 1 to 3 for a chain that is over the cap. It sorts each file into a small part that stays in AGENTS.md and files Codex opens only when a task needs them. Every line is kept, the originals are backed up first, and one `undo` puts the whole chain back.

install it for Codex

```
$ npm i -g minnimemory
$ minnimemory install --host codex
```

Then run `/hooks` once in Codex to trust its two hooks, and ask Codex to run `init`. A file Codex already loads whole is left as it is, because in our tests splitting a small file cost recall.

## Related

A long chain also costs tokens on every turn, cap or no cap: see [How to reduce Codex token usage](https://minniai.com/learn/reduce-codex-token-usage) and [Codex usage limits](https://minniai.com/learn/codex-usage-limits). For the Claude Code side of the same problem, see [Claude Code memory: CLAUDE.md vs MinniMemoryMCP](https://minniai.com/learn/claude-code-memory-claude-md-vs-minnimemorymcp).

Try MinniMemoryMCP

Free, runs on your computer, and every change can be undone. It maps the AGENTS.md chain Codex loads and trims it when it is over the cap. The [product page](https://minniai.com/minnimemorymcp) and the [docs](https://minniai.com/minnimemorymcp/docs#install-codex) cover the rest.

install it for Codex

```
$ npm i -g minnimemory
$ minnimemory install --host codex
```

## More guides

- [How to reduce Claude Code token usage](https://minniai.com/learn/reduce-claude-code-token-usage) Where the tokens go each turn, and eight ways to spend fewer.

Updated 2026-11-16 · Minni AI

- [Claude Code usage limit reached: what to do, and how to hit it less](https://minniai.com/learn/claude-code-usage-limit-reached) What each limit message means, what to do now, and how to send less every turn.

Updated 2026-11-16 · Minni AI

- [CLAUDE.md too long: what Claude Code does with it, and how to split it](https://minniai.com/learn/claude-md-too-long) What a long CLAUDE.md costs, the real size limits, and four ways to cut it.

Updated 2026-11-16 · Minni AI

- [Claude Code context window keeps filling up: why it compacts, and what to do](https://minniai.com/learn/claude-code-context-window-full) What fills the window, what compaction keeps, and how to compact less often.

Updated 2026-11-16 · Minni AI

- [How to reduce Codex token usage](https://minniai.com/learn/reduce-codex-token-usage) Where Codex spends tokens, and seven ways to spend fewer.

Updated 2026-11-16 · Minni AI

- [Codex usage limits: why they drain and how to use fewer tokens](https://minniai.com/learn/codex-usage-limits) How the windows work, how to check what is left, and what uses the allowance up.

Updated 2026-11-11 · Minni AI

- [How to lower a Claude Code or Codex API bill](https://minniai.com/learn/lower-claude-code-codex-api-bill) What a coding agent bills on an API key, and the levers that move it.

Updated 2026-11-16 · Minni AI

- [Why Claude Code sessions get expensive](https://minniai.com/learn/why-claude-code-sessions-get-expensive) Every turn re-sends the whole session. What makes that grow.

Updated 2026-11-05 · Minni AI

- [Claude Code memory: CLAUDE.md vs MinniMemoryMCP](https://minniai.com/learn/claude-code-memory-claude-md-vs-minnimemorymcp) What belongs in CLAUDE.md, and splitting the rest out by hand or with a tool.

Updated 2026-11-16 · Minni AI

- [MinniMemoryMCP vs Mem0, Zep, supermemory and Letta](https://minniai.com/learn/minnimemorymcp-vs-mem0-zep-supermemory-letta) Four tools add memory to an agent. MinniMemoryMCP cuts what the agent already loads. When each fits.

Updated 2026-11-16 · Minni AI

- [How Claude Code remembers across sessions](https://minniai.com/learn/claude-code-memory-across-sessions) What carries over between sessions, what does not, and how to keep it small.

Updated 2026-11-16 · Minni AI

- [Where Claude Code keeps its memory](https://minniai.com/learn/claude-code-memory-directory) Every memory path on your machine, what each file is for, and which ones load every turn.

Updated 2026-11-07 · Minni AI

- [How to run a coding agent on free, open models](https://minniai.com/learn/run-a-coding-agent-on-free-open-models) What a free key gets you, what a local model can do, and where the tokens go.

Updated 2026-10-25 · Minni AI

- [Get a free NVIDIA API key for a coding agent](https://minniai.com/learn/free-nvidia-api-key-for-a-coding-agent) Where the key comes from, where to keep it, and how to run a coding agent on it.

Updated 2026-11-07 · Minni AI

- [What a Windows PC optimization agent should and should not touch](https://minniai.com/learn/what-a-pc-optimization-agent-should-touch) The settings worth changing, the ones that are placebo, and the ones that break things.

Updated 2026-10-25 · Minni AI

---

Index for agents: https://minniai.com/llms.txt. Doing a task: https://minniai.com/agents.md
