Lesson 2: Deep Dive into Claude Code auto memory

2.1 The Four Categories of auto memory

auto memory is not just a simple "recorder"; it consists of structured notes actively written by the LLM. The LLM evaluates what is worth retaining long-term and categorizes it into four types:

Type	Purpose	Example
user	Identity, roles, and technical preferences	"User is a backend engineer, primary language is Go."
feedback	Practices you've corrected or confirmed	"Do not mock DB in tests — previously caused production issues."
project	Background, long-term decisions, deadlines	"Auth rewrite is due to compliance, not technical debt."
reference	External resource pointers (Linear, Jira, Slack)	"Pipeline bugs are tracked in Linear project: INGEST."

2.2 Storage Structure and Loading Mechanism

auto memory data is stored locally, typically at ~/.claude/projects/<project_hash>/memory/.

Directory Structure:

• MEMORY.md: The index file. Claude Code automatically loads the first 200 lines (or 25KB) at startup.
• Individual .md files: Each specific memory (e.g., user_preferences.md) is a separate Markdown file with frontmatter.

The Writing Workflow:

1. Evaluation: The LLM analyzes the conversation to identify facts worth recording.
2. Categorization: Selects the appropriate type (user/feedback/project/reference).
3. Writing: Generates the individual Markdown file.
4. Indexing: Adds a reference entry to MEMORY.md.

2.3 What NOT to Record

To maintain the precision of the memory system, official guidelines state that auto memory should not record:

• Patterns or paths that can be derived directly from reading the code.
• Git history (git log is the authoritative source).
• Temporary task states or transient session context.
• Rules already defined in CLAUDE.md.