- name
- memory-defragmenter
- description
- Defragment and optimize agent memory files by cleaning duplicates, merging similar entries, archiving stale content, and ensuring proper tiering. Use when: (1) memory files feel cluttered or bloated; (2) before or after context optimization; (3) weekly memory maintenance; (4) when explicitly asked to clean, defragment, or optimize memory.
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.pyReports:
- 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 --planCreates 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 --executeBacks 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.pyChecks:
- 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