memory-defrag
Defragment and reorganize agent memory files: split bloated files, merge duplicates, remove stale information, and restructure the memory hierarchy. Use when memory files have grown unwieldy, contain redundancies, or need reorganization. Run periodically (weekly) or on demand.
- Installs
- 632
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/basicmachines-co/basic-memory-skills --skill memory-defrag- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads memory-defrag automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 tasks
For 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.md
4. 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.
FAQ
What does the memory-defrag skill do?
Defragment and reorganize agent memory files: split bloated files, merge duplicates, remove stale information, and restructure the memory hierarchy. Use when memory files have grown unwieldy, contain redundancies, or need reorganization. Run periodically (weekly) or on demand.
How do I install memory-defrag?
Run npx skills add https://github.com/basicmachines-co/basic-memory-skills --skill memory-defrag in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/memory-defrag/ (personal) or .claude/skills/memory-defrag/ (project).
Which AI agents can use memory-defrag?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is memory-defrag safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains memory-defrag?
It is published by basicmachines-co in basicmachines-co/basic-memory-skills. It has 632 recorded installs.
More from basicmachines-co/basic-memory-skills
memory-notes
basicmachines-co/basic-memory-skills
How to write well-structured Basic Memory notes: frontmatter, observations with semantic categories, relations with wiki-links, and best practices for building a rich knowledge graph. Use when creating or improving notes.
memory-reflect
basicmachines-co/basic-memory-skills
Sleep-time memory reflection: review recent conversations and daily notes, extract insights, and consolidate into long-term memory. Use when triggered by cron, heartbeat, or explicit request to reflect on recent activity. Runs as background processing to improve memory quality over time.
memory-tasks
basicmachines-co/basic-memory-skills
Task management via Basic Memory schemas: create, track, and resume structured tasks that survive context compaction. Uses BM's schema system for uniform notes queryable through the knowledge graph.
memory-schema
basicmachines-co/basic-memory-skills
Schema lifecycle management for Basic Memory: discover unschemaed notes, infer schemas, create and edit schema definitions, validate notes, and detect drift. Use when working with structured note types (Task, Person, Meeting, etc.) to maintain consistency across the knowledge graph.
memory-metadata-search
basicmachines-co/basic-memory-skills
Structured metadata search for Basic Memory: query notes by custom frontmatter fields using equality, range, array, and nested filters. Use when finding notes by status, priority, confidence, or any custom YAML field rather than free-text content.
memory-lifecycle
basicmachines-co/basic-memory-skills
Manage entity status transitions in Basic Memory: archive completed work, move notes between status folders, update frontmatter, and handle edge cases. Use when marking items complete, archiving old entities, or managing any folder-based status workflow.
Popular other skills
hyperframes-cli
heygen-com/hyperframes
The HyperFrames CLI by job - scaffold, check, look at frames, edit the timeline, preview, render locally or in the cloud, publish, project history - plus reading its JSON and recovering from build or render failures.
triage
mattpocock/skills
Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.
ask-matt
mattpocock/skills
Ask which skill or flow fits your situation. A router over the skills in this repo.
to-questionnaire
mattpocock/skills
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
loop-me
mattpocock/skills
Grill me about specs for the workflows I want to build, within this workspace.