Claude Code Memory Hierarchy

Complete reference for Claude Code's memory management system.

Memory Locations (Highest to Lowest Priority)

/Library/Application Support/ClaudeCode/CLAUDE.md

/etc/claude-code/CLAUDE.md

C:\Program Files\ClaudeCode\CLAUDE.md

./CLAUDE.md

./.claude/CLAUDE.md

./.claude/rules/*.md

~/.claude/CLAUDE.md

~/.claude/rules/*.md

./CLAUDE.local.md

Key: Files higher in hierarchy load first; more specific memories take precedence.

Memory Discovery

Claude Code discovers memory files by:

1. Upward recursion: From

   cwd

   up to (not including) root

   /

2. Subtree discovery: Nested CLAUDE.md loaded when reading files in those subtrees
3. Automatic loading: All

   .claude/rules/*.md

   files loaded with same priority as

   .claude/CLAUDE.md

View loaded memories: Run

/memory

Import Syntax

CLAUDE.md files can import other files using

@path/to/file

# Project Instructions

See @README.md for project overview.
See @docs/architecture.md for system design.
API reference: @docs/api/README.md

# Personal preferences (not in git)
@~/.claude/my-project-prefs.md

Features:

• Relative and absolute paths supported
• Home directory imports (

  @~/...

  ) for personal preferences
• Not evaluated inside code blocks or code spans
• Recursive imports (max 5 hops)

Modular Rules (

.claude/rules/

)

Basic Structure

project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       ├── security.md     # Security requirements
│       └── api/
│           └── validation.md  # API-specific rules

Path-Specific Rules

Use YAML frontmatter to scope rules to specific files:

---
paths: src/api/**/*.ts
---

# API Development Rules

- All endpoints must include input validation
- Use the standard error response format

Glob Patterns

**/*.ts

src/**/*

*.md

src/**/*.{ts,tsx}

{src,lib}/**/*.ts

tests/**/*.test.ts

Multiple patterns:

---
paths: {src,lib}/**/*.ts, tests/**/*.test.ts
---

Subdirectory Organization

.claude/rules/
├── frontend/
│   ├── react.md
│   └── styles.md
├── backend/
│   ├── api.md
│   └── database.md
└── general.md

All

.md

Symlink Support

Share rules across projects:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

User-Level Configuration

User Memory (

~/.claude/CLAUDE.md

)

Personal preferences applying to ALL projects:

• Code style preferences
• Tooling shortcuts
• Workflow habits

User Rules (

~/.claude/rules/

)

~/.claude/rules/
├── preferences.md    # Personal coding preferences
└── workflows.md      # Preferred workflows

User rules load before project rules; project rules take higher priority.

Quick Memory Addition

#

Shortcut

Start input with

#

# Always use descriptive variable names

Prompts for which memory file to store in.

/memory

Command

Opens memory file in system editor for extensive additions.

/init

Command

Bootstrap a CLAUDE.md for your codebase.

When to Use Each Memory Type

./CLAUDE.md

./CLAUDE.md

./.claude/rules/{topic}.md

./.claude/rules/

paths:

~/.claude/CLAUDE.md

./CLAUDE.local.md

Decision Tree: Choosing Memory Structure

Project Analysis
│
├─ Small project (<500 files, <50 dirs)?
│   └─ Single ./CLAUDE.md
│       └─ Use @imports for large documentation
│
├─ Medium project with topic diversity?
│   └─ ./CLAUDE.md + .claude/rules/
│       ├─ testing.md
│       ├─ code-style.md
│       └─ {topic}.md
│
├─ Monorepo / microservices?
│   └─ Multiple ./CLAUDE.md (one per package/service)
│       └─ Each can have own .claude/rules/
│
├─ File-type-specific patterns?
│   └─ Path-specific rules with paths: frontmatter
│
└─ Personal dev setup needed?
    └─ ./CLAUDE.local.md (gitignored automatically)

Best Practices

Content Guidelines

• Be specific: "Use 2-space indentation" > "Format code properly"
• Use structure: Bullet points under descriptive headings
• Review periodically: Update as project evolves

Rules Organization

• Keep rules focused: Each file covers one topic
• Use descriptive filenames:

  testing.md

  ,

  api-design.md

  ,

  security.md

• Use paths: sparingly: Only when rules truly apply to specific file types
• Organize with subdirectories: Group related rules

Project vs Personal

• Project memory: What the team needs to know
• User memory: Your personal preferences
• Local memory: Your dev environment specifics

File Priority Summary

When the same topic is covered in multiple files:

1. Enterprise policy (highest)
2. Project

   .claude/rules/

   (path-specific first)
3. Project

   CLAUDE.md

4. User

   ~/.claude/rules/

5. User

   ~/.claude/CLAUDE.md

6. Project

   CLAUDE.local.md

   (lowest, but most specific to you)

Common Patterns

Imports for Documentation

# Project Overview

See @README.md for getting started.
Architecture details: @docs/architecture.md
API reference: @docs/api/README.md

Topic-Specific Rules

.claude/rules/
├── testing.md          # Test patterns, mocking, coverage
├── api-design.md       # REST conventions, error handling
├── database.md         # Query patterns, migrations
└── security.md         # Auth, validation, secrets

Path-Specific API Rules

---
paths: src/api/**/*.ts, src/routes/**/*.ts
---

# API Endpoint Rules

- Validate all inputs with zod
- Use consistent error response format
- Include OpenAPI documentation comments

Personal Local Setup

./CLAUDE.local.md

# My Local Setup

## Dev URLs
- API: http://localhost:3001
- Frontend: http://localhost:3000
- Database: postgresql://localhost:5432/mydb

## Debug Commands
```bash
DEBUG=api:* npm run dev