# CLAUDE.md too long: what Claude Code does with it, and how to split it

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

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


Claude Code loads the whole of your CLAUDE.md at the start of every session, however long it is, and keeps it in context for every turn. Anthropic suggests staying under 200 lines per file, because a longer file uses more context and is followed less closely. Splitting it with @path imports does not help, since imported files load with it. What helps is moving the parts that are not needed on every turn into files that load only when a task calls for them.

Updated 2026-11-16

## What Claude Code does with a long file

There is no cut-off that saves you. [Anthropic’s memory docs](https://code.claude.com/docs/en/memory) say Claude gets the whole of each CLAUDE.md that loads at launch, as long as the file is 4 MiB or smaller. So a file several times the suggested length is still loaded in full, sent with every request, and paid for on every turn.

The cost is not only tokens. The docs say longer files reduce adherence: the more rules the agent carries, the less reliably it follows each one. And if two instructions contradict each other, Claude may pick one arbitrarily.

Claude Code tells you when you are over. If an instruction file is past the recommended length, you see a warning at startup and when you run `/status`. You also see one when files that are each fine add up past a combined limit.

## The size limits, in one table

| File | What loads | When |
| --- | --- | --- |
| CLAUDE.md at the project root or above, and your user CLAUDE.md | All of it, up to 4 MiB. A file over 4 MiB is skipped. | Every session, at launch |
| Files it imports with `@path` | All of each file, up to four hops deep | Every session, with the file that imports them |
| A CLAUDE.md in a subfolder | Only its start if it is over 40,000 characters on a 200K context window | When Claude reads or edits a file in that folder |
| A path-scoped rule in `.claude/rules/` | The same per-file limit as a subfolder file | When Claude works with a matching file |
| Auto memory `MEMORY.md` | The first 200 lines or 25KB, whichever comes first | Every session, at launch |

Two things follow from this. The root file is the expensive one, because it always loads in full. And imports only organize: an imported file is loaded together with the file that imports it, so moving text into an import saves nothing.

## See what is loading

- Run `/context all` and look under **Memory files**. It lists the CLAUDE.md files that loaded at launch and what each costs.
- Run `/memory` to see every memory file location and open any of them.
- Run `/usage` on a subscription plan. Its recommendations name a CLAUDE.md that is costing you on every request.
- Run `/doctor`. It proposes trims for a checked-in CLAUDE.md: it cuts what Claude can work out from the code and keeps the pitfalls and the rules.

## Four ways to make it shorter

### 1. Cut what the code already says

Folder layouts, dependency lists and architecture overviews can be read from the repo. Keep what the code cannot tell the agent: the build and test commands, the conventions that differ from the defaults, and the mistakes it must not repeat.

### 2. Move folder-specific rules into path-scoped rules

A rule file in `.claude/rules/` with a `paths:` line loads only when Claude works with a matching file. Rules for the API layer stop loading while you work on the front end.

### 3. Move procedures into skills

A release checklist or a migration walkthrough is a multi-step procedure, needed on a few turns. A skill loads its body only when it is used.

### 4. Move reference notes into files opened on demand

History, past decisions and long reference notes can sit in their own files, with one line in CLAUDE.md that says when to open each. Do not import them with `@path`, or they load every time again.

## Doing the split automatically

Step 4 is the one that takes the time, and it has to be redone as the file grows. [MinniMemoryMCP](https://minniai.com/minnimemorymcp) does it for you. It sorts your CLAUDE.md or AGENTS.md, MEMORY.md and the files they import into a small part that loads on every turn and files Claude opens only when a task needs them. Every line is kept, the originals are backed up first, and `undo` puts them back byte for byte.

install it for Claude Code

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

With MinniMemoryMCP 1.6.0 on our test memory, the agent went looking in its memory 17 times instead of 89 over the same 87 answers, and the run used 47.2% fewer tokens. Measured 15 November 2026: at API rates, a Claude Code session on our test memory cost $0.47 before MinniMemoryMCP 1.6.0 and $0.29 after on average, 37.7% less (each of the three sessions 33.9% to 40.0% less). A blind judge found 80 of 87 answers correct before and 81 after.

Related: [Claude Code memory: CLAUDE.md vs MinniMemoryMCP](https://minniai.com/learn/claude-code-memory-claude-md-vs-minnimemorymcp) for what belongs in each kind of file, [Where Claude Code keeps its memory](https://minniai.com/learn/claude-code-memory-directory) for every path, and [AGENTS.md too large](https://minniai.com/learn/agents-md-too-large) for the same problem in Codex.

Try MinniMemoryMCP

Free, runs on your computer, and every change can be undone. Two commands install it for Claude Code; the [docs](https://minniai.com/minnimemorymcp/docs) cover Codex and the rest.

install it for Claude Code

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

## 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 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

- [AGENTS.md too large: what Codex cuts off and how to split it](https://minniai.com/learn/agents-md-too-large) The 32 KiB cap, how to see which files load, and five ways back under it.

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
