Memory Defragmenter
Clean, merge, and optimize memory files to keep them lean and effective.
Purpose
Memory files grow over time and become:
- Bloated with duplicates
- Stale with outdated info
- Scattered across tiers
- Inconsistent in format
This skill defragments them.
When to Run
| Trigger | Action |
|---|---|
| Weekly maintenance | Full defragment |
| Before context optimization | Clean first |
| After many sessions | Remove stale entries |
| Explicit request | Clean specified files |
Defragmentation Workflow
Step 1: Analyze Memory State
python3 scripts/analyze_memory.py
Reports:
- Files analyzed and sizes
- Duplicate detection
- Stale entry detection (30+ days old)
- Tier distribution
- Formatting consistency
Step 2: Generate Defragmentation Plan
python3 scripts/defragment.py --plan
Creates defragment-plan.md with:
- Entries to merge
- Entries to archive
- Entries to delete
- Entries to promote/demote
Step 3: Review Plan
Read the plan and approve/modify before execution.
Step 4: Execute Defragmentation
python3 scripts/defragment.py --execute
Backs up original files first, then:
- Merges duplicate entries
- Archives stale content to
archive/ - Promotes hot entries to HOT tier
- Demotes cold entries to archive
- Normalizes formatting
Step 5: Verify
python3 scripts/verify_memory.py
Checks:
- All files readable
- No broken links
- Consistent formatting
- Tier limits respected
Memory Tiers Reference
| Tier | Location | Max Size | Age Policy |
|---|---|---|---|
| HOT | memory.md, ~/self-improving/memory.md |
≤100 lines each | Review monthly |
| WARM | memory/*.md, ~/self-improving/domains/ |
≤200 lines each | Review quarterly |
| COLD | archive/ |
Unlimited | Archive at 90 days |
Safety Rules
- Always backup before executing
- Review plan before applying
- Never delete - only archive
- Keep originals for 24h after
- Verify after every defragment
Files
scripts/analyze_memory.py— Analyze memory statescripts/defragment.py— Plan and execute cleanupscripts/verify_memory.py— Verify integrityreferences/rules.md— Defragmentation rules and patterns
