/claude-md-overhaul — Tier-by-tier audit + improvement of the Claude Code memory layer

Companion to /maintain (which covers MCP/sync/tool-usage health). This skill focuses on the content + structure of CLAUDE.md and MEMORY.md.

When to use

• CLAUDE.md feels bloated or stale; specific entries are obviously wrong (skills that don't exist, machines that moved, JIRA-style references after migration)
• Old memories aren't surfacing at session start — MEMORY.md is probably past the 25 KB / 200-line auto-load cap and you only see the recent ~30 entries
• You added projects but never wrote memory files for them
• After a multi-machine migration, you suspect Syncthing has sync-conflict files in ~/.claude/
• Periodic hygiene: roughly monthly, or after a heavy session of new skill/project shipping

When NOT to use

• Anthropic config issues (use /maintain)
• Pure MCP health (use /maintain or /raven-mcp-doctor)
• Single-fix triage (just edit the file directly)

Anthropic's documented caps (the targets)

Source: code.claude.com/docs/en/memory

Procedure

Follow tier-by-tier. After each tier, verify caps + offer the next.

Tier 0 — Survey current state (run first, no edits)

# Sizes vs caps
for f in ~/.claude/CLAUDE.md ~/CLAUDE.md; do
  [ -f "$f" ] && printf "%-32s  %4d lines  %5d bytes\n" "$f" "$(wc -l < $f)" "$(wc -c < $f)"
done

# MEMORY.md (the auto-load file)
mem=~/.claude/projects/$(pwd | sed 's|/|-|g')/memory/MEMORY.md
[ -f "$mem" ] && wc -lc "$mem"

# Sync conflicts in the Syncthing-managed area
ls ~/.claude/*.sync-conflict-* 2>/dev/null
ls ~/.claude/settings.sync-conflict-*.json 2>/dev/null

# Active projects on disk
find ~/projects -maxdepth 1 -type d -mtime -14 | wc -l

# Project memory file coverage
ls ~/.claude/projects/-home-*/memory/project_*.md 2>/dev/null | wc -l

Produce a ranked findings table:

Tier 1A — Syncthing exclusions

If ~/.claude/.sync-conflict- files exist, they signal .stignore is missing entries. Add settings.local.json, settings.sync-conflict-*.json, and any other per-machine files. Archive the conflict files to ~/.claude/backups/ (don't delete blindly — sometimes the conflict contains the canonical version from another machine).

Tier 1B — CLAUDE.md surgical fixes

Read the file. For each section:

• Are skill references real? ls ~/.claude/skills/<name> for each /skill-name mention
• Are there duplicated tables across global and machine CLAUDE.md? Slim the global to a summary; keep machine as authoritative
• Are there sections that already exist as skills (/unwoke, /distill, etc.)? Collapse to a one-line pointer
• Add a Project Portfolio section if missing — categorize active projects into families (employer / personal / clients / tools)
• Add operational rules that have bitten you (e.g., per-organization git email, push targets, identity-routing)

Target: under 150 lines after the trim. If you must go over, stay under 200 lines.

Tier 2A — Skill overrides

Audit installed skills. Look for:

• Wrong-platform skills (e.g., pc-ops on Linux/macOS only) → "off"
• Obviously stale (boot.dev course skills if course is done, MBA skills if MBA is done) → "off"
• Occasional-use (deploy-* family) → "name-only" (still invocable, drops description bloat)

Add skillOverrides to ~/.claude/settings.local.json:

{
  "skillOverrides": {
    "pc-ops": "off",
    "tweet": "name-only"
  }
}

Values per Anthropic docs: on / name-only / user-invocable-only / off.

Tier 2B — CURRENT.md this-week focus

Create ~/.claude/CURRENT.md (machine-local — add to ~/.claude/.stignore). Format:

# CURRENT — Week of YYYY-MM-DD

## Hot (touched this week, active push)
- {project} — {one-line state + heat}

## Warm (touched in last month, can pick up)
- ...

## Blocked / on hold
- ...

## This-week intent (what gets prioritized)
1. ...

## Refresh discipline
Update when projects move hot↔warm↔blocked; weekly if untouched.

Wire it as a SessionStart hook in settings.local.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [{
          "type": "command",
          "command": "[ -f ~/.claude/CURRENT.md ] && cat ~/.claude/CURRENT.md || true",
          "timeout": 5
        }]
      },
      { "matcher": "resume", "hooks": [/* same */] }
    ]
  }
}

Tier 3 — MEMORY.md prune

If MEMORY.md is past 25 KB or 200 lines, 80% of memory is invisible at session start. This is the biggest single fix in this entire workflow.

Discipline:

• MEMORY.md is an index, not a content store
• One line per entry, under ~150 chars: - [topic](file.md) — pithy hook (load-bearing fact)
• Detail lives in topic files (feedback.md, project.md, reference_*.md)
• Group by month: ## 2026-05, ## 2026-04, etc.
• Collapse "References / Feedback / Dormant Projects" sections to load-on-demand pointers when they grow long

For mechanical bulk transformation, dispatch a subagent — read MEMORY.md, for each ## entry:

1. Extract title + date
2. Find the linked topic file ([name](name.md))
3. Verify topic file has the body; if not, append before collapsing
4. If no topic file exists for an entry with substantive body, create one
5. Replace the entry with a single index line

Target: under 200 lines AND under 25 KB. Check after each operation. If you're at the cap, look for the heaviest individual entries (awk '{print length($0), NR}' MEMORY.md | sort -rn | head) and either trim hooks or collapse list-style entries to load-on-demand sentences.

Tier 4 — Fill memory gaps (active-project stubs)

# Find active projects (touched in last 14 days) that lack a memory file
mem=~/.claude/projects/$(pwd | sed 's|/|-|g')/memory
for d in ~/projects/*/; do
  name=$(basename "$d")
  mtime=$(find "$d" -type f -mtime -14 -not -path '*/.git/*' -not -path '*/node_modules/*' | head -1)
  [ -z "$mtime" ] && continue
  norm=$(echo "$name" | tr '-' '_')
  if ! grep -rli "\b$name\b\|\b$norm\b" "$mem"/*.md >/dev/null 2>&1; then
    echo "GAP: $name"
  fi
done

For each gap, create a one-paragraph stub project_<name>.md:

---
name: project-<name>
description: One-line description of what this project is + where it lives + current status.
metadata:
  type: project
---

# <name>

**Location**: `~/projects/<name>/` on <machine>.

**What it is**: <short>

**Stack**: <stack>

**Status**: <one line on activity>

**Companions**: <related projects/skills>

Add a single line referencing all new stubs to MEMORY.md's "Active projects" paragraph (don't add 11 separate ## entries — that blows the cap).

Tier 5 — Per-project CLAUDE.md (high-traffic repos only)

For each repo touched ≥10 times in the last month with a multi-area structure (apps/, packages/, src/, or distinct frontend/backend/infra), check whether the repo has a CLAUDE.md:

for d in ~/projects/*/; do
  if [ -d "$d/apps" ] || [ -d "$d/packages" ]; then
    has=$([ -f "$d/CLAUDE.md" ] && echo "HAS" || echo "MISSING")
    echo "$has  $(basename $d)"
  fi
done

For "MISSING" results, write a 50-100-line CLAUDE.md covering: purpose, stack + scripts, key files, hard rules (load-bearing — the ones that bit you before), conventions, anti-patterns.

Tier 6 — Path-scoped rules (.claude/rules/)

For repos with 5+ distinct areas, write rule files with paths: frontmatter so they load only when editing matching files:

---
paths:
  - "packages/auth/**"
  - "apps/*/middleware.{ts,js,mjs}"
---

# Auth rules

- Source of truth: `@<scope>/auth` only
- ...

Three starter rule files cover most cases: auth.md, db.md, frontend.md. Add infra.md if Docker/k8s.

For joint repos (you don't own alone), put .claude/rules/ in .gitignore — your rules are personal, not team.

User-level rules at ~/.claude/rules/ apply across every project on the machine. Good candidates: typescript-conventions.md, python-conventions.md, shell-safety.md, markdown-discipline.md.

Quality criteria

A successful overhaul leaves you with:

• CLAUDE.md under 200 lines (sweet spot 80–150)
• MEMORY.md under 200 lines AND 25 KB
• No sync-conflict files in ~/.claude/
• Every active project (touched in last 14 days) has a memory file
• Every high-traffic multi-area repo has its own CLAUDE.md
• At least one path-scoped rule directory exists for monorepos
• CURRENT.md exists and is dated this week
• At least one SessionStart hook loads context automatically

Anti-patterns

• Bloated MEMORY.md entries with full paragraph bodies — bodies belong in topic files; MEMORY.md is the index. One line per entry.
• Adding entries without checking cap first — every addition risks pushing older entries past the 25 KB / 200-line cutoff, silently shrinking what loads at session start.
• Per-app CLAUDE.md in monorepos with divergent teams — fragments context. Use .claude/rules/ with paths: scoping instead.
• @-imports as a token-saving tactic — imports expand inline; they organize but don't compress. Use the "Documentation (read on demand)" linked-list pattern instead for true on-demand loading.
• Committing personal .claude/rules/ to joint repos — gitignore them. Your operator notes are not team conventions.
• Auto-pushing skill repos without secret-scanning first — grep for tokens, channel IDs, credentials before pushing public.
• Declaring a hook "live" mid-session — Claude Code reads hook config at session start, not per-tool-call. Verify activation via failure-case reproduction in a fresh session.

Mid-session config gotcha

If you install a hook or change settings during this overhaul, the running session won't see it. The change is on disk but the loader is cold. To verify a hook actually works:

1. Close the current Claude Code session
2. Start a fresh one
3. Run the command that should trigger the hook
4. Observe state change (or its absence)

If the hook isn't firing in the fresh session, it's broken; if it fires, you're good for all future sessions.

Companion skills + memories

• /maintain — MCP/sync/tool-usage health (complementary)
• /distill — promotes session patterns into new skills
• /absorb — distills session knowledge into memory files (deeper than the stubs created here)
• /pickup — entry ritual for new sessions; reads HANDOFF.md or infers from git
• ~/.claude/CLAUDE.md — apply trim rules from Tier 1B here

Origin

Distilled 2026-05-16 from a session that ran the full audit-improve loop end-to-end:

• Global CLAUDE.md: 164 → 177 lines (after Project Portfolio + Vibe Engineer additions; trimmed Multi-Machine + Athanor + Unwoke first)
• MEMORY.md: 772 → 162 lines / 134 KB → 25.6 KB (5.4× over → under both caps)
• 11 active projects lacking memory files → 11 new stubs
• 13 path-scoped rule files across 4 scopes (user + 3 monorepos)
• 1 settings.local.json sync-conflict resolved
• 1 SessionStart hook + 1 PreToolUse hook installed
• 4 git commits across 4 repos; 2 PRs pushed to a team org
• Mid-session config-hot-reload gotcha discovered + memorialized

The full session summary is at ~/.claude/projects/-home-ormus/sessions/2026-05-16-claude-md-overhaul.md.

The discipline that emerged: measure → propose tier'd → execute with cap-fitting verification at each step → never declare a config "live" without reproducing the failure case it's meant to fix.