Part 3 of 7 · Series: Building Your AI Developer Handbook · GitHub
The Goldfish Problem
By default, every Claude session starts completely fresh. No memory of last week's conversation. No memory of the rule you explained three times. No memory of the mistake you made together and fixed together.
"Imagine if your doctor forgot everything about you every time you walked into the clinic. You'd spend 10 minutes re-explaining your history before they could help you."
That's Claude without memory files.
The memory system fixes this. It's a folder of plain markdown files that Claude reads at the start of every session — carrying forward the lessons, preferences, and decisions that would otherwise reset.
Where Memory Lives
~/.claude/projects/your-project/memory/
MEMORY.md ← the index (loads automatically every session)
feedback_rules.md ← lessons from mistakes
user_preferences.md ← how you like to work
project_context.md ← what's happening in the project right now
reference_links.md ← where to find things outside the project
Think of it like a filing cabinet:
- MEMORY.md is the table of contents — one line per memory, always loaded
- Each individual file is a folder in the cabinet — loaded when relevant
The Four Types of Memory
1. Feedback Memory — "Rules Born From Mistakes"
"Every rule in a safety manual was written in response to an accident." — Aviation saying
These files store corrections and confirmations. Every time Claude does something you didn't want — or something you want it to repeat — that lesson becomes a feedback file.
Example: You discover mocked database tests passed while a real production migration failed. You tell Claude: "never mock the database in tests." That becomes a rule that applies to every future session.
**Rule:** Integration tests must hit a real database.
**Why:** Mocked tests passed; prod migration broke.
**Apply:** Never suggest mocking the DB layer in tests.
2. User Memory — "How You Think and Work"
"A good assistant doesn't just do tasks — they understand how their manager thinks."
These files capture your preferences, style, and philosophy — folder structure, state management approach, testing philosophy. Claude reads these and adjusts its suggestions to match your way of working.
3. Project Memory — "What's Happening Right Now"
"Context switches are expensive. The more context you can offload to a file, the less you re-explain every session."
These files track ongoing work — what feature is being built, why a particular decision was made, what the deadline is. Without these, you start every session re-explaining the backstory.
4. Reference Memory — "Where to Look Things Up"
Simple pointers to external resources:
- "Bug tracker is at Linear project INGEST"
- "Design tokens are in Figma file XYZ"
- "Oncall dashboard is at grafana.internal/api-latency"
"A good assistant knows where the filing cabinet is. They don't memorize every document — they know where to look."
The MEMORY.md Index
# Memory Index
- [No DB mocks](feedback_db_testing.md) — integration tests use real DB; mocks missed prod migration bug
- [State ladder](user_state_management.md) — useState→Zustand→TanStack Query; no server state in Zustand
- [Current feature](project_auth_sprint.md) — building OAuth login, deadline 2026-06-20
This is the only file that loads automatically on every session. Intentionally short — one line per memory.
"A good index tells you whether you need to open the drawer. You shouldn't need to read the whole drawer just to find out."
Each line has three parts:
- The name (links to the full file)
- A one-line hook (enough to know if it's relevant right now)
How It Works in Practice
Session 1 (no memory):
You: "How should I structure the auth feature?"
Claude: [gives generic advice based on training data]
You: "I use feature-based folders, not layer-based"
Claude: [adjusts, gives feature-based advice]
Same question, Session 2 (with memory):
[Claude reads: "feature-based folders — /features/auth/, /features/payment/"]
You: "How should I structure the auth feature?"
Claude: [immediately gives feature-based advice — no re-explaining needed]
What NOT to Put in Memory
Memory files are for things that aren't in the code itself.
| Already exists | Don't memorize |
|---|---|
| Code patterns | They're in the code |
| Git history |
git log knows |
| File structure | Read the filesystem |
| Debugging solutions | Fix is in the commit |
"A post-it note on your monitor says 'check Figma before coding UI.' It doesn't copy the entire Figma file onto the post-it."
Memory files decay. The older they are, the more likely they describe something that's changed. The Why field is what tells you whether a memory is still load-bearing.
Starting Your Own Memory System
Start with one file: feedback.md. Every time you correct Claude, add a line:
- Don't use barrel exports in large modules — slows TS server
- Always check bundlephobia before adding a dependency
- State management order: useState first, Zustand only if shared
Over a few weeks you'll have a precise record of how you like to work. Split into separate files when it gets large. Build the MEMORY.md index.
Key Takeaway
Memory files turn Claude from a stateless tool into a contextual collaborator.
The difference between "Claude that needs re-teaching every session" and "Claude that gets better the more you use it" is a folder of markdown files.
"Experience is just lessons that were written down. Wisdom is lessons that were read again."
Next: Part 4 — Battle Scars as Rules: Inside the Feedback Files
Top comments (0)