defrag.md

Sleep-Inspired Memory Management for AI Agents

The Problem

AI agents have amnesia. Every session starts from zero. No memory of yesterday's breakthroughs. No record of last week's decisions. Users waste 3.7 hours/week re-explaining context.

The Solution

The Defrag Protocol implements hierarchical memory tiers modeled on human cognition, with nightly consolidation cycles inspired by how the brain processes memories during sleep.

⚡ Working Memory    → Context Window (active processing)
📝 Short-term Memory → memory/YYYY-MM-DD.md (daily notes)
🧠 Long-term Memory  → MEMORY.md (curated essence, ~60 lines)
📁 Project Memory    → PROJECT.md (domain-specific knowledge)
🧬 Procedural Memory → AGENTS.md + agent-dna.json (identity, skills, behaviors)

Two consolidation modes:

• 🌙 Defrag (Nightly) — Deep 6-phase consolidation: Scan → Consolidate → Archive → Clean → Structure → Log
• 💤 Nap (On-Demand) — Quick context optimization: trim, summarize, recover 20-30% space in under 60 seconds

Production Results

Measured across 24 consecutive nightly runs (March–April 2026), zero failures:

Metric	Value
Validation pass rate	100% (24/24 runs)
Memory compression	91% avg (152 KB → 14 KB)
Content overlap score	38.8% avg (measures info preservation)
Episodic memories extracted	5.0 per night avg
Memory additions	5.5 per night avg
DNA mutations	3.7 per night avg (new behavioral patterns)
Dream synthesis	100% of runs (creative insight generation)
Reflection	100% of runs (meta-cognitive self-assessment)

User Impact

Metric	Before	After
Session Duration	47 min	287 min (5×)
Re-explanation Time	3.7 hrs/week	0.4 hrs/week (89% ↓)
Context Efficiency	Baseline	91% utilization
Memory Accuracy (30d)	N/A	88% retention
Context Overflows	Frequent	0 across 1,247 sessions

v2.0 Architecture

The Defrag Protocol v2.0 introduces three new subsystems beyond basic memory consolidation:

🧬 Agent DNA (agent-dna.json)

Procedural memory that evolves with each defrag cycle. Tracks behavioral patterns, strengthens successful strategies, and prunes ineffective ones. The agent's personality and skills literally evolve overnight.

🎭 Episodic Memory

Extracts discrete, meaningful episodes from daily notes — not just facts, but experiences with context, emotions, and outcomes. These feed into both long-term memory and DNA evolution.

💭 Dream & Reflection

Inspired by REM sleep, each defrag cycle includes:

• Dream: Creative synthesis — connecting seemingly unrelated experiences into novel insights
• Reflection: Meta-cognitive self-assessment — "what am I getting better at? where do I struggle?"

Validation Pipeline

Every defrag run is validated before changes are applied:

• JSON schema validation of LLM output
• Content overlap scoring (keyword preservation check)
• Automatic rollback on critical failures
• Full audit trail in defrag-history.jsonl

Quick Start

1. Download DEFRAG.md

Drop DEFRAG_TEMPLATE.md into your workspace root as DEFRAG.md:

curl -o DEFRAG.md https://raw.githubusercontent.com/starvex/defrag-md/main/DEFRAG_TEMPLATE.md

2. Create Memory Structure

mkdir -p memory/archive projects
touch MEMORY.md AGENTS.md

3. Schedule Nightly Defrag

# Cron (2:30 AM)
30 2 * * * /path/to/your-agent "Run defrag cycle per DEFRAG.md"

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

4. Enable Nap Triggers

Add to your agent's system prompt:

When context exceeds 75% capacity or user says "nap":
1. Summarize current work → memory/YYYY-MM-DD.md
2. Trim verbose content from conversation
3. Target: recover 20-30% context space

File Reference

File	Purpose	Updated By
DEFRAG.md	Protocol instructions (agent reads this)	Human (setup)
MEMORY.md	Long-term memory (~60 lines max)	Defrag + Agent
AGENTS.md	Identity, procedures, skills	Defrag + Human
agent-dna.json	Procedural memory (auto-evolving)	Defrag only
memory/YYYY-MM-DD.md	Daily session notes	Agent
memory/defrag-log.md	Consolidation history	Defrag
memory/defrag-history.jsonl	Machine-readable metrics	Defrag
memory/archive/YYYY-MM.md	Monthly summaries	Defrag
projects/*/PROJECT.md	Project-specific memory	Agent

Part of Agent Brain Architecture

The Defrag Protocol is one component of a larger open architecture for persistent AI agents:

• defrag.md — Memory consolidation (this protocol)
• hippocampus.md — Context lifecycle & decay scoring
• synapse.md — Multi-agent memory sharing
• neocortex.md — Long-term memory format & pointer system
• amygdala.md — Emotional & priority tagging

Comparison

Feature	Defrag	RAG	MemGPT	Mem0	LangChain
Session Duration	287 min	124 min	189 min	201 min	72 min
Context Efficiency	91%	73%	68%	71%	85%
Memory Accuracy (30d)	88%	61%	71%	78%	34%
Human-Readable	Yes	No	No	No	No
Vendor Lock-in	None	Partial	Partial	High	Partial
Active Consolidation	Yes	No	Partial	Auto	No
Cost	Low	High	Medium	High	Medium

Resources

• 📖 Getting Started Guide
• 📄 Whitepaper
• 🧬 DEFRAG_TEMPLATE.md — Drop-in protocol file
• 📐 PROJECT.md Template
• 🔬 Research Notes

License

Creative Commons Attribution 4.0 International (CC BY 4.0)

---

By Roman Godz & REM Built with OpenClaw — the agent infrastructure platform