claude-code-memory-and-rules

What this skill does

# 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](./references/memory-types.md) - All memory locations, scopes, and precedence
- [Rules Guide](./references/rules-guide.md) - Modular `.claude/rules/` with path scoping
- [Auto Memory](./references/auto-memory.md) - Claude's self-managed memory system
- [Examples](./references/examples.md) - 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:

```markdown
# 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:

```yaml
---
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:

```markdown
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:

```markdown
# 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](https://code.claude.com/docs/en/memory).