/memory-audit

Audit Claude Code memory hierarchy for a project. Shows what files load at session start, total context budget, and optimization hints.

Context

Claude Code loads memory files at session start in this order:

1. Managed policy (/Library/Application Support/ClaudeCode/CLAUDE.md)
2. User memory (~/.claude/CLAUDE.md)
3. User rules (~/.claude/rules/*.md)
4. Auto-memory (~/.claude/projects/{key}/memory/MEMORY.md, first 200 lines)
5. Project hierarchy (walk from / to CWD: CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md)
6. Local overrides (CLAUDE.local.md at each level)

Rules with paths: frontmatter are conditional — loaded only when working on matching files. Rules without paths: always load and consume context budget.

Target: keep startup context under 40k chars. Large CLAUDE.md files should extract domain-specific sections into conditional .claude/rules/*.md files.

Steps

1. Determine target. Parse $ARGUMENTS:

   • Empty or . -> use CWD
   • Path -> use that path
   • all -> scan CWD subdirectories that have CLAUDE.md

2. Run memory_map.py. Execute:

   uv run python ${CLAUDE_PLUGIN_ROOT}/scripts/memory_map.py <path> --audit
   

   If all argument, add --all-projects flag instead of path.

   If uv is not available, fall back to:

   python ${CLAUDE_PLUGIN_ROOT}/scripts/memory_map.py <path> --audit --plain
   

3. Analyze the output. Read the tree display and audit hints table. Key metrics:

   • Total startup chars — should be under 40k
   • Large files (>300 lines) — candidates for splitting into rules
   • Unconditional rules (>30 lines, no paths: frontmatter) — add paths: to make conditional
   • Duplicate sections — same ## Header in multiple files, extract to one place
   • Missing auto-memory — project doesn't learn across sessions

4. Generate recommendations. Based on audit hints, suggest concrete actions:

   Issue	Action
   File > 300 lines	Extract domain sections to .claude/rules/{topic}.md with paths: frontmatter
   Total > 40k chars	Identify largest files, move conditional content to rules
   Unconditional rule > 30 lines	Add paths: frontmatter targeting relevant source files
   Duplicate sections	Keep in the highest-level file, remove from children
   No auto-memory	Normal for new projects, just informational
   User-level rule is project-specific	Move from ~/.claude/rules/ to project's .claude/rules/
   Generic rule in project	Move up to ~/.claude/rules/ or parent CLAUDE.md

5. Check hierarchy health. For the target project:

   • Verify parent CLAUDE.md files exist (inheritance chain intact)
   • Check that project CLAUDE.md has essential sections (structure, commands, stack)
   • Verify .claude/rules/ files have valid paths: frontmatter syntax

6. Output report:

   ## Memory Audit Report
   
   **Project:** [path]
   **Startup context:** X files, ~Y chars (Z% of 40k budget)
   
   ### Tree
   [paste tree output from memory_map.py]
   
   ### Issues Found
   [from audit hints]
   
   ### Recommendations
   1. [specific action with file path]
   2. [specific action with file path]
   
   ### Hierarchy Health
   - Inheritance chain: [OK / broken at level X]
   - Auto-memory: [present / missing]
   - Rules: X total (Y conditional, Z always-on)
   

Rules Frontmatter Reference

Conditional rules load only when the agent works on files matching the glob pattern:

---
paths:
  - "src/lib/analytics/**"
  - "src/app/api/analytics/**"
---
# Analytics Module
...content only loaded when working on analytics files...

Without paths:, the rule always loads and consumes context budget.