Claude Code MEMORY.md 200-line limit
keep entrypoint instructions small; pull past fixes and errors from indexed transcripts on demand
Claude Code's auto-memory loads MEMORY.md at the start of every session and truncates the entrypoint after 200 lines or 25 KB. Even below the cutoff, copying build notes, bug postmortems, and debugging history into MEMORY.md or CLAUDE.md taxes every single prompt with stale text.
brew install deja-vu && deja install claude-autonpx @vshulcz/deja-vu install claude-autoWhy always-loaded memory files break down
Three failure modes appear once MEMORY.md passes its first sprint:
- Hard truncation at line 200 / 25 KB: newer notes appended past the cutoff drop silently on session start unless manually reorganized into topic files.
- Fixed token tax on unrelated turns: a migration workaround pasted into
MEMORY.mdsits in context while editing CSS or writing SQL queries. - Isolated per tool and machine path: what Codex CLI, Cursor, or opencode solved yesterday in the same repo never reaches Claude Code's
MEMORY.md.
Three layers instead of one overflowing file
| Layer | Keep short / bounded | Who reads it |
|---|---|---|
CLAUDE.md / .claude/rules/*.md | Repo build commands, architecture boundaries, non-negotiable conventions (< 100 lines) | Claude Code on every session start |
.deja/memory.jsonl | Curated repo gotchas, settled choices, and dead ends promoted via deja repo candidates and deja repo add <id> --kind gotcha | Any teammate or agent via hooks or MCP |
~/.deja/deja.db | Full transcripts across 52 coding agents from before and after install (secret-redacted SQLite + FTS5) | Queried in 0.7 to 0.8 ms by hooks (1,536 bytes per prompt, about 4 KB per tool call) and the deja MCP tool |
Moving history out without losing recall
Trim MEMORY.md and CLAUDE.md back to active workspace rules, then index the transcripts already under ~/.claude/projects/:
$ deja index $ deja install claude-auto
deja install claude-auto leaves your existing rules files intact, registers the single stdio MCP tool deja (477 schema tokens, 8 modes), and attaches Claude Code lifecycle hooks so errors and prior command patterns surface verbatim when needed. For multi-step engineering tasks on the same repository, measured hook plus MCP recall completed work in 52,815 vs 103,443 total tokens compared to an unassisted run, and achieved 97.2% R@5 across all 500 LongMemEval-S questions.
Keeping team gotchas in git
When a session uncovers a project rule that should travel with the repository rather than stay local to one developer's machine, promote that candidate into .deja/memory.jsonl:
$ deja repo candidates $ deja repo add a1b2c3d4 --kind gotcha
Entries stay capped cleanly (600 chars per record, 500 records / 1 MB limit), use merge=union to avoid git merge conflicts, and avoid polluting every Claude Code prompt unless relevant.
Found this useful? Star deja-vu on GitHub.