Auto Memory Architecture — Structuring What Persists
Good memory architecture is the difference between Claude that feels like a collaborator and Claude that re-introduces itself every session. This article covers how to structure project memories for lasting usefulness, when memories go stale, team memory patterns, and why wrong memories are worse than no memories.
Quick Reference
- →MEMORY.md is the index — it loads on every session start, individual files load when referenced
- →Four memory types: user (who you are), feedback (how to work), project (context), reference (where to look)
- →Feedback memories are the most high-value: they prevent repeated mistakes across all future sessions
- →Include WHY in feedback memories — rules without reasons get misapplied at edge cases
- →Memories about code structure go stale — verify before acting on named files or functions
- →Project memories belong in project memory; personal memories belong in user-level or personal files
- →A wrong memory actively misleads Claude — stale memories are worse than no memories
- →Audit memory files periodically: ask Claude 'what do you remember about this project?'
In this article
The Full Memory System Architecture
The auto memory system has two layers: MEMORY.md as a lightweight index, and individual memory files that hold the actual content. This split matters because MEMORY.md loads on every session start — it needs to stay lean. Individual memory files load only when referenced, so their content can be more detailed without taxing every session.
Each memory file has YAML frontmatter with name, description, and type fields. The description field is the one-liner that appears in MEMORY.md — write it to be useful for deciding relevance, not just as a label.
The Four Types in Depth
Each memory type has different characteristics — different shelf life, different value, different risk of going stale. Understanding the types helps you write memories that age well.
user — Who You Are
Your role, expertise level, domain knowledge, and working style. These change slowly — a user memory written today will still be valid in six months. Include expertise gaps ('new to React, strong in Go') because they shape how Claude explains things. Avoid negative judgements. Save: 'senior engineer, 10 years backend, learning the frontend' not 'struggles with CSS'.
feedback — How to Work With You
The most valuable type. These are behavioral rules derived from corrections you've made (don't do X) and approaches you've validated (yes, keep doing that). The rule alone is not enough — include WHY and how to apply it at edge cases. A feedback memory without a why becomes a puzzle the next engineer (or future Claude) can't resolve.
project — Non-Obvious Context
Decisions, constraints, and ongoing work that is not obvious from reading the code. Key word: non-obvious. If Claude can determine it from reading the codebase, it doesn't need to be in memory. Save decisions that have business or security reasons behind them that the code doesn't capture. Include absolute dates when saving time-sensitive project context.
reference — Where to Look
Pointers to external systems: Linear project names, Slack channels, Grafana dashboards, runbooks, documentation URLs. These are stable (URLs and project names rarely change) and high-value (finding the right resource quickly saves time). Save when you discover where something lives so you don't have to hunt for it next session.
Structuring Project Memories for Maximum Usefulness
Well-structured memories are concise, verifiable, and actionable. Poorly structured ones are vague, stale, or redundant with what's already in the codebase.
| Good memory | Bad memory |
|---|---|
| Auth uses JWT in HttpOnly cookies — see src/lib/auth/cookies.ts | Authentication is implemented |
| Never mock the DB in tests — past incident where mock passed but prod migration failed | Use real databases in tests |
| Staging DB (postgres://staging:5432/acme) is read-only, no migrations | Be careful with staging |
| Bugs tracked in Linear project 'API' — not GitHub issues | We use Linear |
The difference: good memories are specific, include the reason, and tell Claude exactly where to look or what to do. Bad memories are so vague that Claude already knows them, or knows them from the codebase.
Before saving a project memory, ask: can Claude determine this by reading the codebase? If yes, skip it — the code is authoritative. Save only what the code cannot tell Claude: business decisions, historical context, team agreements, external system locations.
When Memories Go Stale
Every memory is a claim about the past. The code evolves; memories don't update themselves. A memory that names a specific function, file, or path is a claim that it existed when the memory was written — it may have been renamed, moved, or deleted since.
| Memory type | Staleness risk | Verification approach |
|---|---|---|
| user | Low — expertise and preferences change slowly | Review quarterly or after major skill shifts |
| feedback | Low-Medium — rules are usually durable, but codebases change | Review when a major refactor changes the relevant code area |
| project | High — decisions get revisited, work completes, priorities shift | Review monthly or when starting a new phase of work |
| reference | Medium — URLs and project names occasionally change | Verify if a reference hasn't been used in 3+ months |
Audit periodically
Ask Claude: 'What do you remember about this project?' It will read MEMORY.md and summarize stored memories. Review the summary for memories that no longer match current reality.
Update on contradiction
If Claude's observation of the current code contradicts a memory (e.g., the file a memory names no longer exists), that memory should be updated or removed. Say 'update the memory about X' or edit the file directly.
Delete completed project memories
Project memories about in-progress work become clutter once that work ships. Say 'forget that we're working on the billing migration' or delete the file directly after the work is done.
A memory saying 'auth uses session cookies' when the project has since migrated to JWT will cause Claude to suggest session-based approaches, audit the wrong code, and miss the actual auth files. Stale memories don't just fail to help — they cause Claude to act on wrong information. When in doubt, delete rather than leave stale.
Team Memory Patterns
Memory files are personal — they live in ~/.claude/projects/ on your machine and are not shared with your team. But the content of memories often comes from team decisions. There's a pattern to what belongs in memory vs what belongs in the repo.
| Content | Where it belongs | Why |
|---|---|---|
| Team coding conventions (naming, exports, patterns) | CLAUDE.md (committed) | Applies to everyone — share it |
| Architecture decisions with business context | Your project memory (personal) | You encountered and learned this — others may too, independently |
| Personal working preferences | User memory or ~/.claude/CLAUDE.md | Specific to you — not relevant for teammates |
| Locations of external resources (Linear, Grafana) | Reference memory | Your memory of where things are — others need to discover their own |
| Security and workflow constraints | Both CLAUDE.md AND project memory | CLAUDE.md for team enforcement; memory adds personal context on why |
A common pattern: a team decision is documented in CLAUDE.md for enforcement, and in your project memory for context. CLAUDE.md says 'use HttpOnly cookies for auth'. Your memory adds 'this was a security team mandate from Q1 2026 — it's non-negotiable'. The memory gives you the why when you need to defend the decision in a PR review.
Best Practices
Do
- ✓Include WHY in every feedback and project memory — rules without reasons get misapplied
- ✓Apply the non-obvious test before saving: if Claude can learn it from the code, skip it
- ✓Use absolute dates in project memories (2026-03-15, not 'last month')
- ✓Audit memories quarterly by asking Claude to summarize what it remembers
- ✓Delete completed project memories — finished work shouldn't clutter the index
- ✓Verify named files and functions before acting on a memory — they may have been renamed
Don’t
- ✗Don't save code patterns, conventions, or architecture to memory — those belong in CLAUDE.md
- ✗Don't save git history or change summaries — git log is authoritative
- ✗Don't leave stale memories — wrong memories actively mislead Claude
- ✗Don't let MEMORY.md grow past 200 lines — archive old memories rather than accumulating
- ✗Don't confuse personal memory (~/.claude/projects/) with team config (CLAUDE.md) — they serve different purposes
Key Takeaways
- ✓MEMORY.md is a lean index; memory files hold the details — this split keeps every session start fast
- ✓Feedback memories are the highest-value type — they prevent repeated mistakes permanently
- ✓Always include WHY in feedback and project memories so Claude can apply them at edge cases
- ✓Project memories go stale fastest — audit and update them monthly
- ✓Wrong memories are worse than no memories — delete stale entries rather than leaving them
Video on this topic
How to Structure Claude Code Auto Memory for Real Projects
tiktok