Auto Memory — Claude Code's Persistent Cross-Session Memory

Source: wiki synthesis: nate-herk-every-level-of-claude, claudemd-file-primer, seven-claude-use-cases-rick-mulready

Claude Code’s Auto Memory is a file-based persistence layer that stores per-project facts, corrections, and references as discrete markdown files under .claude/projects/<project>/memory/, indexed by a MEMORY.md table of contents that loads automatically into every session. Distinct from CLAUDE.md (which holds rules-of-engagement that the human curates) and from prompt-injected memory (which lives inside a single conversation), Auto Memory is the layer Claude itself writes — facts harvested from real conversations, encoded as one short index line per memory file, so the system gets sharper at working with this user over time rather than relitigating the same context every session.^[inferred]

Key Takeaways

• What Auto Memory captures vs CLAUDE.md. CLAUDE.md holds project-level rules (stack, conventions, commands). Auto Memory holds project-level facts harvested from conversation — who the user is, what they corrected last week, what state a half-finished project is in, where external systems live. The two layers are complementary, not redundant.^[inferred]
• Four memory types. Memory files split into four functional categories — user (role, preferences), feedback (corrections + confirmations), project (state, decisions, open threads), and reference (pointers to external tools, repos, docs). The MEMORY.md index lists each with a one-line description.^[inferred]
• Auto-loaded into every session. The MEMORY.md index file is read at session start and silently appended to context the same way CLAUDE.md is, so facts persist across sessions without re-prompting.^[inferred]
• Persists across sessions and across surfaces. Per Rick Mulready’s Memory 2.0 walkthrough, the same memory state loads into Claude Code and Cowork sessions — inspect with /memory from either surface.
• Auto-dream is the cleanup pass. Between sessions a background pass merges duplicates, drops contradicted entries, and converts “yesterday” to actual dates. Per Nate Herk’s L5 framing, “memory consolidation (autodream)” is what stops the file pile from slowly drifting on stale information.
• The size discipline that keeps it useful. Index lines stay under ~200 chars each; detail lives in the per-topic memory file, not the index. Bloat in the index breaks loading — the MEMORY.md at the top of this very project hit 26.8KB and was flagged for over-long index entries.^[inferred]

Memory types

• User — long-lived facts about who the human is and how they prefer to work. Role at their company, project ownership, voice/style preferences, brand context. Example index line: “User role — WEO Marketly AI lead — merged dental marketing agency; Karpathy wiki + onboarding course + BAW/Clawdbot are active surfaces.”
• Feedback — corrections and reinforcements harvested when the human pushes back or confirms a pattern. Each entry is a rule the LLM should not relearn the hard way — “WebFetch is blocked on CDN sites, fall back to Tavily,” “Quartz auto-renders frontmatter title, don’t add body H1.” Anthropic’s CLAUDE.md primer describes the same loop (“course-correct, then save”) for CLAUDE.md; Auto Memory is where it lands when the correction is conversational rather than structural.
• Project — state of in-flight work. Open threads, paused integrations, decisions made, milestones reached. Example: “Hermes Codex image backend — open thread, paused 2026-04-28 awaiting URL bridge decision.” This is what makes resumption-after-a-week-away coherent instead of amnesiac.^[inferred]
• Reference — pointers to external systems the conversation routinely touches. Repo paths, deployed URLs, installed MCP servers, scheduled cron triggers. The index entry is a one-line locator; the body file holds the details.^[inferred]

Auto Memory vs CLAUDE.md

	CLAUDE.md	Auto Memory
Author	Human	Claude (with human approval on saves)
Content	Rules of engagement	Harvested facts
When written	Up-front + corrections	Continuously, from conversation
Location	Project root (committed)	.claude/projects/<project>/memory/
Granularity	One file per scope	Many small files, one index
Purpose	”How should you behave?"	"What do you know about me / this project / our history?”

The clean read: CLAUDE.md is prescriptive and stays small; Auto Memory is descriptive and grows linearly with the relationship. Together they replace the two failure modes Anthropic’s primer names — Claude having to re-explore the codebase every session, and Claude guessing wrong about conventions it has been corrected on before.^[inferred]

Related

• claudemd-file-primer — sibling memory layer, human-authored rules
• nate-herk-every-level-of-claude — L5 framing of memory consolidation / autodream
• seven-claude-use-cases-rick-mulready — Memory 2.0 walkthrough across Cowork + Code
• folder-as-workspace-architecture — the project-folder convention Auto Memory is keyed to
• context-management-claude-code — how persistent memory composes with /compact and context windows
• cli-reference — /memory command surface
• hooks — InstructionsLoaded event fires when memory loads; useful for context-injection workflows

Try It

1. Inspect what Claude already knows about you. Run /memory in Claude Code or Cowork. Read every index line. Anything wrong, stale, or duplicated → ask Claude to update or remove it.
2. Practice the save-this-to-memory loop. Next time you correct Claude on a real fact about your project (“we use Drizzle, not Prisma”), end with “save this to memory as a feedback entry.” Future sessions inherit the rule without re-prompting.
3. Audit index bloat once a month. Open MEMORY.md directly. If any index line is more than ~200 chars, push the detail into the referenced topic file and trim the index entry to one sentence — the same discipline CLAUDE.md uses to stay under ~200 lines.