| name | memory-placement |
| description | Use when user says 'remember this', when deciding where to store learnings or context, when about to edit CLAUDE.md or create a skill, or when routing any persistent information. Determines the correct storage destination among CLAUDE.md, auto-memory, rules, skills, and local overrides. |
Memory Placement
Route persistent information to the right destination. The goal is: information is discoverable when needed, without bloating context that's loaded every session.
Hop Cost
Each "hop" (notice a skill → open it → open a referenced doc) adds latency and risk of being missed.
- L0: CLAUDE.md — loaded every session, universal guardrails only
- L1: Skills / rules — loaded when triggered or when files match
- L2+: Referenced docs inside skills — loaded on demand
Promote upward only when a miss proves high-risk or recurs. See mistake-tracking skill for the escalation ladder.
Decision Tree
Who is writing this? (human instruction vs Claude learning)
├── CLAUDE is writing (learned insight, debugging note, architecture discovery)
│ └── Auto-memory: ~/.claude/projects/<project>/memory/
│
└── HUMAN is writing (instruction, preference, rule, workflow)
│
├── Needed MOST sessions + high miss risk?
│ ├── All projects → ~/.claude/CLAUDE.md
│ └── This project → ./CLAUDE.md (checked into git)
│
├── Scoped to specific files/paths?
│ └── .claude/rules/<topic>.md with paths: frontmatter
│ (e.g., only load when touching src/api/**/*.ts)
│
├── Personal preference, not shared with team?
│ ├── All projects → ~/.claude/CLAUDE.md or ~/.claude/rules/
│ └── This project → ./CLAUDE.local.md (auto-gitignored)
│
├── Procedural knowledge triggered by context?
│ └── Skill (.claude/skills/<name>/SKILL.md)
│
├── Third-party API/library docs?
│ └── Don't store — fetch via Context7 or WebFetch at use time
│
└── Historical reference (debugging log, past decisions)?
└── Auto-memory or project logs/
Storage Destinations
| Destination | Path | Loaded | Scope | Who writes |
|---|
| User CLAUDE.md | ~/.claude/CLAUDE.md | Every session | All projects | Human |
| Project CLAUDE.md | ./CLAUDE.md | Every session in this repo | Team (git) | Human |
| Local overrides | ./CLAUDE.local.md | Every session in this repo | Personal (gitignored) | Human |
| User rules | ~/.claude/rules/*.md | Every session | All projects | Human |
| Project rules | ./.claude/rules/*.md | Every session (or path-filtered) | Team (git) | Human |
| Auto-memory | ~/.claude/projects/<project>/memory/ | MEMORY.md index at startup | Per-project, personal | Claude |
| Personal skills | ~/.claude/skills/<name>/SKILL.md | When description matches | All projects | Human |
| Project skills | ./.claude/skills/<name>/SKILL.md | When description matches | Team (git) | Human |
| Canonical skills | ~/.dotfiles/agents/skills/<name>/ | Via symlink to ~/.claude/skills/ | All projects | Human |
Auto-Memory Details
Claude writes to ~/.claude/projects/<project>/memory/ during sessions. Only the first 200 lines of MEMORY.md load at startup — keep it concise and link to topic files for details.
~/.claude/projects/<project>/memory/
├── MEMORY.md # Index (200-line cap at startup)
├── debugging.md # Topic-specific notes
├── patterns.md # Discovered conventions
└── api-notes.md # Integration learnings
Use /memory to view and edit memory files. Auto-memory is the right place for things Claude discovers (not things the user instructs).
Rules with Path Filtering
.claude/rules/*.md files support conditional loading via paths: frontmatter:
---
paths:
- "src/api/**/*.ts"
- "src/**/*.test.ts"
---
# API Testing Rules
- All API endpoints must have integration tests
- Use supertest for HTTP assertions
This rule only loads when Claude is working on files matching those globs. Use this for domain-specific conventions that would be noise elsewhere.
CLAUDE.md Imports
CLAUDE.md files support @path/to/file imports (up to 5 hops deep):
See @README for project overview.
Follow conventions in @docs/coding-standards.md.
Use imports to keep CLAUDE.md lean while making related docs discoverable.
Before Editing CLAUDE.md
Writing Skill Descriptions
Skills trigger based on their description field. Write them to match the contexts where they should fire:
description: "Use when [specific triggering condition]"
Examples:
"Use when about to run git stash or git worktree operations""Use when killing processes on ports or freeing busy ports"
Test: would Claude naturally think to load this in that situation? If the description is too narrow, it won't trigger. Err on the side of "pushy" — undertriggering is the more common failure mode.
Acceptance Checks
