Reference documentation for Claude Code memory management -- CLAUDE.md files, auto memory, memory hierarchy, project rules (.claude/rules/), modular rules with path-specific scoping, CLAUDE.local.md, /memory command, /init command, imports with @path syntax, organization-level managed policy, and memory best practices.
This skill provides the complete official documentation for Claude Code's memory systems — CLAUDE.md files, auto memory, .claude/rules/, and the full .claude directory layout.
| | CLAUDE.md files | Auto memory | | :--- | :--- | :--- | | Who writes it | You | Claude | | What it contains | Instructions and rules | Learnings and patterns | | Scope | Project, user, or org | Per repository, shared across worktrees | | Loaded into | Every session | Every session (first 200 lines or 25KB of MEMORY.md) | | Use for | Coding standards, workflows, project architecture | Build commands, debugging insights, preferences Claude discovers |
| Scope | Location | Shared with |
| :--- | :--- | :--- |
| Managed policy | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Linux/WSL: /etc/claude-code/CLAUDE.md; Windows: C:\Program Files\ClaudeCode\CLAUDE.md | All users in organization (cannot be excluded) |
| User instructions | ~/.claude/CLAUDE.md | Just you (all projects) |
| Project instructions | ./CLAUDE.md or ./.claude/CLAUDE.md | Team members via source control |
| Local instructions | ./CLAUDE.local.md | Just you (current project; add to .gitignore) |
CLAUDE.local.md appended after CLAUDE.md at each level<!-- notes -->) are stripped before injection — use for maintainer notes without spending tokens@path/to/file syntax (relative or absolute, max 4 hops deep); wrap in backticks to prevent importingclaudeMdExcludes setting skips specific files by path/glob (merged across settings layers; managed policy files cannot be excluded)CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 + --add-dir also loads CLAUDE.md from extra directoriesPlace .md files in .claude/rules/ (discovered recursively). Two loading modes:
| Rule type | Frontmatter | When it loads |
| :--- | :--- | :--- |
| Unconditional | No paths: field | Every session, same priority as .claude/CLAUDE.md |
| Path-scoped | paths: YAML list | When Claude reads a file matching any listed glob |
Path glob examples: **/*.ts (all TypeScript), src/**/* (all under src/), src/components/*.tsx (specific directory). Brace expansion works: src/**/*.{ts,tsx}. Supports symlinks (circular symlinks detected gracefully). User-level rules at ~/.claude/rules/ apply to every project; project rules take higher priority.
/memory in session, or autoMemoryEnabled: false in settings, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1~/.claude/projects/<project>/memory/ (keyed by git repo root; all worktrees share one directory)autoMemoryDirectory setting (absolute path or ~/-prefixed; honored after workspace trust dialog for project settings)Auto memory directory layout:
~/.claude/projects/<project>/memory/
├── MEMORY.md # Index — first 200 lines or 25KB loaded each session
├── debugging.md # Topic files — read on demand by Claude, not at startup
└── api-conventions.md
MEMORY.md acts as an index; Claude moves detailed notes to topic files when it grows large/memory to browse, open files, and toggle auto memory on/offSubagents can maintain their own memory. Set memory: frontmatter in the agent definition:
| Value | Storage location | Shared |
| :--- | :--- | :--- |
| project | .claude/agent-memory/<agent-name>/ | With team (committed) |
| local | .claude/agent-memory-local/<agent-name>/ | Local only |
| user | ~/.claude/agent-memory/<agent-name>/ | Across all your projects |
/memory lists all CLAUDE.md, CLAUDE.local.md, and rules files loaded in the current session, provides a link to the auto memory folder, lets you toggle auto memory, and opens any file in your editor.
| Symptom | Fix |
| :--- | :--- |
| Claude ignores CLAUDE.md | Run /memory to verify the file is listed; check location is in the load path; make instructions more specific; look for conflicting rules |
| Instructions need guaranteed execution | Use a hook instead — hooks enforce behavior regardless of Claude's decisions |
| Don't know what auto memory saved | Run /memory and open the auto memory folder |
| CLAUDE.md too large | Use path-scoped rules; split content; note that @path imports still load at launch |
| Instructions lost after /compact | Project-root CLAUDE.md re-injected after compact; nested CLAUDE.md files reload next time Claude reads files in that subdirectory |
| You want to | Edit | Reference |
| :--- | :--- | :--- |
| Give Claude project context and conventions | CLAUDE.md | Memory |
| Topic-scoped instructions, optionally path-gated | .claude/rules/*.md | Rules |
| Allow or block specific tool calls | .claude/settings.json permissions | Permissions |
| Run scripts at lifecycle events | .claude/settings.json hooks | Hooks |
| Keep personal overrides out of git | .claude/settings.local.json | Settings scopes |
| Add a reusable prompt invoked with /name | .claude/skills/<name>/SKILL.md | Skills |
| Define a specialized subagent | .claude/agents/*.md | Subagents |
| Orchestrate subagents from a script | .claude/workflows/*.js | Dynamic workflows |
| Connect external tools over MCP | .mcp.json | MCP |
| Change Claude's response format | .claude/output-styles/*.md | Output styles |
Auto-cleaned after cleanupPeriodDays (default 30) days on startup:
~/.claude/projects/<project>/<session>.jsonl — full transcripts~/.claude/file-history/ — pre-edit file snapshots (checkpoint restore)~/.claude/plans/, ~/.claude/debug/, ~/.claude/paste-cache/, etc.Kept indefinitely (delete manually if needed):
~/.claude/history.jsonl — prompt history (up-arrow recall)~/.claude/stats-cache.json — token/cost totals for /usageRun claude project purge <path> (v2.1.124+) to delete all state for one project. Use --dry-run to preview, --yes to skip confirmation, --all to purge all projects.
For the complete official documentation, see the reference files:
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer