Claude Code Memory Hierarchy

Complete reference for Claude Code's memory management system.

Memory Locations (Highest to Lowest Priority)

| Memory Type | Location | Purpose | Shared With | |-------------|----------|---------|-------------| | Enterprise policy | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md<br>Linux: /etc/claude-code/CLAUDE.md<br>Windows: C:\Program Files\ClaudeCode\CLAUDE.md | Organization-wide standards (IT/DevOps managed) | All org users | | Project memory | ./CLAUDE.md or ./.claude/CLAUDE.md | Team-shared project instructions | Team via git | | Project rules | ./.claude/rules/*.md | Modular, topic-specific instructions | Team via git | | User memory | ~/.claude/CLAUDE.md | Personal preferences for all projects | Just you | | User rules | ~/.claude/rules/*.md | Personal modular rules | Just you | | Project local | ./CLAUDE.local.md | Personal project-specific preferences | Just you (gitignored) |

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

Memory Discovery

Claude Code discovers memory files by:

Upward recursion: From cwd up to (not including) root /
Subtree discovery: Nested CLAUDE.md loaded when reading files in those subtrees
Automatic loading: All .claude/rules/*.md files loaded with same priority as .claude/CLAUDE.md

View loaded memories: Run /memory command

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

| Pattern | Matches | |---------|---------| | **/*.ts | All TypeScript files | | src/**/* | All files under src/ | | *.md | Markdown files in root | | src/**/*.{ts,tsx} | TS and TSX in src/ | | {src,lib}/**/*.ts | TS in src/ or lib/ | | tests/**/*.test.ts | Test files |

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 files discovered recursively.

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

| Scenario | Recommended Location | |----------|---------------------| | Team coding standards | ./CLAUDE.md | | Build/test/lint commands | ./CLAUDE.md | | Topic-specific rules (testing, API, security) | ./.claude/rules/{topic}.md | | File-type-specific patterns | ./.claude/rules/ with paths: | | Personal code style | ~/.claude/CLAUDE.md | | Your local dev URLs/setup | ./CLAUDE.local.md | | Org-wide compliance | Enterprise policy (IT managed) |

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:

Enterprise policy (highest)
Project .claude/rules/ (path-specific first)
Project CLAUDE.md
User ~/.claude/rules/
User ~/.claude/CLAUDE.md
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