CLAUDE.md too long: what Claude Code does with it, and how to split it
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 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 alland look under Memory files. It lists the CLAUDE.md files that loaded at launch and what each costs. - Run
/memoryto see every memory file location and open any of them. - Run
/usageon 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 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.
$ npm i -g minnimemory
$ minnimemory installWith 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 for what belongs in each kind of file, Where Claude Code keeps its memory for every path, and AGENTS.md too large for the same problem in Codex.