Memory System

Claude Code persists information between sessions using a file-based memory system in ~/.claude/. It uses 4 typed memory categories and an index file (MEMORY.md) that is always loaded into context.

4 memory types 200 line limit on MEMORY.md 25KB size limit on MEMORY.md

Memory types

user

User

· Role, preferences, knowledge level

Example: "Is a data scientist, new to React. Explain frontend concepts via backend analogues."

When to save: When you learn about the user's background, goals, or working style.

feedback

Feedback

· Corrections and validated approaches

Example: "Don't mock the database in tests. A previous incident showed mock/prod divergence breaks migrations."

When to save: When the user corrects an approach OR confirms a non-obvious choice worked.

project

Project

· Ongoing work, deadlines, incidents

Example: "Merge freeze begins 2026-03-05 for mobile release cut. Flag non-critical PRs after that date."

When to save: When you learn who is doing what, why, or by when. Relative dates are converted to absolute.

reference

Reference

· Pointers to external systems

Example: "Pipeline bugs are tracked in Linear project INGEST."

When to save: When you learn about resources in external tools (Linear, Grafana, Slack channels, etc.).

File structure

Each memory is stored as a separate markdown file with YAML frontmatter. MEMORY.md is the index.

~/.claude/projects/<slug>/memory/

├── MEMORY.md # index, max 200 lines / 25KB

├── user_role.md

├── feedback_testing.md

└── reference_tools.md

What is NOT saved in memory

× Code patterns, conventions, or file paths (derivable from the code)

× Git history or who changed what (use git log / git blame)

× Debugging solutions or fix recipes (the fix is in the code)

× Anything already documented in CLAUDE.md

× Ephemeral task details from the current session

× PR lists or activity summaries (frozen in time, stale quickly)

Automatic memory extraction

Runs in background : A fork of the main agent handles extraction without blocking your session.

Triggers after silent turns : Activates when the main model completes a turn without making any tool calls.

Max 5 turns : The extraction agent has a maximum of 5 turns to identify and save relevant memories.

Limited permissions : Read/Grep/Glob are unrestricted. Bash is read-only. Write/Edit are restricted to the memory directory only.

Deduplication : Does not run if the main agent already wrote to memory in the same session, avoiding duplicates.

Cache sharing : Shares the prompt cache with the parent session for efficiency.

! MEMORY.md is silently truncated at 200 lines

If the MEMORY.md index exceeds 200 lines or 25KB, it is truncated without warning. Entries past the limit simply don't load into context. Keep the index concise: one line per memory file, under 150 characters each.