Memory System

Claude Code uses CLAUDE.md files to maintain persistent context across sessions. These files tell Claude about your project conventions, technology stack, and how you want to be helped. A good CLAUDE.md saves you from explaining the same patterns repeatedly.

Official Documentation: Claude Code Memory

Memory Hierarchy

CLAUDE.md files load in a specific order, with higher levels overriding lower ones:

1. Enterprise Policy (system-wide, set by IT/DevOps)

   • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md
   • Linux: /etc/claude-code/CLAUDE.md
   • Windows: C:\ProgramData\ClaudeCode\CLAUDE.md

2. Project Memory (team-shared in source control)

   • ./CLAUDE.md or ./.claude/CLAUDE.md in your repository root

3. User Memory (personal, applies to all your projects)

   • ~/.claude/CLAUDE.md

The system also loads optional .CLAUDE.local.md files (gitignored) for personal overrides that don't go into source control.

Nested directories can have their own CLAUDE.md files. These load on-demand when you open a file in that directory, letting you scope context to specific sub-projects within a monorepo.

What Goes in Memory

Memory works best for things that don't change sprint-to-sprint:

• Project conventions - Coding standards, file organization, naming patterns, code style rules
• Technology stack - Which frameworks, databases, languages, and architectural patterns you use
• Team preferences - How you do code review, which tools you prefer, commit message format
• Domain context - Business rules, terminology, compliance constraints that affect code decisions
• Development workflow - How testing works, how deployment happens, which tools are required

Don't use memory for current state (who's working on what, what's deployed now). That information changes daily and belongs in your issue tracker or deployment system.

Project vs User Memory: Trade-offs

Project CLAUDE.md (in your repo):

• Shared with your team, version controlled
• Ensures everyone working on the project gets the same instructions
• Good for: stack details, project conventions, architectural principles everyone should know
• Cost: Changes affect the whole team; balance between comprehensive and maintainable

User CLAUDE.md (in ~/.claude):

• Personal, only you see it
• Applies across all your projects
• Good for: your preferred style, tools you always use, personal coding standards
• Cost: Doesn't help teammates who haven't set their own user memory

Most Agronod teams maintain project CLAUDE.md with shared conventions and (optionally) a personal user CLAUDE.md for things only you care about. When the two conflict, project memory wins.

Using Memory Effectively

Import other files into CLAUDE.md to avoid duplication:

# My Project

@path/to/tech-decisions.md
@path/to/coding-standards.md

Update memory when your patterns change. An outdated CLAUDE.md misleads Claude about what your codebase actually does.

Related

• Prompting Techniques
• Context Management
• Output Styles