Keep CLAUDE.md short: move the rest into shared memory

Last updated October 30, 2026

A CLAUDE.md file loads into every Claude Code session, so every line costs context on every task, and Anthropic suggests keeping each one under 200 lines. To shrink it, keep only what nearly every task needs, such as how to build and test, the code style and where things live. Move past decisions, how each service works, gotchas and rules for one corner of the code into a memory server, saved one rule or decision per memory. The agent then searches for the few it needs. The same steps work for AGENTS.md in Codex.

Why a long CLAUDE.md hurts

Claude Code reads CLAUDE.md at the start of every session, before it knows what the task is. Its documentation says to keep each file under 200 lines, because longer files use more context and are followed less closely. Codex stops reading AGENTS.md files once they reach 32 KiB together, by default.

Instruction files also grow in one direction. When a decision changes, an agent tends to add the new rule and leave the old one, so the file ends up holding both. A reader, person or agent, then has to guess which one is current.

What to keep in the file

Keep what applies to nearly every task, and what the agent needs before it can even search:

• how to build, test and run the project;
• code style and naming rules;
• where the main parts of the code live;
• one line telling the agent to search memory before it changes code.

What to move into memory

Move what matters only for some tasks, or what changes over time:

• decisions and why they were made ("we moved billing to the ledger-api because...");
• how a service or an integration works;
• gotchas and mistakes not to repeat;
• rules for one part of the code;
• notes about people, teams and outside services.

Each of these becomes its own memory, with a name and a plain title. A memory is a short document you can read, edit and roll back, not a hidden entry in a vector store.

Move it with one prompt

You need Memlo connected to your agent. See How to add a memory MCP server to Codex or Claude Code memory between sessions. Then paste this into Claude Code or Codex, in the repository's folder:

Read CLAUDE.md, and AGENTS.md if this repository has one. Sort everything in them into two groups.

Keep in the file: what nearly every task needs. How to build, test and run the project, the code style, and where the main parts of the code live.

Move to memory: everything else. Past decisions and why they were made, how each service or integration works, gotchas, rules that apply to one part of the code, and notes about people or outside services.

For each item you move, call the memlo tool smart_add_memory with:
- name: a short snake_case id, like billing_moved_to_ledger_api
- title: a plain sentence that says what it is about
- content: the full rule or decision, with the reason if the file gives one
Save one rule or decision per memory. If smart_add_memory lists a memory that already says the same thing, merge them: edit the older memory with edit_memory so it holds both, then delete the new one with delete_memory.

Then rewrite the file so it holds only the first group, and add this line at the end:
"Before you change code, search memlo for decisions about it."

Show me the list of memories you saved and the new file before you write the file.

Read the list before you accept the new file. The prompt keeps the old file until you say yes, and Git keeps its history either way.

To put the memories somewhere a team can share, add "in the space <name>" to the prompt. Run list_spaces first to see the spaces you can use.

How smart_add_memory avoids near copies

smart_add_memory saves a memory like create_memory, but first checks your memories for ones that already say the same thing. It waits up to 5 seconds for that check. The memory is saved either way, and any near copies are listed, so the agent can merge them. When the check takes longer than 5 seconds, it is skipped and the reply says so.

"Agents need documentation, not memory"

A Hacker News thread titled "Agents don't need memory, they need documentation" argued this openly. Two points from it are fair. Agents get confused when an old decision sits next to the new one. And documents written by agents grow long, because agents add text instead of replacing it.

Both points are about how notes are kept, and they apply to a long CLAUDE.md as much as to a memory store. Here is how Memlo handles them:

• A memory is a document. Each one has a name and a title, and you can open it and edit it in the Memlo app or through any connected agent.
• Edits replace text. edit_memory swaps exact text in place, so the old rule is gone from the current version instead of sitting next to the new one.
• Old versions are kept, not mixed in. Every change is a new version. memory_history shows them, with when each was written and by whom, and restore_memory brings one back.
• Out-of-date memories can be retired. retire_memory hides a memory from search without deleting it.

So the answer is documentation, kept as many small documents with history, that the agent searches instead of loading all at once. CLAUDE.md stays for the few rules every task needs.

Frequently asked questions

How long should CLAUDE.md be?

Anthropic's Claude Code documentation suggests keeping each CLAUDE.md under 200 lines. Longer files use more context in every session and are followed less closely.

Does this work for AGENTS.md and Codex?

Yes. The prompt reads AGENTS.md too, and Codex can run it once Memlo is added with codex mcp add. Codex stops reading AGENTS.md files at 32 KiB together by default, so a short file matters there as well.

Will the agent still follow rules I moved out of CLAUDE.md?

Only when it finds them. That's why the file keeps one line telling the agent to search memory before it changes code, and why each memory gets a plain title that search can match. Keep a rule in the file if every task needs it.

Can my team share the memories?

Yes. Save them in a space, then share the space with people by email as a Viewer or an Editor, or with a team. Each person's agents then search the same memories.

Isn't Git history enough?

Git keeps CLAUDE.md's history, and that is a good reason to keep the file in the repository. A memory server adds history per note, search, and sharing with agents outside the repository, such as ChatGPT or claude.ai.

Sources

Checked on October 30, 2026:

• Claude Code memory and CLAUDE.md
• Codex AGENTS.md guide
• Agents don't need memory, they need documentation, Hacker News
• Memlo: the setup page and its list of tools