Memory and Auto-Memory: Persistent Context

Every Claude Code session starts with a fresh context window. Without a memory system, you would need to re-explain your project conventions, architecture decisions, and workflow preferences every time. Claude Code's memory system solves this through CLAUDE.md files for explicit instructions and auto-memory for implicit knowledge accumulation.

What You Will Learn

• The hierarchy of CLAUDE.md files and their precedence
• How auto-memory works and what it saves
• The MEMORY.md index file and memory types
• How to manage, edit, and curate your memory files
• Best practices for what to save versus what to skip

---

The CLAUDE.md Hierarchy

CLAUDE.md files are Markdown files that Claude Code reads at the start of every session. They provide persistent instructions, project context, and conventions. There are multiple levels, each with different scope:

Project-Level CLAUDE.md

Located at the root of your repository. This is the most common and important level. Every session in this project reads it.

my-project/
├── CLAUDE.md          # Project-level instructions
├── src/
└── package.json

Content typically includes:

# CLAUDE.md

## Build Commands
npm run dev          # Start development server
npm run build        # Production build
npm test             # Run test suite

## Architecture
- Next.js App Router with TypeScript
- Supabase for database and auth
- Tailwind CSS for styling

## Conventions
- Use functional components with hooks
- Always include error boundaries
- Test files go next to source files

Directory-Level CLAUDE.md

You can place CLAUDE.md files in subdirectories for area-specific instructions. Claude reads them when working in that directory.

src/
├── api/
│   └── CLAUDE.md      # API-specific conventions
├── components/
│   └── CLAUDE.md      # Component guidelines
└── CLAUDE.md          # General source conventions

Example for src/api/CLAUDE.md:

# API Conventions

- All endpoints return JSON with \{ data, error \} shape
- Use Zod for request validation
- Include rate limiting on public endpoints
- Always validate auth tokens before processing

User-Level CLAUDE.md

Located at ~/.claude/CLAUDE.md. Contains your personal preferences that apply across all projects.

# Personal Preferences

- I prefer explicit types over inference
- Use named exports, not default exports
- Keep functions under 30 lines when possible
- I use VS Code with the Vim extension

Team-Level (Shared) CLAUDE.md

Checked into the repository at .claude/CLAUDE.md. Contains team conventions that all developers share.

# Team Conventions

- PR titles follow Conventional Commits format
- All new features need tests before merging
- Use the /review command before creating PRs
- Database migrations go in supabase/migrations/

Precedence Order

When instructions conflict, Claude Code follows this precedence (highest to lowest):

1. Direct prompt instructions (what you type in the session)
2. Directory-level CLAUDE.md (most specific)
3. Project-level CLAUDE.md
4. Team-level .claude/CLAUDE.md
5. User-level ~/.claude/CLAUDE.md

The Auto-Memory System

Auto-memory is Claude Code's ability to save knowledge for itself across sessions. When Claude learns something important during a session (a debugging insight, a project convention, a workflow pattern), it can automatically save it as a memory note.

How It Works

Auto-memory is enabled by default (requires Claude Code v2.1.59+). During a session, Claude evaluates whether information would be useful in future conversations. If it decides something is worth remembering, it writes a Markdown file to your memory directory.

Claude does not save something every session. It decides based on novelty and future utility. Things it tends to save:

• Build commands and common scripts
• Debugging discoveries ("The auth module requires X env var to work locally")
• Architecture insights gained from exploring code
• Code style preferences you correct it on
• Workflow patterns you demonstrate

Memory Storage Locations

Auto-memory files are stored in plain Markdown:

Project memory: ~/.claude/projects/<project-path>/memory/

User memory: ~/.claude/memory/

The MEMORY.md Index

The MEMORY.md file serves as an index linking to individual memory files with descriptions:

# Memory Index

- [Build command preference](feedback_build_commands.md) - Use turbo for builds
- [Image optimization](feedback_unoptimized_images.md) - WebP images are pre-optimized
- [UI review workflow](feedback_uiux_agent.md) - Run reviewer before committing
- [Course builder pattern](feedback_course_builder_agent.md) - Use course-builder agent

Each linked file contains a specific piece of knowledge:

<!-- feedback_build_commands.md -->
When building, always use `npx turbo build --filter=@platforms/appname`
instead of `npm run build` for faster incremental builds.

Memory Types

Auto-memory categorizes notes by type:

• feedback: Corrections or preferences you communicated ("Don't use default exports")
• project: Project-specific discoveries ("The database uses row-level security")
• user: Personal workflow preferences ("I prefer verbose git commit messages")
• reference: Documentation references ("The API docs are at docs/api/README.md")

Managing Memory

Viewing Memory

Use the /memory command in Claude Code to browse all saved memories. Everything is plain Markdown that you can read and edit.

/memory

This shows your memory index and lets you navigate to individual files.

Editing Memory

Since memories are plain Markdown files, you can edit them directly:

# Edit project memory
vim ~/.claude/projects/-Users-you-myproject/memory/MEMORY.md

# Edit a specific memory file
vim ~/.claude/projects/-Users-you-myproject/memory/feedback_build_commands.md

Deleting Memory

Remove files you no longer need:

rm ~/.claude/projects/-Users-you-myproject/memory/feedback_outdated_info.md

Update the MEMORY.md index to remove the reference.

Toggling Auto-Memory

You can disable auto-memory through the /memory interface or in settings:

\{
  "autoMemory": false
\}

Best Practices

What to Save in CLAUDE.md

• Build, test, and deployment commands
• Architecture overview and key design decisions
• Coding conventions and style rules
• File structure and naming conventions
• Environment setup requirements
• Common gotchas and troubleshooting tips

What Auto-Memory Handles Well

• Corrections you make during sessions
• Debugging discoveries that were hard to find
• Workflow preferences you demonstrate by example
• Project-specific quirks that are not documented elsewhere

What to Avoid Saving

• Temporary information (one-off debugging of a now-fixed bug)
• Information that changes frequently (current sprint tasks)
• Secrets or credentials (never put these in memory files)
• Obvious information (standard language features, common library usage)

Memory Hygiene

Review your memory files periodically (monthly is a good cadence). Remove outdated information, consolidate duplicates, and ensure the MEMORY.md index is accurate. Stale memories can mislead Claude in future sessions.

# Quick audit of all memory files
ls -la ~/.claude/projects/-Users-you-myproject/memory/
cat ~/.claude/projects/-Users-you-myproject/memory/MEMORY.md

---

Key Takeaways

• CLAUDE.md files form a hierarchy from user-level to directory-level, with more specific files taking precedence
• Project-level CLAUDE.md at the repository root is the most important file for team alignment
• Auto-memory lets Claude accumulate knowledge across sessions without manual intervention
• Memory files are plain Markdown stored at predictable paths, fully readable and editable
• The MEMORY.md index file links to individual memory notes with descriptions
• Review and curate memory files periodically to prevent stale information from misleading Claude
• Never store secrets in CLAUDE.md or memory files since they are plain text in your filesystem