name: defragmenting-memory description: Defragments and cleans up agent memory blocks. Use when memory becomes messy, redundant, or poorly organized. Backs up memory, uses a subagent to clean it up, then restores the cleaned version.

Memory Defragmentation Skill

This skill helps you maintain clean, well-organized memory blocks by:

1. Dumping current memory to local files and backing up the agent file
2. Using the memory subagent to clean up the files
3. Restoring the cleaned files back to memory

When to Use

• Memory blocks have redundant information
• Memory lacks structure (walls of text)
• Memory contains contradictions
• Memory has grown stale or outdated
• After major project milestones
• Every 50-100 conversation turns

Workflow

Step 1: Backup Memory to Files

npx tsx <SKILL_DIR>/scripts/backup-memory.ts $LETTA_AGENT_ID .letta/backups/working

This creates:

• .letta/backups/<agent-id>/<timestamp>/ - Timestamped memory blocks backup
• .letta/backups/working/ - Working directory with editable files
• Each memory block as a .md file: persona.md, human.md, project.md, etc.

Step 2: Spawn Memory Subagent to Clean Files

Task({
  subagent_type: "memory",
  description: "Clean up memory files",
  prompt: `Edit the memory block files in .letta/backups/working/ to clean them up.

Focus on:
- Reorganize and consolidate redundant information
- Add clear structure with markdown headers
- Organize content with bullet points
- Resolve contradictions
- Improve scannability

IMPORTANT: When merging blocks, DELETE the redundant source files after consolidating their content (use Bash rm command). You have full bash access in the .letta/backups/working directory. Only delete files when: (1) you've merged their content into another block, or (2) the file contains only irrelevant/junk data with no project value.

Files to edit: persona.md, human.md, project.md
Do NOT edit: skills.md (auto-generated), loaded_skills.md (system-managed)

After editing, provide a report with before/after character counts and list any deleted files.`
})

The memory subagent will:

• Read the files from .letta/backups/working/
• Edit them to reorganize and consolidate redundancy
• Merge related blocks together for better organization
• Add clear structure with markdown formatting
• Delete source files after merging their content into other blocks
• Provide a detailed report of changes (including what was merged where)

Step 3: Restore Cleaned Files to Memory

npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/working

This will:

• Compare each file to current memory blocks
• Update only the blocks that changed
• Show before/after character counts
• Skip unchanged blocks

Example Complete Flow

// Step 1: Backup memory to files
Bash({
  command: "npx tsx <SKILL_DIR>/scripts/backup-memory.ts $LETTA_AGENT_ID .letta/backups/working",
  description: "Backup memory to files"
})

// Step 2: Clean up (subagent edits files and deletes merged ones)
Task({
  subagent_type: "memory",
  description: "Clean up memory files",
  prompt: "Edit memory files in .letta/backups/working/ to reorganize and consolidate redundancy. Focus on persona.md, human.md, and project.md. Merge related blocks together and DELETE the source files after merging (use Bash rm command - you have full bash access). Add clear structure. Report what was merged and where, and which files were deleted."
})

// Step 3: Restore
Bash({
  command: "npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/working",
  description: "Restore cleaned memory blocks"
})

Rollback

If something goes wrong, restore from a previous backup:

# Find the backup directory
ls -la .letta/backups/<agent-id>/

# Restore from specific timestamp
npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/<agent-id>/<timestamp>

Dry Run

Preview changes without applying them:

npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/working --dry-run

What the Memory Subagent Does

The memory subagent focuses on cleaning up files. It:

• Reads files from .letta/backups/working/
• Edits files to improve structure and consolidate redundancy
• Merges related blocks together to reduce fragmentation
• Reorganizes information for better clarity and scannability
• Deletes source files after merging their content (using Bash rm command)
• Provides detailed before/after reports including merge operations
• Does NOT run backup scripts (main agent does this)
• Does NOT run restore scripts (main agent does this)

The memory subagent runs with bypassPermissions mode, giving it full Bash access to delete files after merging them. The focus is on consolidation and reorganization.

Tips

What to clean up:

• Duplicate information (consolidate into one well-organized section)
• Walls of text without structure (add headers and bullets)
• Contradictions (resolve by clarifying or choosing the better guidance)
• Speculation ("probably", "maybe" - make it concrete or remove)
• Transient details that won't matter in a week

Reorganization Strategy:

• Consolidate duplicate information into a single, well-structured section
• Merge related content that's scattered across multiple blocks
• Add clear headers and bullet points for scannability
• Group similar information together logically
• After merging blocks, DELETE the source files to avoid duplication

When to DELETE a file:

• After merging - You've consolidated its content into another block (common and encouraged)
• Junk data - File contains only irrelevant test/junk data with no project connection
• Empty/deprecated - File is just a notice with no unique information
• Don't delete - If file has unique information that hasn't been merged elsewhere

What to preserve:

• User preferences (sacred - never delete)
• Project conventions discovered through experience
• Important context for future sessions
• Learnings from past mistakes
• Any information that has unique value

Good memory structure:

• Use markdown headers (##, ###)
• Organize with bullet points
• Keep related information together
• Make it scannable at a glance