Memory Manager

Three Memory Layers

./CLAUDE.md

.claude/rules/*.md

~/.claude/projects/*/memory/MEMORY.md

Operating Modes

Mode 1: Session Capture

1. Review the conversation for discoveries worth preserving:
   • Commands that worked (or didn't)
   • Gotchas and workarounds found
   • Architecture decisions made
   • Configuration quirks discovered
   • Patterns that would help future sessions
2. Categorise each discovery using the placement decision tree below
3. Draft all changes as diffs in a single batch
4. Present the batch — apply after a single yes/no confirmation

Mode 2: Full Audit

1. Run the audit script:
   bash

   python3 skills/memory-manager/scripts/audit_memory.py [repo-path]

2. Review the output: sizes, quality scores, project type, missing docs, stale references
3. Generate changes autonomously — create, update, or flag files as needed
4. Present all changes as a single batch for approval
5. Apply approved changes

Task(subagent_type: "general-purpose",
  prompt: "Run python3 skills/memory-manager/scripts/audit_memory.py /path/to/repo
           and summarise the findings.")

Mode 3: Restructure

1. Run full audit (Mode 2) first
2. Split oversized files:
   • Extract topic sections from root CLAUDE.md into

     .claude/rules/<topic>.md

   • Extract directory-specific content into sub-directory CLAUDE.md files
3. Create missing documentation files based on project type
4. Present the restructure plan, apply after approval

Placement Decision Tree

Would this still apply if I switched to a completely different project?
├── YES → ~/.claude/rules/<topic>.md
│         (correction rules, API patterns, coding standards)
└── NO  → Is it specific to a subdirectory?
    ├── YES → <dir>/CLAUDE.md
    │         (integrations, directory-specific gotchas)
    └── NO  → ./CLAUDE.md (project root)
              (identity, stack, commands, architecture, critical rules)

Size Targets

What Belongs Where

Root CLAUDE.md

• Project name, purpose, owner
• Tech stack summary
• Build/deploy/test commands (copy-paste ready)
• Directory structure overview
• Critical "never do X" rules
• Key integrations and secrets locations

Sub-directory CLAUDE.md

• External service integrations for that component
• Non-obvious configuration specific to this area
• Directory-specific commands
• Gotchas when working in this directory

.claude/rules/ topic files

• Correction rules bridging training cutoff (e.g. API changes, deprecated patterns)
• Coding patterns and standards
• Platform-specific formatting rules
• Error prevention patterns

What to delete

• Content Claude already knows from training
• Verbose explanations of standard frameworks
• Changelogs or version history (use git)
• Duplicated content from parent CLAUDE.md files
• "TODO" items that were never completed
• Generic advice not specific to the project

Project Type Detection

wrangler.jsonc

wrangler.toml

vite.config.*

.tsx

next.config.*

src/index.ts

src/routes/

src/api/

Autonomy Rules

• Just do it: Run audit, detect project type, identify gaps, draft changes
• Brief confirmation: Apply changes (single batch yes/no, not item-by-item)
• Ask first: Delete existing content, major restructures (moving 50+ lines), create new project docs from scratch where there's ambiguity about content

Quality Scoring

Reference Files

Scripts

• scripts/audit_memory.py

  — Scan all three layers, score quality, detect project type, flag issues

  • python3 audit_memory.py [repo-path]

    — human-readable report

  • python3 audit_memory.py [repo-path] --json

    — structured JSON output