Memory Defrag
- 312 installs
- 3.6k repo stars
- Updated August 5, 2026
- basicmachines-co/basic-memory
memory-defrag is a Claude skill that reorganizes agent memory files by splitting bloated files, merging duplicates, pruning stale info, and restructuring the hierarchy.
About
This skill defragments and reorganizes an agent's memory files: splitting bloated files, merging duplicates, removing stale entries, and restructuring the hierarchy. It audits current state, plans changes, executes them one at a time, and logs the result while preserving raw daily notes. A developer runs it periodically or when MEMORY.md grows unwieldy.
- Defragments agent memory files: splits bloated files, merges duplicates, prunes stale info
- Restructures the memory hierarchy and preserves raw daily notes as the audit trail
- Run periodically (weekly) or on demand, or when MEMORY.md exceeds ~500 lines
Memory Defrag by the numbers
- 312 all-time installs (skills.sh)
- Ranked #876 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
memory-defrag capabilities & compatibility
- Capabilities
- memory hygiene · file reorganization · stale pruning
- Use cases
- memory · documentation
What memory-defrag says it does
Reorganize memory files for clarity, efficiency, and relevance. Like filesystem defragmentation but for knowledge.
**Preserve raw daily notes.** Don't delete or modify `memory/YYYY-MM-DD.md` files — they're the audit trail.
npx skills add https://github.com/basicmachines-co/basic-memory --skill memory-defragAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 312 |
|---|---|
| repo stars | ★ 3.6k |
| Last updated | August 5, 2026 |
| Repository | basicmachines-co/basic-memory ↗ |
What it does
Defragment agent memory files by splitting bloated files, merging duplicates, and pruning stale info.
Who is it for?
Cleaning up an agent's MEMORY.md and memory/ files when they grow unwieldy or accumulate redundancy.
Skip if: Curating the knowledge-graph notes/relations themselves, which is memory-curate's job.
When should I use this skill?
Weekly/biweekly, on request to clean up memory, or when MEMORY.md exceeds ~500 lines.
What you get
A reorganized memory tree of focused files with duplicates merged, stale entries pruned, and changes logged.
- reorganized memory files
- defrag plan
- defrag log entry
By the numbers
- target 15-25 focused files
- MEMORY.md >500 lines threshold
- completed tasks removable after 14 days
Files
Memory Defrag
Reorganize memory files for clarity, efficiency, and relevance. Like filesystem defragmentation but for knowledge.
When to Run
- Periodic: Weekly or biweekly via cron (recommended)
- On demand: User asks to clean up, reorganize, or defrag memory
- Threshold: When MEMORY.md exceeds ~500 lines or daily notes accumulate without consolidation
Process
1. Audit Current State
Inventory all memory files:
MEMORY.md — long-term memory
memory/ — daily notes, tasks, topical files
memory/tasks/ — active and completed tasksFor each file, note: line count, last modified, topic coverage, staleness.
2. Identify Problems
Look for these common issues:
| Problem | Signal | Fix |
|---|---|---|
| Bloated file | >300 lines, covers many topics | Split into focused files |
| Duplicate info | Same fact in multiple places | Consolidate to one location |
| Stale entries | References to completed work, old dates, resolved issues | Remove or archive |
| Orphan files | Files in memory/ never referenced or updated | Review, merge, or remove |
| Inconsistencies | Contradictory information across files | Resolve to ground truth |
| Poor organization | Related info scattered across files | Restructure by topic |
| Recursive nesting | memory/memory/memory/... directories | Delete nested dirs (indexer bug artifact) |
3. Plan Changes
Before making edits, write a brief plan:
## Defrag Plan
- [ ] Split MEMORY.md "Key People" section → memory/people.md
- [ ] Remove completed tasks older than 30 days from memory/tasks/
- [ ] Merge memory/bm-marketing-ideas.md into memory/competitive/
- [ ] Update stale project status entries in MEMORY.md4. Execute
Apply changes one at a time:
- Split: Extract sections from large files into focused topical files
- Merge: Combine related small files into coherent documents
- Prune: Remove information that is no longer relevant or accurate
- Restructure: Move files to appropriate directories, rename for clarity
- Update: Fix outdated facts, dates, statuses
5. Verify & Log
After changes:
- Verify no information was lost (compare before/after)
- Update any cross-references between files
- Log what was done in today's daily note:
## Memory Defrag (HH:MM)
- Files reviewed: N
- Split: [list]
- Merged: [list]
- Pruned: [list]
- Net result: X files, Y total lines (was Z lines)Guidelines
- Preserve raw daily notes. Don't delete or modify
memory/YYYY-MM-DD.mdfiles — they're the audit trail. - Target 15-25 focused files. Too few means bloated files; too many means fragmentation. Aim for the sweet spot.
- File names should be scannable. Use descriptive names:
people.md,project-status.md,competitive-landscape.md— notnotes-2.md. - Don't over-organize. One level of directories is usually enough.
memory/tasks/andmemory/competitive/are fine;memory/work/projects/active/basic-memory/notes/is not. - Completed tasks: Tasks with
status: doneolder than 14 days can be removed. Their insights should already be in MEMORY.md via reflection. - Ask before destructive changes. If uncertain whether information is still relevant, keep it with a
(review needed)tag rather than deleting.
Related skills
Grill MeHave an agent relentlessly pressure-test their plan or design until every decision branch is resolved and shared understanding is reached.691k196kGrill With DocsPressure-test architecture decisions against their live codebase and living documentation before writing production code.585k196k
Lark CalendarLet their coding agents read, create, and manage events inside Lark (Feishu) Calendar directly from natural language instructions.493kLark ImLet their coding agent send instant notifications, post updates, and receive commands directly inside Lark (Feishu) workspaces.493kLark ContactLet their AI coding agents read and write contacts, send messages, and manage user data inside Lark (Feishu).493kLark AttendanceAutomatically fetch and report daily attendance data from Lark (Feishu) into their own tools or agents.493kFAQ
Does it delete daily notes?
No. It preserves raw memory/YYYY-MM-DD.md daily notes as the audit trail.
How many files should result?
It targets 15-25 focused files, avoiding both bloated files and fragmentation.