From the team behind aidrop.it — one workspace to build, host, and keep changing your code.
Writing a CLAUDE.md is the single best first step for working with coding agents — and it has a hard ceiling. File-based memory loads everything into every session, stops at the repo boundary, and fragments the moment you use more than one tool. Knowing where the ceiling is tells you when to add a real memory layer on top.
To be clear: keep your CLAUDE.md. Repo conventions, build commands, and architecture notes belong exactly there, versioned in git next to the code they describe. The problem is what happens when you try to make one file carry your whole working memory.
Limit 1: the whole file loads every time
CLAUDE.md is read into context at the start of every session — all of it, relevant or not. As the file grows, every session pays its full token cost, and the useful signal gets diluted by entries that don't apply to today's task. File memory has no retrieval step; it's all-or-nothing. Past a few hundred lines, growth makes the agent worse, not better.
Limit 2: it stops at the repo boundary
A CLAUDE.md knows one repository. Your working memory doesn't: client preferences, cross-project decisions, infrastructure quirks, things you learned in a different codebase last month. None of that has a home in a per-repo file — so it either gets duplicated across repos (and drifts) or stays in your head (and never reaches the agent).
Limit 3: every tool wants its own file
Claude Code reads CLAUDE.md, Codex reads AGENTS.md, ChatGPT wants custom instructions, OpenClaw keeps its own workspace files. Same knowledge, four formats, four copies to keep in sync by hand. Update a decision in one and the other three quietly serve the stale version. Files don't sync; you become the sync — and when nobody keeps up, you get code nobody in the room can explain — the silo problem behind switching tools without losing context.
What goes on top: a retrieval-based memory layer
The fix isn't a bigger file — it's memory with a retrieval step, shared across tools. Because that store now holds knowledge from many sources, securing what gets written into it becomes its own discipline. The division of labor is clean: CLAUDE.md keeps the repo's stable conventions; the memory layer holds everything that's cross-repo, cross-tool, or evolving.
A practical split
Put in CLAUDE.md: build/test commands, code style, architecture constraints — stable facts a stranger needs in this repo. Put in shared memory: decisions and their reasoning, client and project context, preferences, corrections — anything that changes, spans repos, or should follow you into other tools. If you're pasting the same paragraph into a second file, it belongs in memory. The same split applies to workflows, not just facts — see how skills turn a repeatable procedure into structure an agent can follow instead of a paragraph nobody rereads.
FAQ
Should I still use CLAUDE.md? Yes — it's the right place for stable, repo-scoped conventions and is versioned with the code. Just don't ask one static file to be your entire memory.
How big should a CLAUDE.md be? Small enough that every line earns its token cost in most sessions — typically one or two screens. If you're scrolling, you're paying for context the agent rarely needs.
What's the difference between CLAUDE.md and MCP memory? CLAUDE.md is static, repo-scoped, and fully loaded every session. MCP memory is shared across tools and repos, updated as you work, and retrieved selectively — the agent pulls only what the task needs.
One workspace to build, host, and keep changing your code
The repository, what the project knows, the rules a change has to follow, and the path to an address — kept together, and reachable by the coding agent your team already uses.