claude-memory

Memory files are automatically loaded at session startup, consuming tokens from your 200k context window. Every instruction competes with Claude Code's ~50 built-in instructions, leaving ~100-150 effective instruction slots for your customizations.

Two approaches available:

• CLAUDE.md - Single file, simpler, best for small projects
• .claude/rules/ - Modular files with optional path-scoping, best for large projects

<quick_start> <bootstrap_new_project> Run /init in Claude Code to auto-generate a CLAUDE.md with project structure.

Or create manually at project root:

# Project Name

## Tech Stack

- [Primary language/framework]
- [Key libraries]

## Commands

- `npm run dev` - Start development
- `npm test` - Run tests
- `npm run build` - Build for production

## Code Conventions

- [2-3 critical conventions]

## Important Context

- [1-2 architectural decisions worth knowing]

</bootstrap_new_project>

<quick_add_memory> Press # during a Claude Code session to quickly add new memory items without editing the file directly. </quick_add_memory>

<edit_memory> Use /memory command to open CLAUDE.md in your system editor. </edit_memory> </quick_start>

<file_hierarchy> Claude Code loads CLAUDE.md files in a specific order. Higher priority files are loaded first and take precedence.

<loading_order>

Priority	Location	Purpose	Scope
1 (Highest)	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)	Enterprise policy (managed by IT)	All org users
2	./CLAUDE.md or ./.claude/CLAUDE.md	Project memory (git-tracked)	Team via git
2	./.claude/rules/*.md	Modular rules (git-tracked)	Team via git
3	~/.claude/CLAUDE.md	User preferences (global)	All your projects
3	~/.claude/rules/*.md	Personal modular rules (global)	All your projects
4 (Lowest)	./CLAUDE.local.md	Personal project prefs (auto-gitignored)	Just you
</loading_order>

<recursive_loading> Claude recurses UP from current directory to root, loading all CLAUDE.md files found.

Running Claude in foo/bar/ loads:

1. foo/bar/CLAUDE.md
2. foo/CLAUDE.md
3. Root-level files

Claude also discovers CLAUDE.md in SUBTREES when reading files in those directories. </recursive_loading>

<monorepo_strategy> For monorepos, use layered approach:

root/
├── CLAUDE.md              # Universal: tech stack, git workflow
├── apps/
│   ├── web/CLAUDE.md      # Frontend-specific patterns
│   └── api/CLAUDE.md      # Backend-specific patterns
└── packages/
    └── shared/CLAUDE.md   # Shared library conventions

Root file defines WHEN to use patterns; subtree files define HOW. </monorepo_strategy> </file_hierarchy>

<rules_directory> The .claude/rules/ directory provides a modular alternative to monolithic CLAUDE.md files. Instead of one large file, you organize instructions into multiple focused markdown files.

<when_to_use_rules> Use .claude/rules/ when:

• Project has many distinct concerns (testing, security, API, frontend)
• Different rules apply to different file types
• Team members maintain different areas
• You want to update one concern without touching others

Use CLAUDE.md when:

• Project is small/simple
• All rules are universal
• You prefer a single source of truth </when_to_use_rules>

<rules_structure>

.claude/rules/
├── code-style.md      # Formatting and conventions
├── testing.md         # Test requirements
├── security.md        # Security checklist
├── frontend/
│   ├── react.md       # React-specific patterns
│   └── styles.md      # CSS conventions
└── backend/
    ├── api.md         # API development rules
    └── database.md    # Database conventions