1588 words | Esment
CLAUDE.md or a memory server?
CLAUDE.md holds reviewed project conventions. A memory MCP server holds what is learned while working. Many solo users only need the file.
╌╌╌╌
CLAUDE.md is for instructions you write and review: build commands, code style, how the project is laid out. A memory MCP server is for what gets learned while working: decisions, dead ends, preferences that change, and context that has to follow you into another tool. One is a file your assistant loads. The other is a service your assistant calls.
If you work alone, in one tool, on one computer, you probably only need the file. Claude Code's built-in auto memory covers much of the rest. A memory server starts to earn its place when the same knowledge has to reach more than one assistant, more than one machine, or more than one person.
What goes where
| What you want to keep | Where it goes | Why |
|---|---|---|
| Build and test commands, code style, project layout, used by several tools | AGENTS.md | Reviewed in pull requests and read by many coding agents |
| Instructions only Claude Code should follow | CLAUDE.md, importing AGENTS.md if you have one | Same review process, with room for Claude-specific notes |
| Your own preferences across every project in Claude Code | ~/.claude/CLAUDE.md | Applies to you only and stays out of the repository |
| Behaviour only Cursor needs, or rules for certain file types | .cursor/rules | Can be scoped with globs and turned on only when relevant |
| A decision and its reason, an approach that failed, a preference that changes | Memory | Learned mid-work, and too specific or short-lived for a reviewed file |
| Context needed in several assistants, or outside any repository | A memory MCP server | A file in a repository does not reach a chat assistant or another tool |
| Something that must never happen | A hook or a permission rule | Files and memory are guidance, not enforcement |
A short test: if a new teammate should read it on day one, it belongs in a file. If you found it out last Tuesday, it is memory. A memory that keeps proving true should move into the file.
How the files load today
Loading behaviour changes, and older guides are often out of date. This is what the official docs say as of the date on this page.
CLAUDE.md in Claude Code
- Claude Code loads CLAUDE.md from your working directory and every directory above it at launch. Files are joined together rather than overriding each other. CLAUDE.md files in subdirectories load later, once Claude works there.
- The docs suggest under 200 lines per file, because longer files use more context and reduce adherence. Rules in .claude/rules can be scoped to paths, so they load only when relevant.
- Anthropic describes these files as context, "not enforced configuration". To block an action outright, the Claude Code memory docs point to a hook.
AGENTS.md
AGENTS.md is an open Markdown format with no required fields, now stewarded by the Agentic AI Foundation under the Linux Foundation. Cursor supports it in the project root and in subdirectories. Nested files are combined with their parents, and the more specific instruction takes precedence.
Some older guides say Claude Code ignores AGENTS.md. Since v2.1.277 it reads the file directly, but by default only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If you have both, Claude reads CLAUDE.md alone unless you import the other file, the pattern Anthropic documents:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`..cursor/rules
Project rules must use the .mdc extension. A plain .md file in that folder is ignored, because it has no frontmatter. Frontmatter decides when a rule applies: always, when the agent judges it relevant, when matching files are in context, or only when you mention it.
Cursor's CLI docs say the CLI reads AGENTS.md and CLAUDE.md at the project root, but its rules page mentions only AGENTS.md. For one file both tools can rely on, AGENTS.md is the safer choice.
Cursor's editor once had a Memories feature. A staff forum reply from November 2025 says it was removed starting with version 2.1.x, and that old memories can be exported to an .mdc file.
The option in between: Claude Code auto memory
Auto memory is on by default in local sessions. Claude writes its own notes about your preferences, your corrections and context it cannot work out from the code, as plain Markdown under ~/.claude/projects/<project>/memory/. Each conversation loads the first 200 lines or 25KB of MEMORY.md, and topic files open when needed. You can browse and edit everything with /memory.
Its limits are about reach. The docs call it machine-local: files are not shared across machines or cloud environments. It is kept per repository, and other tools such as Cursor do not read it. For one person on one computer using Claude Code, this may be all the memory you need.
What a memory MCP server adds, and what it costs
MCP is an open standard for connecting AI applications to external systems. A memory server uses it to offer tools for saving and searching, so any MCP client can use the same store.
- Reach: a decision saved in Claude Code is available in Cursor or any other connected client.
- Scope: memory is not tied to a repository, so it can hold things about clients or habits that have no natural folder.
- Selection: an assistant searches for what is relevant instead of loading everything into every session.
There are real costs too:
- Recall is not automatic. A file is loaded for you, while an MCP tool is called only when the model decides to call it. The Knowledge Graph Memory Server in the MCP project's repository ships a sample system prompt that tells the model to retrieve memories at the start of a chat. Hooks are firmer in apps that support them.
- Nobody reviews it by default. What an assistant saves can be wrong or go stale, so you need a way to see, correct and delete it.
- It is one more thing to run, and one more place your data lives.
When you do not need one
- You use one assistant on one computer.
- Nearly everything worth remembering is about the codebase and should be reviewed anyway.
- Your team already records decisions in a docs folder. Point to it from AGENTS.md or CLAUDE.md instead of copying it.
If you want a memory server and prefer open source or plain files, the Knowledge Graph Memory Server above keeps a local graph, and Basic Memory stores memory as Markdown on your own machine. Either may suit you better than a product with an app and an account.
Where Esment fits
Esment is a memory layer rather than an assistant or a model: it gives Claude, ChatGPT, Cursor and others one shared memory over MCP. It fits when you move between several assistants, including chat apps outside your editor, and want to see what they saved. Conventions still belong in AGENTS.md or CLAUDE.md.
On the Mac, Claude Code and Cursor each connect with Configure on the Assistants page, followed by quitting and reopening the app. If you prefer to edit settings yourself, the manual config has this shape:
{
"mcpServers": {
"esment": {
"url": "<your memory address>/mcp",
"headers": { "Authorization": "Bearer <access key>" }
}
}
}- Recall: optional Claude Code hooks load your memory into every turn, so recall does not depend on Claude choosing to ask. Without hooks, recall depends on the assistant calling the tool, which is why teaching your assistants exists.
- Review: each memory shows which assistant saved it, and you can search, edit, pin or forget it.
- Data: in the Mac app with sync off, memories stay on your Mac and never reach Esment's servers. Anything an assistant reads is still processed by that assistant's vendor. Where your data lives covers every case, including optional cloud memory, which is hosted in the US.
- Limits: the desktop app is Mac only and needs a paid plan. The web dashboard runs in any browser. See plans and pricing.
A setup that holds up
- Start with AGENTS.md, or CLAUDE.md if you only use Claude Code. Keep it short.
- Add a line when you type the same correction twice.
- In Claude Code, leave auto memory on. In Cursor, add rules only for what is truly specific to it.
- Add a memory server when you catch yourself explaining the same thing to a second tool.
- Move memories that prove stable into the file, and delete the ones that stop being true.
Common questions
Does a memory MCP server replace CLAUDE.md?
Out:No. CLAUDE.md is loaded for you at the start of a session and can be reviewed in a pull request, which suits rules that should always apply. A memory server is searched when needed and suits things learned along the way. You can use both.
Does Claude Code read AGENTS.md?
Out:Yes, since v2.1.277, but by default only when no CLAUDE.md or CLAUDE.local.md exists in your working directory or above it. If you have both, add an @AGENTS.md import to CLAUDE.md, or change the Project instructions setting so both load.
Does Cursor read CLAUDE.md?
Out:The Cursor CLI docs say it reads CLAUDE.md at the project root. The rules page does not mention it, so for one shared file use AGENTS.md.
Why does Claude sometimes ignore my CLAUDE.md?
Out:Anthropic describes the file as context rather than enforced configuration. Concrete, checkable instructions work better than general ones, and long or contradictory files reduce adherence. For something that must never happen, use a hook.
Written by the team that builds Esment, so we are not a neutral party. Tools change quickly: check each one before you rely on it.
Get the next chapter by email.
One email per new chapter. Nothing else.