dwmkerr/claude-code-memory-and-rules

Claude Code Memory and Rules

Configure Claude Code's memory system — CLAUDE.md files, modular rules, and auto memory — so instructions persist across sessions.

Quick Reference

You MUST read these references for detailed guidance:

• Memory Types - All memory locations, scopes, and precedence
• Rules Guide - Modular .claude/rules/ with path scoping
• Auto Memory - Claude's self-managed memory system
• Examples - Real-world memory and rules configurations

Core Concepts

Claude Code has two kinds of persistent memory:

1. CLAUDE.md files — Markdown you write with instructions, rules, and preferences
2. Auto memory — Notes Claude writes for itself based on session learnings

Both load at session start. More specific instructions take precedence over broader ones.

Memory Hierarchy

| Scope | Location | Shared With | Priority | |-------|----------|-------------|----------| | Organization | /Library/Application Support/ClaudeCode/CLAUDE.md | All org users | Lowest | | User | ~/.claude/CLAUDE.md | All your projects | | | User rules | ~/.claude/rules/*.md | All your projects | | | Project (shared) | ./CLAUDE.md or ./.claude/CLAUDE.md | Team via git | | | Project rules | ./.claude/rules/*.md | Team via git | | | Project (local) | ./CLAUDE.local.md | Just you | Highest | | Auto memory | ~/.claude/projects/<project>/memory/ | Just you | Per-project |

CLAUDE.md files in parent directories are loaded in full at launch. Files in child directories load on demand when Claude reads files there.

Choosing the Right Location

What do you need?
├── Instruction for ALL your projects?
│   ├── Shared with team? → Not possible at user level
│   └── Just you? → ~/.claude/CLAUDE.md or ~/.claude/rules/
├── Instruction for ONE project?
│   ├── Shared with team? → ./CLAUDE.md or .claude/rules/
│   └── Just you? → ./CLAUDE.local.md
├── Scoped to specific file types?
│   └── .claude/rules/<topic>.md with paths frontmatter
├── Session learnings that persist?
│   └── Auto memory (~/.claude/projects/<project>/memory/)
├── Automated enforcement (not guidance)?
│   └── Hook — use the claude-code-hook-development skill
└── Organization-wide policy?
    └── Managed CLAUDE.md (deployed by IT)

Rules vs Hooks

Rules (CLAUDE.md / .claude/rules/) are instructions — natural language that Claude interprets with judgment.

Hooks (.claude/settings.json) are enforcement — shell commands that execute deterministically on events. Use the claude-code-hook-development skill for hooks.

| Need | Use | |------|-----| | "Use 2-space tabs in this project" | Rule — .claude/rules/code-style.md or ./CLAUDE.md | | "I prefer TypeScript over JavaScript" | Rule — ~/.claude/CLAUDE.md (user-level) | | "API routes must validate input" | Rule — .claude/rules/api.md with paths: src/api/** | | "Remember the DB uses port 5433" | Auto memory or ./CLAUDE.local.md | | "All engineers must follow X policy" | Rule — Managed CLAUDE.md (org-level) | | "Always run prettier after editing" | Hook — use claude-code-hook-development skill | | "Never push to main" | Hook — use claude-code-hook-development skill | | "Block rm -rf /" | Hook — use claude-code-hook-development skill |

Use rules for the 90% (guidance). Use hooks for the 10% (guardrails and automation).

CLAUDE.md Structure

Keep instructions specific and actionable:

# Project Instructions

## Build & Test
- Run tests: `npm test`
- Lint: `npm run lint`
- Build: `npm run build`

## Code Style
- Use 2-space indentation
- Prefer named exports over default exports
- All API endpoints must validate input

## Architecture
- API routes in src/api/, business logic in src/services/
- Database queries only in src/db/ — never in route handlers

Tips:

• "Use 2-space indentation" beats "Format code properly"
• Format each instruction as a bullet point
• Group related instructions under descriptive headings
• Review periodically as the project evolves

Modular Rules (.claude/rules/)

For larger projects, split instructions into focused files instead of one large CLAUDE.md:

.claude/rules/
├── code-style.md       # Formatting and naming
├── testing.md          # Test conventions
├── security.md         # Security requirements
└── frontend/
    ├── react.md        # React patterns
    └── styles.md       # CSS conventions

All .md files are discovered recursively and loaded as project memory.

Path-Scoped Rules

Scope rules to specific files using paths frontmatter:

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

# API Rules

- All endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Rules without paths apply to all files.

Glob Patterns

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

CLAUDE.md Imports

Import files with @path/to/file syntax:

See @README for project overview and @package.json for available npm commands.

# Git Workflow
- @docs/git-instructions.md

Relative paths resolve relative to the importing file. Max depth: 5 hops.

For personal instructions shared across worktrees:

# My Preferences
- @~/.claude/my-project-instructions.md

Bootstrapping

Run /init to generate an initial CLAUDE.md for your project. Then refine it.

Run /memory to open any memory file in your editor, toggle auto memory, or see what's loaded.

Attribution

Based on Claude Code Memory Documentation.