If you use Claude Code, you probably know about MEMORY.md. It's a file where Claude saves notes about your project, your preferences, patterns it's learned, things it should remember across conversations.
It sounds great until your project grows and that file becomes a wall of text that Claude quietly ignores.
The Problem
Claude Code loads MEMORY.md into every conversation automatically. But there's a catch: it truncates everything after 200 lines. Anything past that limit just doesn't exist as far as Claude is concerned.
So what happens is predictable. You work on a project for a few weeks. Claude keeps saving useful context: architecture decisions, infrastructure notes, coding conventions, things you've told it to remember. The file grows past 200 lines. And now the stuff at the bottom, often the most recent and relevant notes, gets cut off.
You end up repeating yourself. Claude forgets decisions you already made. It re-discovers things it already knew last week. Sound familiar?
The Fix
Stop using one big file. Break it into topic files and turn MEMORY.md into a short index that links out to them.
Your memory directory goes from this:
memory/
MEMORY.md ← 400 lines, half of it truncated
To this:
memory/
MEMORY.md ← index (under 200 lines)
architecture-decisions.md
docker-infra.md
plan-phases.md
debugging-notes.md
deferred-items.md
MEMORY.md becomes a table of contents. Short descriptions, links to the detail files. Claude reads the full index every time, then pulls in the specific topic files only when they're relevant to what you're working on.
Nothing gets truncated. Nothing gets lost.
What the Index Looks Like
Keep it lean. Each entry should be one or two lines max:
Project Memory Index
Architecture
Key decisions and patterns: architecture-decisions.md
Infrastructure
Docker setup, deployment, CI/CD notes: docker-infra.md
Current Plan
9-phase implementation roadmap: plan-phases.md
Debugging
Recurring issues and fixes: debugging-notes.md
Deferred Work
Things we decided to do later and why: deferred-items.md
Preferences
- Always use bun instead of npm
- Never auto-commit without asking
- Use Zustand for state, not Redux
That's maybe 30 lines. You have 170 lines of headroom before truncation, and all the real detail lives in files that Claude can read on demand.
Why This Works
It's the same pattern as .claude/agents/. A small markdown file that gives Claude exactly what it needs to know, structured so it can find more detail when it needs it.
The index tells Claude what exists and where to find it. The topic files hold the real depth: architecture rationale, infrastructure configs, deferred work with context on why it was deferred. None of that competes for those 200 lines anymore.
Claude is good at deciding when to read a linked file. If you're asking about Docker, it'll pull in docker-infra.md. If you're planning the next phase, it'll read plan-phases.md. You don't have to tell it to. The index gives it enough context to make that call.
How to Set It Up
You don't even have to do it manually. Just tell Claude:
"Break my MEMORY.md into topic files. Keep the main file as an index under 200 lines, and move detailed sections into separate .md files in the same memory directory."
It'll read your current MEMORY.md, identify the natural topic boundaries, create the files, and rewrite the index. Takes about 30 seconds.
If you're starting fresh, just create the directory structure yourself and start saving notes into topic files from the beginning. Tell Claude: "Save this to architecture-decisions.md, not MEMORY.md."
Tips From Using This for a While
- Keep the index under 100 lines if you can. 200 is the max, but leaving room means you can add quick notes directly to the index without worrying about hitting the limit.
- Use clear file names. Claude uses the file name to decide whether to read it. docker-infra.md is better than notes-3.md.
- Don't create too many files. 5 to 10 topic files is the sweet spot. If you have 30 files, the index itself gets bloated.
- Review and clean up periodically. Tell Claude "review the memory files and remove anything outdated." Context that was useful two weeks ago might just be noise now.
- Put preferences in the index directly. Short, stable things like "always use bun" or "never auto-commit" belong in the index, not in a separate file. They're small and you want Claude to see them every time.
That's It
It's a small change that makes a real difference once your project has enough history. Structure beats bulk. An organized 30-line index with linked detail files gives Claude better context than a 400-line dump where half of it gets cut off.
Try it on your next project and see if Claude stops forgetting things.
Top comments (0)