Auto Memory System
Auto memory is a per-project file-based system Claude Code uses to remember user preferences, project status, and feedback across sessions. Stored in ~/.claude/projects/<project-path-slug>/memory/ as markdown files (the slug is the project's absolute path with slashes replaced by hyphens, e.g. /Users/me/app → -Users-me-app). Loaded automatically into context when relevant.
Auto memory is a sticky-note board in the office — short labels (index), full notes pinned (detail files). Read the labels every morning; pull the note down when you need it.
Four memory types: user (who the user is, role, expertise), feedback (corrections and confirmations), project (active goals, deadlines, decisions), reference (pointers to external systems like Linear, Slack channels). MEMORY.md is a one-line index pointing to detail files. Memories are loaded based on description matching against the current conversation. Updates happen automatically when the model detects new information worth remembering.
Memory writes are at the model's discretion — it watches for explicit ('remember X') and implicit ('we always do Y') signals. Memory is project-scoped (different projects have different memory sets) but the user file applies broadly. Index size matters: MEMORY.md content is loaded into every prompt, so the index stays one-line-per-entry; detail files only load when the description matches. Stale memory: timestamps and 'why' fields help judge whether a memory still applies. Verification: before acting on a memory, confirm it's still true (the file may have been renamed since).
Claude Code's auto memory remembers things across sessions — user preferences, project status, corrections I've given before, references to external systems. It's file-based in ~/.claude/projects/<hash>/memory/, organized by type. The model writes memories when it detects information worth saving — explicit 'remember X' or implicit pattern recognition. The index (MEMORY.md) loads every session; detail files load when descriptions match the current conversation. The trap is stale memory — I make sure 'why' is captured so future sessions can judge whether the memory still applies.
Treating memory as a wiki for the codebase. Don't save 'this project uses TypeScript' — git/package.json say so. Save 'we tried Y and it didn't work because Z' — non-derivable context.