CLAUDE.md is boot context, not memory. It can tell Claude Code how to work in a repository, but it does not create source-linked writes, retrieval traces, supersession, tenant scope, or deletion handles. Use static files for durable instructions and memory for facts that change or accumulate.
Last updated: June 20, 2026.
What is CLAUDE.md good for?
CLAUDE.md is good for stable repository instructions: commands, conventions, workflow rules, style expectations, and warnings. Claude Code’s memory docs describe project memory files as a way to share instructions with Claude across sessions (Claude Code memory docs). That is useful and worth doing.
The mistake is treating that file as the whole memory system. A static file cannot automatically know which decision happened yesterday, which source supports a claim, or which user asked for deletion.
What is agent memory good for?
Agent memory is good for durable facts and source-linked recall. It can store decisions, preferences, source artifacts, corrections, and transcript turns under a scope. It can retrieve them when relevant and keep them out of the prompt when irrelevant.
LangChain’s memory concepts separate short-term thread state from long-term memory. CLAUDE.md is closer to static instruction context. It is not a long-term memory write path.
Where does CLAUDE.md break at scale?
Static context files break in predictable ways:
| Failure | Symptom | Memory fix |
|---|---|---|
| Staleness | Old instructions remain after a workflow changes | Supersede old facts with source lineage |
| Bloat | File grows until agents ignore parts | Retrieve only relevant memory |
| No write path | Decisions in chats never land in the file | Sync transcripts or save memory |
| No source lineage | A rule exists but no one knows why | Link memory to source artifacts |
| No delete handle | A sensitive fact is hard to target | Store delete handles and tombstones |
| Single-client shape | The file serves one tool’s convention | Expose memory through MCP, REST, or CLI |
Anthropic’s context engineering guidance reinforces the deeper point: current context should be engineered. Static files are one input, not the whole context system.
How should you split static instructions and memory?
Use this rule:
- Put stable operating instructions in CLAUDE.md or AGENTS.md.
- Put source-backed project facts in memory.
- Put one-off scratch state in the current context.
- Put large documents in source storage and retrieve them when needed.
- Put corrections into memory with supersession metadata.
For example, “run tests before closing issue work” belongs in a static instruction file. “Issue #680 cannot publish benchmark numbers” belongs in memory and issue context. “The current command is still running” belongs only in working context.
How do you make CLAUDE.md and memory work together?
Keep CLAUDE.md small and directional. It should tell the agent to use memory for prior decisions rather than trying to contain all prior decisions itself. Example:
Before implementing, use Answer Engine memory to retrieve recent decisions for this repo and issue.
Do not rely only on this file for prior context.Then configure the memory server through MCP:
{
"mcpServers": {
"answer-engine": {
"command": "npx",
"args": ["answer-engine-mcp"],
"env": {
"ANSWER_ENGINE_API_KEY": "ae_live_your_key_here",
"ANSWER_ENGINE_API_URL": "https://engine.answeragent.ai",
"ANSWER_ENGINE_LIBRARY": "personal-memory"
}
}
}
}The MCP introduction explains why this is client-portable. The same memory server can serve more than one agent surface.
How do you migrate static context into memory?
Do not blindly import the entire file as one memory. Split it into source-backed rules and decisions:
- Keep current stable rules in the file.
- Move historical decisions into source artifacts or memory records.
- Add links from memory records back to issues, docs, commits, or transcripts.
- Mark obsolete rules superseded instead of leaving both versions active.
- Test a fresh session with one known project question.
If a rule changes often, memory plus source lineage is usually better than editing a giant static context file.
What should you read next?
Read Give your coding agent memory of your codebase, Claude Code loses context after compaction, and Context Engineering vs Memory.