Part 16: autoDream — Automatic Memory Consolidation

Part 16: autoDream — Automatic Memory Consolidation

**Note:** OpenClaw 2026.4+ has a [built-in dreaming system (Part 22)](./README.md#part-22-built-in-dreaming) inside memory-core. If you're on 2026.4+, use that instead — it's the official, supported version with proper scoring, phase management, and a UI. This part is kept for older versions and custom implementations.

*Your agent's memory grows forever. Session files pile up. MEMORY.md gets stale. Knowledge gets buried. autoDream fixes this by teaching your agent to consolidate its own memory — automatically, on every session start.*

---

The Problem

Every OpenClaw session generates knowledge. Decisions get made, lessons get learned, infrastructure changes happen. The `session-memory` hook dutifully saves all of this to `memory/*.md` files.

But nobody cleans it up.

After a month you've got 200+ session files, a MEMORY.md that's either a stale stub or an unmanageable wall of text, and your agent spends half its context window loading irrelevant session transcripts from 3 weeks ago.

Claude Code solved this with a system called **autoDream** — a background memory consolidation engine. We reverse-engineered the pattern from their [leaked source code](https://github.com/instructkr/claude-code) and adapted it for OpenClaw.

The key insight: **you don't need a new script or cron job. Your agent IS the consolidation engine — you just need to give it instructions.**

---

How It Works

The 3-Gate Trigger (Cheapest-First)

autoDream doesn't run every session — that would waste time on casual chats. It uses gates checked in **cheapest-first order** (stop at first failure):

Gate	Condition	Cost	Why
TIME	≥24 hours since last dream	1 read	Don't consolidate too often
SCAN THROTTLE	≥10 minutes since last gate check	1 read	Prevent thrashing when time passes but sessions haven't accumulated
SESSION	≥5 sessions since last dream (excluding current)	1 read	Ensure enough new material
USER	User's first message isn't urgent	Judgment	Don't delay someone who needs help NOW

The scan throttle is key — without it, every single message re-checks the session count once the time gate passes. Claude Code's actual implementation uses `SESSION_SCAN_INTERVAL_MS = 10 * 60 * 1000` (10 minutes) for this.

State is tracked in `memory/.dream-state.json`:

{
  "lastDreamAt": "2026-03-31T15:47:00Z",
  "sessionsSinceDream": 0,
  "lastScanAt": null,
  "totalDreams": 1,
  "lastDreamResult": "success",
  "lastProcessedFiles": ["2026-03-31-session.md"]
}

**Failure recovery:** If a dream crashes mid-execution, reset `lastDreamAt` to its previous value so the time gate passes again on the next attempt. This is Claude Code's "lock rollback" pattern — don't let a failed dream block all future dreams.

The 4-Phase Execution

When gates pass, the agent runs a consolidation pass (2-3 minutes max) before respondin