Getting Started with defrag.md

Implement sleep-inspired memory management in your AI agent in under 10 minutes.

Prerequisites

✓An AI agent with file system access (Claude, GPT-4, etc.)
✓A workspace directory for memory files
✓Ability to schedule recurring tasks (cron, Task Scheduler, etc.)

Create Your Memory Structure

Set up the five-tier memory hierarchy in your workspace:

workspace/
├── MEMORY.md          # Long-term memory (~60 lines max)
├── AGENTS.md          # Procedural memory (identity, skills)
├── memory/
│   └── YYYY-MM-DD.md  # Daily notes (short-term memory)
├── projects/
│   └── <project>/
│       └── PROJECT.md # Project-specific memory
└── DEFRAG.md          # Defrag configuration & log

Download DEFRAG.md

This file contains the consolidation instructions your agent will follow:

📥 Download DEFRAG.md

Place it in your workspace root. The agent reads this during defrag cycles.

Configure the Defrag Cycle

Schedule a nightly defrag job. Example using cron (2:30 AM):

# Cron expression (Linux/macOS)
30 2 * * * /path/to/your/agent "Run defrag cycle per DEFRAG.md"

# OpenClaw config example
{
  "cron": {
    "defrag": {
      "schedule": { "kind": "cron", "expr": "30 2 * * *" },
      "payload": { 
        "kind": "agentTurn", 
        "message": "Run defrag cycle per DEFRAG.md" 
      }
    }
  }
}

The agent will read DEFRAG.md and perform memory consolidation automatically.

Enable On-Demand Naps

Add nap triggers to your agent's instructions:

# In your AGENTS.md or system prompt:

## Context Management
When context exceeds 75% capacity OR user says "nap":
1. Summarize current work → memory/YYYY-MM-DD.md
2. Move completed items to appropriate files
3. Clear verbose tool outputs from context
4. Target: recover 20-30% context space

Understanding the Two Modes

🌙

Defrag (Nightly)

Deep consolidation like human sleep. Runs at 2:30 AM.

✓ Scan all memory files
✓ Archive old daily notes
✓ Remove duplicates
✓ Enforce size limits
✓ Log what changed

💤

Nap (On-Demand)

Quick context optimization. Under 60 seconds.

✓ Trim verbose content
✓ Summarize recent work
✓ Move completed items
✓ Recover 20-30% space
✓ Stay productive

Memory File Templates

MEMORY.md

Long-term memory — curated essence (~60 lines max)

# Memory

## Identity
- Name: [Agent Name]
- Role: [Primary function]
- Style: [Communication preferences]

## People
- [Name]: [Relationship, preferences, key context]

## Projects
- [Project]: [Status, key decisions, location]

## Knowledge
- [Topic]: [Important facts, configurations]

## Patterns
- [Behavioral pattern]: [When/how to apply]

## Lessons
- [Lesson learned]: [Context, avoid repeating]

Daily Notes (memory/YYYY-MM-DD.md)

Short-term memory — raw session notes

# 2026-02-03

## Session 1 (10:30)
- Task: [What was worked on]
- Decisions: [Key choices made]
- Blockers: [Issues encountered]
- Next: [Follow-up items]

## Session 2 (14:00)
- ...

## Notes
- [Anything worth remembering]

Best Practices

1.
Keep MEMORY.md under 60 lines.
More isn't better. Curated beats comprehensive.
2.
Archive daily notes after 7 days.
Move to memory/archive/YYYY-MM.md monthly summaries.
3.
One PROJECT.md per project.
Prevents context bleeding between codebases.
4.
Nap before context overflow.
Trigger at 75% capacity, not 99%.
5.
Review defrag logs weekly.
Ensure important info isn't being lost.