Skip to main content
Generalmelodic-software

audit-memory

Audit Claude Code CLAUDE.md memory files for quality, compliance, and organization. Use to validate import syntax, detect circular imports, and check hierarchy compliance.

Stars
74
Source
melodic-software/claude-code-plugins
Updated
2026-04-07
Slug
melodic-software--claude-code-plugins--audit-memory
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/melodic-software/claude-code-plugins/HEAD/plugins/claude-ecosystem/skills/audit-memory/SKILL.md -o .claude/skills/audit-memory.md

Drops the SKILL.md into .claude/skills/audit-memory.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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...