CLAUDE.md and AGENTS.md vs a memory server: which one you need

Last updated October 30, 2026

Use CLAUDE.md or AGENTS.md for a short set of rules that every session should follow, such as build commands, style and project layout. Use a memory server for what grows over time: decisions, facts and preferences that the agent should look up when they matter rather than read in full every session. Many projects need both, and a small project with one person and one agent is often fine with files alone.

What instruction files do well

CLAUDE.md (read by Claude Code) and AGENTS.md (read by Codex, and by Claude Code when a project has no CLAUDE.md) are plain Markdown files in your repository.

• They load automatically at the start of every session. The agent can't miss them.
• They live in version control, so changes are reviewed like code and the whole team gets them.
• They cost nothing to run and need no account.
• They are easy to read and edit by hand.

For rules that apply to almost every task, this is the right place.

Where files get hard to use

• They load in full. Every line costs context in every session, whether the task needs it or not. Claude Code's documentation suggests keeping each CLAUDE.md under 200 lines, because longer files use more context and are followed less closely. Codex stops adding AGENTS.md files at 32 KiB combined by default.
• They are per repository. A decision about a shared service has to be copied into each repository that uses it, and the copies drift.
• They are per tool, unless you share one file. CLAUDE.md is for Claude Code and AGENTS.md is the convention for others. You can make one import the other, but an agent outside your repository, such as claude.ai or ChatGPT, does not see either.
• Finding things means reading. To answer "what did we decide about retries?", the agent opens files one after another until it finds the answer.
• History is in git, not in the note. An outdated line is either edited away or left to mislead.

Claude Code's auto memory solves some of this for one person: the agent writes its own notes. Those notes stay on one computer and are not shared with other computers or other agents.

What a memory server does differently

A memory server stores notes as separate memories behind a search, and agents reach it through MCP tools.

• Search instead of loading. The agent searches for the few memories that match the task and reads only those. In our own measurement, agents using Memlo used 22%* fewer tokens than with file-based memory, on average.
• One store for every agent. Claude Code, Codex, claude.ai and ChatGPT can all use the same memories when they sign in to the same account.
• Not tied to a repository. A memory about a shared service is saved once and found from any project.
• History per memory. In Memlo, every change is kept as a version, an outdated memory can be retired without deleting it, and an old version can be restored.

The costs are real too: it needs an account and a sign-in, the agent has to decide to search (a session-start step helps), and you trust a service with what you save.

When files are enough

• One person, one agent, one repository.
• The notes fit comfortably in a short file.
• The rules change rarely and you want them reviewed in pull requests.

When a memory server helps

• Notes keep growing and the file is getting long.
• You switch between Claude Code, Codex and chat apps and want them to agree.
• Knowledge spans several repositories or a whole team.
• You want to know when a fact changed and what it said before.

Use both

A common setup: keep CLAUDE.md or AGENTS.md short, with the rules every session needs, and add one line telling the agent to search memory before it changes anything important. For Memlo, that line is to call get_prime_directive at the start of each session, which loads how to use Memlo and your space's key memories. Setup for each agent: Claude Code, Codex, other MCP apps.

Frequently asked questions

Is a memory server a replacement for CLAUDE.md?

Not entirely. CLAUDE.md is the right place for rules that apply to every session. A memory server is better for the growing set of decisions and facts that only some tasks need.

How long should CLAUDE.md be?

Claude Code's documentation suggests under 200 lines per CLAUDE.md file. It also notes that imported files load together with the file that imports them, so splitting a file with imports does not reduce its context cost.

Does Claude Code read AGENTS.md?

Yes, from Claude Code version 2.1.277: when a project has an AGENTS.md and no CLAUDE.md in the working folder or above it, Claude Code reads the AGENTS.md. A CLAUDE.md can also import AGENTS.md so both tools share one file.

Can I keep my memories in git instead?

You can keep notes in Markdown files in git, and many people do. You get review and history, but the agent still has to find the right file by reading, and agents outside the repository can't see it.