defragmenting-memory_skill

Overview

This skill decomposes and reorganizes agent memory files into focused, single-purpose components to improve clarity, reduce redundancy, and make memory blocks easier to maintain. It operates on the memfs memory directory and is intended for agents that show large multi-topic blocks, contradictions, or poor structure. A mandatory safety backup is required before any edits are made.

How this skill works

The skill creates a timestamped backup of the memfs directory, then spawns a memory subagent that reads, edits, and creates .md files under the agent's memory root. The subagent splits multi-purpose blocks into hierarchical, single-purpose files, restructures content with clear markdown headers and bullets, removes redundancy and speculation, and produces a detailed before/after report. Changes are propagated to API memory blocks by memfs sync on the next CLI startup.

When to use it

• Memory blocks are large, multi-topic, or look like "walls of text"
• You see redundant or contradictory information across memory files
• Memory has grown stale after major milestones or project changes
• You want better discoverability using hierarchical / naming
• Regular maintenance every ~50–100 conversation turns

Best practices

• Always run a memfs backup before starting the subagent (required safety step)
• Favor decomposition over consolidation: each file should have one clear purpose
• Use hierarchical paths (folder/name.md) and concise filenames that state purpose
• Structure content with headers and bullet lists for scannability
• Keep user preferences and unique context intact; delete only junk or fully migrated sources

Example use cases

• Split a monolithic persona.md into persona/identity.md, persona/values.md, persona/approach.md
• Decompose project.md into project/overview.md, project/architecture.md, project/conventions.md
• Remove duplicated guidance scattered across multiple blocks and centralize it into a single, focused block
• After a release or pivot, reorganize memory to reflect new responsibilities and remove outdated details
• Periodic housekeeping to keep memory concise and reduce contradictions