Context Manager

Manage the Claude Code memory hierarchy and audit the full markdown landscape of a project. Produces well-organised memory files, detects documentation overlap, and reports the total context footprint.

Four Context Layers

Layer Location Purpose What this skill does

Memory ./CLAUDE.md , subdirs, .claude/rules/*.md

Project context, commands, architecture, rules Audit, score, maintain

Project docs ARCHITECTURE.md , DATABASE_SCHEMA.md , API_ENDPOINTS.md , docs/**/*.md

Technical documentation Check existence per project type, flag staleness, detect CLAUDE.md overlap

Session SESSION.md , PROJECT_BRIEF.md

Temporary progress tracking Report presence + size (managed by dev-session)

Public README.md , CONTRIBUTING.md , other root .md

Public-facing docs Detect CLAUDE.md duplication

Auto-memory (~/.claude/projects/*/memory/MEMORY.md ) is also scanned for awareness but managed by Claude automatically.

Operating Modes

Mode 1: Session Capture

When: End of session, "capture learnings", "update CLAUDE.md with what we learned"

• 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

• Categorise each discovery using the placement decision tree below

• Draft all changes as diffs in a single batch

• Present the batch — apply after a single yes/no confirmation

Keep it concise: one line per concept. No verbose explanations, no generic advice.

Mode 2: Full Audit

When: "audit context", "audit memory", "check project docs", periodic maintenance, working in a neglected project

• Run the audit script: python3 plugins/dev-tools/skills/context-manager/scripts/audit_memory.py [repo-path]

• Review the output:

• Memory layer: CLAUDE.md sizes, quality scores, rules file sizes

• Project docs: existence, staleness, overlap with CLAUDE.md

• Session/public: presence and size

• Markdown footprint: total KB by layer

• Overlap warnings: sections duplicated between files

• Generate changes autonomously — create, update, or flag files as needed

• Present all changes as a single batch for approval

• Apply approved changes

• Check if the commit capture hook is installed — if not, offer to set it up (see references/commit-hook.md)

For large repos, delegate to a sub-agent:

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

Mode 3: Restructure

When: "restructure memory", root CLAUDE.md over 200 lines, first-time memory setup

• Run full audit (Mode 2) first

• 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

• Move detailed technical content from CLAUDE.md to docs/ or ARCHITECTURE.md if it's reference material, not operational context

• Resolve overlaps: if CLAUDE.md duplicates ARCHITECTURE.md or docs/, remove the duplication

• Create missing documentation files based on project type

• 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 → Is it reference documentation or operational context? ├── Reference → ARCHITECTURE.md or docs/ │ (system design, schemas, detailed flows) └── Operational → ./CLAUDE.md (project root) (identity, stack, commands, critical rules)

Size Targets

File Type Target Maximum

Root CLAUDE.md 50-150 lines 200

Sub-directory CLAUDE.md 15-50 lines 80

Rules topic file 20-80 lines 120

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

Don't create when: parent covers it, directory is self-explanatory, content would be under 10 lines.

.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

docs/ and ARCHITECTURE.md

• Detailed system architecture (component diagrams, data flows)

• Database schemas and migration guides

• API endpoint catalogues

• Content that Claude should read on demand, not every session

Rule of thumb: If it's needed every session, put it in CLAUDE.md. If it's reference material consulted occasionally, put it in docs/.

What to delete

• Content Claude already knows from training

• Verbose explanations of standard frameworks

• Changelogs or version history (use git)

• Duplicated content (between CLAUDE.md and docs/, ARCHITECTURE.md, or README.md)

• "TODO" items that were never completed

• Generic advice not specific to the project

Project Type Detection

The audit script detects project type from file presence and suggests appropriate documentation:

Indicator Type Suggested Docs

wrangler.jsonc / wrangler.toml

Cloudflare Worker ARCHITECTURE.md

vite.config.*

• .tsx files Vite/React ARCHITECTURE.md

next.config.*

Next.js ARCHITECTURE.md

MCP patterns in src/index.ts

MCP Server ARCHITECTURE.md, API_ENDPOINTS.md

src/routes/ or src/api/

API Project API_ENDPOINTS.md, DATABASE_SCHEMA.md

Drizzle/Prisma config Database DATABASE_SCHEMA.md

All projects get CLAUDE.md. Additional docs only when the project type warrants them. See references/project-types.md for full detection heuristics and doc templates.

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

The audit script scores each CLAUDE.md on 6 criteria (100 points):

Criterion Points What it measures

Commands/Workflows 20 Build, test, deploy documented

Architecture Clarity 20 Structure, relationships, entry points

Non-Obvious Patterns 15 Gotchas, quirks, warnings

Conciseness 15 Dense content, no filler

Currency 15 References valid, commands work

Actionability 15 Copy-paste ready, real paths

See references/quality-criteria.md for the full rubric.

Reference Files

When Read

Scoring CLAUDE.md quality references/quality-criteria.md

Detecting project type and expected docs references/project-types.md

Creating new CLAUDE.md or rules files references/templates.md

Setting up automatic capture on commit references/commit-hook.md

Scripts

• scripts/audit_memory.py — Scan all four layers, score quality, detect project type, report footprint and overlap

• python3 audit_memory.py [repo-path] — human-readable report

• python3 audit_memory.py [repo-path] --json — structured JSON output