Memory, persistent state across sessions

An agent with no memory starts every conversation from zero. Memory lets the agent remember who you are, what you're working on, and what guidance you've given, across every new session.

How Claude Code's memory works

Claude Code maintains a memory directory per project (scoped to the current user's projects folder). Memory files are plain markdown. An index file (MEMORY.md) lists every memory with a one-line description. Claude reads the index at the start of every conversation.

Memory types

• User memory, facts about the person (role, expertise, preferences)
• Feedback memory, guidance the user has given about how to work (e.g., "don't write tests without asking")
• Project memory, context about ongoing work (goals, deadlines, blockers)
• Reference memory, pointers to external systems ("project bugs live in Linear")

What to save

• The user's role and expertise level
• Corrections the user has given ("stop summarizing at the end of every response")
• Non-obvious project context ("we're rewriting auth because legal flagged the current setup")
• External resource pointers ("Grafana dashboard for API latency lives here")

What NOT to save

• Code patterns or conventions, these can be read from the codebase
• Git history. git log is authoritative
• Fixes or solutions, they're in the commit; the commit message has the "why"
• Anything already in CLAUDE.md, don't duplicate
• Ephemeral task state, that's what tasks are for, not memory

Memory hygiene

• Keep the index under 200 lines. Claude reads it every session; a bloated index costs tokens and attention.
• Update or delete stale memories. "User is researching X" should be deleted when X is done.
• Organize by topic, not chronologically. You're not keeping a journal.
• Prefer specific over general. "User prefers shorter responses" is less useful than "User rejects responses over 200 words, trim aggressively."

Risks

• Stale memory. Claims stop being true. Before acting on a memory, verify it in the current state.
• Context bloat. Too many memories = every session starts with a wall of text. Prune aggressively.
• Wrong inferences. Memory is a snapshot. If something changed, trust the new reality over old memory.

When memory shines

• You onboard the agent once, role, preferences, standards, and every session inherits it.
• Long-running projects have a shared context doc the agent keeps current.
• Feedback compounds. Corrections you give today shape every session going forward.

Manual memory control

You can tell Claude to remember or forget something explicitly ("remember that I prefer X", "forget what you know about Y"). Claude will update or prune the memory file accordingly.