# Memory System AI assistants forget everything between sessions. The memory system provides persistent, file-based memory that carries context forward. ## How It Works Claude Code maintains a memory directory at `~/.claude/projects//memory/`. Each memory is a markdown file with frontmatter metadata, indexed by a `MEMORY.md` file. ## Memory Types ### User Memories Information about who you are — role, expertise, preferences. Helps the AI tailor its approach. ```markdown --- name: user_role description: User is a senior infrastructure engineer with deep Linux/networking expertise type: user --- Senior infrastructure engineer. Deep expertise in Linux, ZFS, Proxmox, networking. New to React frontend work — frame frontend explanations in terms of backend analogues. ``` ### Feedback Memories Corrections and confirmed approaches — what to do and what NOT to do. **The most important type.** These prevent the AI from making the same mistake twice. ```markdown --- name: feedback_subagent_safety description: Never use subagents for destructive server operations type: feedback --- Never use subagents for destructive server operations (git history changes, bare repo operations, database modifications). Do these manually, one at a time. **Why:** A subagent running destructive ops in parallel caused data loss. The main conversation can't intervene if a subagent goes wrong. **How to apply:** Before dispatching any agent, check if the task involves destructive operations. If yes, do it in the main conversation sequentially. ``` ### Project Memories Ongoing work, decisions, and context that isn't derivable from code or git history. ```markdown --- name: project_auth_rewrite description: Auth middleware rewrite driven by legal compliance, not tech debt type: project --- Auth middleware rewrite is driven by legal/compliance requirements around session token storage, not tech-debt cleanup. **Why:** Legal flagged the current implementation for non-compliant token storage. **How to apply:** Scope decisions should favor compliance over ergonomics. ``` ### Reference Memories Pointers to where information lives in external systems. ```markdown --- name: reference_bug_tracker description: Pipeline bugs tracked in Linear project INGEST type: reference --- Pipeline bugs are tracked in Linear project "INGEST". API monitoring alerts go to #oncall-api Slack channel. ``` ## MEMORY.md Index `MEMORY.md` is a one-line-per-entry index of all memory files. It's loaded into every conversation. ```markdown # Memory Index - [user_role.md](user_role.md) — Senior infra engineer, new to React - [feedback_subagent_safety.md](feedback_subagent_safety.md) — No subagents for destructive ops - [project_auth_rewrite.md](project_auth_rewrite.md) — Auth rewrite is compliance-driven - [reference_bug_tracker.md](reference_bug_tracker.md) — Bugs in Linear INGEST project ``` Keep entries under 150 characters. MEMORY.md is truncated after 200 lines. ## What NOT to Save - Code patterns or architecture (derivable from reading current code) - Git history (use `git log` / `git blame`) - Debugging solutions (the fix is in the code, context in the commit message) - Anything already in CLAUDE.md - Ephemeral task details (use task tools instead) ## When to Save - **Immediately** when the user explicitly asks to remember something - **Proactively** when you learn about the user's role, preferences, or expertise - **After corrections** — if the user says "don't do X", save it as feedback - **After confirmed approaches** — if something non-obvious worked, save that too - **When project context emerges** that won't be in code (deadlines, stakeholder decisions, compliance requirements) ## When to Read - At conversation start (MEMORY.md index is auto-loaded) - When the user references prior-conversation work - Before making decisions that prior feedback might inform - When the user says "check", "recall", or "remember" ## Stale Memory Memories can become outdated. Before acting on a memory: - If it names a file path: check the file exists - If it names a function or flag: grep for it - If the user asks about *current* state: prefer `git log` or reading code over recalling a snapshot "The memory says X exists" is not the same as "X exists now."