CLAUDE.md vs. Claude Recall: when a markdown file is not enough
A CLAUDE.md file in your repo gives Claude Code a project briefing. It is free, it is standard, and for many projects it is all you need. This is the page about when it stops being enough.
TL;DR
- Use
CLAUDE.mdif your project context fits in two hundred lines and rarely changes. - Use Claude Recall if your context is the cumulative history of dozens of past sessions.
- Use both. Most users do.
Side-by-side
| Capability | CLAUDE.md | Claude Recall |
|---|---|---|
| Free | Yes | Free tier yes |
| Zero install | Yes | One-line install |
| Communicates static project context | Yes | Not its job |
| Communicates dynamic session-history context | Manual edits only | Automatic |
| Searchable across all past sessions | No | Yes |
| Hierarchical (global + repo + ticket) | Manual concat | Planned |
| Survives a six-month gap between contributions | Whatever you remembered to write | Yes |
| Helps a new contributor read your past Claude Code work | Only what is documented | Yes |
Where it wins
CLAUDE.md is the right tool for the static stuff: project conventions, the test command, the deploy pipeline, the architecture diagram. It is a living briefing that the agent reads at the start of every session. There is no reason to replace it.
Where we win
CLAUDE.mdcannot capture what happened in last week's session. The user remembered to update it sometimes; mostly not. Claude Recall makes the dynamic, accumulated context queryable without anyone manually transcribing it. Together: CLAUDE.md for the static brief, Claude Recall for the running history.
When to pick which
- Use
CLAUDE.mdfor “what the agent must know about this repo.” - Use Claude Recall for “what has Claude actually done on this repo.”
Coexistence
Universal. Most projects use both. Claude Recall does not modify CLAUDE.md; the two are orthogonal.
FAQ
Does Claude Recall replace CLAUDE.md?
No.
Could it generate CLAUDE.md from session history?
That is a planned feature direction. The hierarchical version composes context at pipe time and never modifies your CLAUDE.md on disk by surprise.