context-maintenance

Context Maintenance

Audits all Claude context sources (memory files, CLAUDE.md, AGENTS.md) against the actual codebase to find and fix stale information. Prevents wrong context from persisting across conversations.

Problem This Solves

Claude loads memory files and AGENTS.md at session start. If these contain outdated information (wrong model IDs, missing services, stale counts), every conversation starts with incorrect assumptions — leading to wrong suggestions, wasted debugging, and repeated mistakes.

When to Use

• Starting a session after >7 days away from the project
• After changing configurations, services, or infrastructure
• After adding/removing features, API routes, or packages
• User asks to check context freshness
• You notice memory says X but code says Y

Checks

Run in parallel where possible. Adapt to the project's structure.

1. Memory Index Health

wc -l MEMORY.md → must be < 100 lines

MEMORY.md should be a concise index with links to topic files — not inline content. If over limit, extract content into topic files.

2. Memory vs Code Drift

For each memory topic file:

• Identify claims about code (model names, file counts, service lists, API configurations)
• Verify against actual code using Grep/Glob
• Flag discrepancies as DRIFT

Common drift sources:

• Service/function/endpoint counts and lists
• Model or library version references
• File paths that were moved or renamed
• Configuration values that changed

3. AGENTS.md Completeness

For each AGENTS.md in the project:

• Compare documented services/features against actual directory listings
• Check counts match reality (e.g., "15 functions" vs ls | wc -l)
• Verify listed tools/models match what code actually uses

4. Stale Topic Files

For each file in memory/:

• Check description field still matches content
• Flag files older than 30 days for review
• Verify no content duplicates what's already in AGENTS.md
• Check "Known Issues" — verify they still exist in code