melodic-software/audit-memory

Audit Memory Command

Audit Claude Code CLAUDE.md memory files for quality, compliance, and organization.

Initialization

Before auditing, initialize the environment:

Get the current UTC date, capture the project root path, ensure the temp directory exists, and clean up stale audit files. The memory-management skill provides authoritative validation guidance (auto-loaded when this command runs).

What Gets Audited

• Import syntax (@path/to/file.md)
• Hierarchy compliance (enterprise > project > user)
• Circular import detection
• Size guidelines and progressive disclosure
• Content organization

Command Arguments

| Argument | Description | | --- | --- | | (none) | Audit all discoverable CLAUDE.md files | | project | Only audit project-level files | | user | Only audit ~/.claude/CLAUDE.md | | all | Audit all scopes explicitly | | --force | Audit regardless of modification status | | --skip-validation | Skip finding validation (faster, but may include false positives) | | --token-budget | Run ONLY token budget analysis (skip full audit) |

Step 1: Discover CLAUDE.md Files

Check root CLAUDE.md, .claude/CLAUDE.md, user ~/.claude/CLAUDE.md (Unix) or %USERPROFILE%\.claude\CLAUDE.md (Windows), and .claude/memory/*.md.

Build list with scope and level (root/dot-claude/memory/user).

Step 2: Parse Arguments

Parse scope selector and --force flag. Filter files to match requested scope.

Step 3: Present Audit Plan

Display mode, files discovered, primary files, and imported memory files.

Step 4: Execute Audits

For each file, spawn the memory-component-auditor subagent with scope, level, path, and last audit date. Run in parallel batches of 3-5.

After individual audits, perform cross-file circular import detection by building an import graph.

Subagents write findings to .claude/temp/. The main conversation thread collects results and updates audit logs using its Write/Edit tools.

Step 4.5: Validate Findings

Unless --skip-validation flag is present:

1. Spawn the audit-finding-validator agent with:
   • project_root: The captured project root path
   • audit_type: "memory"
   • audit_files: List of .claude/temp/audit-*-memory-*.json file paths
2. Wait for validation to complete
3. Read updated JSON files with validation results
4. Filter out FALSE_POSITIVE findings completely before aggregation
5. Note: Filtered findings are logged to .claude/temp/audit-filtered-findings.json

If --skip-validation flag is present:

• Skip validation phase entirely (current speed preserved)
• Present all findings without filtering
• Note in summary: "Validation: Skipped"

Step 5: Final Summary

Report total audited by scope, results, circular import check, and details tables. Provide remediation steps for issues.

Include validation statistics (if validation was performed):

• Validation performed: Yes/No
• Findings validated: X
• False positives filtered: Y
• Verified findings: Z
• Unverified findings: W

Step 6: Token Budget Analysis (included by default)

Scope: Only always-loaded files (root CLAUDE.md + files with @-prefix imports marked as "Always-loaded")

Note: Use --token-budget to run ONLY this step (skips Steps 1-5 full audit).

6.1 Fetch Official Guidance

Invoke memory-management skill (which delegates to docs-management) to fetch current official guidance on memory file sizing. Official docs recommend keeping memory "concise and focused" with progressive disclosure - specific token thresholds are repo-specific standards, not official requirements.

6.2 Calculate Tokens Per File

For each always-loaded file:

1. Read file content
2. Estimate tokens: len(content) / 4 (approximate for English markdown)
3. Extract declared Token Budget from header if present (e.g., **Token Budget:** ~1,800 tokens)
4. Record file path, actual tokens, declared budget

6.3 Calculate Aggregate Total

Sum all always-loaded file tokens. Do NOT include on-demand files (those without @ prefix in root, or marked "Context-Dependent").

6.4 Evaluate Against Repo-Specific Thresholds

These thresholds are repo-specific standards (see audit-framework.md), NOT from official Claude Code docs:

| Status | Token Range | Guidance | | --- | --- | --- | | PASS | ≤12k tokens | Within repo budget | | WARN | 12k-15k tokens | At upper limit, monitor | | FAIL | >15k tokens | Over budget, remediation needed |

6.5 Generate Report

Report includes:

1. Top 5 largest files by token count with percentage of total
2. Aggregate total vs repo-specific budget
3. Declared vs actual variance for files where declared budget differs from actual by >20%
4. Status (PASS/WARN/FAIL) based on aggregate total

6.6 Suggest Remediation (if FAIL or WARN)

If over budget, recommend:

• Files that could move to on-demand loading (not critical for every session)
• Large files (>2k tokens) that could be split using hub pattern
• Reference progressive disclosure guidance from official docs (via memory-management skill)

6.7 Update Audit Log

Add Token Budget Analysis section to .claude/audit/memory.md with:

• Status and analysis date
• Metrics table (total, budget, variance)
• Top 5 largest files table
• Declared vs actual variance table (if any discrepancies)

Important Notes

Import Syntax

Valid: @path/to/file.md (e.g., @.claude/memory/workflows.md)

Hierarchy Compliance

1. Enterprise (highest precedence)
2. Project root (CLAUDE.md)
3. Project dot-claude (.claude/CLAUDE.md)
4. User (~/.claude/CLAUDE.md - lowest)

Size Guidelines

| File Type | Recommended Size | | --- | --- | | Root CLAUDE.md | < 50 lines core + imports | | Memory imports | < 500 lines each |

Cross-Platform Paths

| Platform | User Memory | | --- | --- | | Unix | ~/.claude/CLAUDE.md | | Windows | %USERPROFILE%\.claude\CLAUDE.md |

Audit Log Location

All audit results are written to .claude/audit/memory.md.

Use /audit-log memory to view current audit status.

Example Usage

Example 1: Audit All Memory Files

User: /audit-memory

Claude: Discovering CLAUDE.md files...

## Audit Plan
**Mode**: SMART
**Files discovered**: 12

### Primary Files:
1. [project:root] CLAUDE.md
2. [user] ~/.claude/CLAUDE.md

### Imported Files:
3. [project:memory] .claude/memory/workflows.md
...

[Spawns memory-component-auditor subagents]

## Audit Complete
**Circular Import Check**: ✓ No cycles detected

| Scope | File | Result | Score |
| --- | --- | --- | --- |
| project | CLAUDE.md | PASS | 100/100 |

Example 2: Audit Project Only

User: /audit-memory project
Claude: Auditing project-level files...