How OpenClaw Dreaming Works

Dreaming is OpenClaw's background memory-consolidation system, built natively into memory-core. While the agent is idle, it replays recent short-term material — daily memory files, recall state, redacted transcripts — through three sleep-inspired phases, and promotes only the strongest candidates into long-term durable memory (MEMORY.md).

Three design properties distinguish it from the resource-heavy vector-database side-stacks that preceded it:

Explainable: Every cycle leaves a human-readable audit trail in DREAMS.md. You can read exactly what was promoted, what decayed, and why.
Conservative: Exactly one phase is allowed to write durable memory, and it must pass three threshold gates first. Nothing is deleted — unpromoted memories simply decay.
Self-contained: No second memory stack, no embedding pipeline, no vector DB. It reuses the agent's existing file-based memory with a managed cron job.

1. The Problem of Session Drift

Agents accumulate daily notes fast — commonly 10 KB+ per active day. Without consolidation, that history produces session drift: the agent forgets key decisions, repeats past mistakes, and loses crucial project context once notes age out of the short-term retention window or get compacted away.

Prior to Dreaming, the only workarounds were manually pinning important notes or running a separate vector-memory pipeline alongside the agent. Both required ongoing human curation. Dreaming automates this curation step: the agent decides, on a schedule and against explicit scoring gates, what deserves to survive.

The biological framing is deliberate and reasonably faithful. During sleep, the human brain replays experiences and transfers the important ones to long-term storage; the rest fade. Dreaming is the same shape: replay short-term traces, strengthen what recurs, and let the noise decay.

2. The Three Sleep Phases

A full sweep runs the phases in order: Light → REM → Deep. Light and REM are read-and-stage passes that never touch durable memory; Deep is the only phase with write authority over MEMORY.md.

Light Sleep — Sort and Stage

Action: Reads short-term recall state, recent daily memory files (memory/YYYY-MM-DD.md), and redacted session transcripts where available.
Output: Writes a managed ## Light Sleep block when inline output is enabled.
Impact: Records reinforcement signals consumed later by deep ranking. Never writes to MEMORY.md.

REM Sleep — Reflect and Associate

Action: Builds theme and reflection summaries from recent short-term traces — the "what keeps coming up" pass.
Output: Writes a managed ## REM Sleep block; records REM reinforcement signals used by deep ranking.
Impact: Integrates associations but never writes to MEMORY.md.

Deep Sleep — Score and Promote

Action: Ranks candidates using a weighted scoring algorithm, then applies three gates that must all pass: minScore, minRecallCount, and minUniqueQueries.
Output: Appends promoted entries to MEMORY.md, writes a ## Deep Sleep summary into DREAMS.md, and optionally archives a per-day record at memory/dreaming/deep/YYYY-MM-DD.md.
Impact: Rehydrates snippets from live daily files immediately before writing — if the source note was edited or deleted since staging, the stale snippet is skipped rather than promoted blind.

Warning

Architecture Safeguard Several third-party guides incorrectly describe REM as the phase that writes long-term memory, with Deep doing the scoring. The official architecture is stricter:Deep Sleep is the only durable writer. REM is read-only reflection. If you're auditing a Dreaming install, watch MEMORY.md mutations during the deep phase only — a durable write during light or REM indicates a misconfigured or non-standard build.

3. Scoring, Decay, and What Survives

Promotion is intentionally hard to earn. A candidate must be important (score above minScore), demonstrably useful (recalled at least minRecallCount times), and broadly useful (matched by at least minUniqueQueries distinct queries). One-off trivia that the agent never touched again will not pass the gates, no matter how interesting it looked on the day.

Two decay parameters shape the candidate pool itself:

Parameter	Effect
`recencyHalfLifeDays`	How fast a memory's weight decays with age. Lower values bias the agent toward recent context; higher values preserve older material longer.
`maxAgeDays`	Hard cutoff. Memories older than this are no longer eligible for promotion at all.

Nothing is force-deleted. Dreaming promotes; it does not prune. Unpromoted short-term memories fade on their normal retention schedule, and MEMORY.md is treated as append-and-refine — entries may be deduplicated or merged, but the file is additive.

4. The Dream Diary

Beyond the mechanical phase blocks, Dreaming keeps a narrative log in DREAMS.md. After each phase has enough material, memory-core runs a best-effort background subagent turn and appends a short diary entry — a few sentences of "what tonight's sweep noticed."

The diary runs on the default runtime model unless dreaming.model overrides it (useful for routing consolidation to a cheaper model). If the configured model is unavailable, it retries once with the session default; trust and allowlist failures surface as errors rather than silently falling back.

Operationally, the diary is the fastest health check there is: a DREAMS.md that stopped gaining entries means the sweep stopped running.

5. Scheduling and Execution

When Dreaming is enabled, memory-core auto-manages a single cron job that performs the full sweep (light → REM → deep). You don't hand-schedule the phases.

Activity guard: Sweeps respect a quiet-period check so consolidation doesn't fire mid-conversation. The guard reads persisted session-store updatedAt timestamps rather than in-memory state, so it survives gateway restarts — an early design that tracked activity in a volatile singleton was rejected for exactly this reason.
Workspace fan-out: The sweep covers the primary runtime workspace plus any configured agent workspaces, deduplicated by path, so subagent workspaces don't crowd out the main agent's DREAMS.md and memory state.
Non-blocking: Consolidation runs in the background and yields to live sessions; a sweep overlapping a conversation does not slow the conversation.
Manual trigger: The /dreaming chat command triggers or inspects a cycle on demand; results from manual and scheduled runs both land in the diary.

6. Configuration Spec

All settings live under plugins.entries.memory-core.config.dreaming. A representative setup:

plugins:
  entries:
    memory-core:
      config:
        dreaming:
          enabled: true            # opt-in; off by default
          schedule: "0 3 * * *"    # nightly sweep, 3 AM
          model: gemma3-local      # optional cheaper model for consolidation
          minScore: 0.6            # promotion gate 1: importance
          minRecallCount: 2        # promotion gate 2: proven usefulness
          minUniqueQueries: 2      # promotion gate 3: breadth
          recencyHalfLifeDays: 14  # age-decay half-life
          maxAgeDays: 60           # hard eligibility cutoff

Restricting dreaming.model further requires the subagent allowlist (plugins.entries.memory-core.subagent.allowedModels); model failures stay visible rather than degrading silently.

7. Operations and Troubleshooting

Symptom	Diagnosis	Solution
`openclaw memory status` reports `Dreaming status: blocked`	The managed cron exists but the default agent heartbeat isn't firing.	Confirm heartbeat is enabled and its target isn't `none`, then re-check with `openclaw memory status --deep` after the next heartbeat interval.
`DREAMS.md` stopped gaining entries	Sweep isn't running.	Check the managed cron job and the activity guard's quiet window.
Nothing ever gets promoted	Gates are too strict for your usage volume.	New agents with little history won't clear `minRecallCount`/`minUniqueQueries`; either lower the gates or let history accumulate.
Stale facts being promoted	Snippet synchronization failure.	Deep rehydrates from live daily files and skips deleted snippets. If observed, verify you're on a current `memory-core` and not a fork.
CPU spikes on small hardware	Excessive batch processing.	Cap the per-cycle batch (`maxReplayBatch`-style limits) or schedule sweeps further apart.

8. Architectural Assessment

The strongest part of the design is restraint. Most "agent memory" systems fail open — they hoard everything and drown in their own context. Dreaming fails closed: three gates, one writer, full audit trail, no deletions. That makes it boring to operate, which is the correct property for memory infrastructure.

The weakest part is cold start. The gates that protect a mature agent from noise also mean a fresh install sees no visible benefit for days or weeks, and the temptation is to lower thresholds until promotion happens — at which point you've rebuilt the hoarding problem with extra steps. Better defaults here would be adaptive gates keyed to history volume.

The architecture also quietly resolves the consolidation-vs-recall tradeoff by keeping both layers in plain Markdown. There is no embedding index to drift out of sync, and every artifact — MEMORY.md, DREAMS.md, per-day deep archives — is diffable, greppable, and reviewable in a pull request. For a single-operator agent, that beats a vector store on every axis except semantic fuzzy recall, which short-term search still covers.

Sources

OpenClaw documentation — Concepts: Dreaming (memory-core; phase table, gates, diary, sweep, troubleshooting).
openclaw/openclaw — PR #19685: Dreaming Process — Autonomous Memory Consolidation (design rationale, activity guard, quiet hours).
openclaw/openclaw — PR #59262: memory-sleep skill (NREM/REM-inspired consolidation cycle, session-drift framing).
OpenClaw Launch — Dreaming guide and background memory guide (decay parameters, scoring overview, CLI usage).
OpenClaw DC — Dreaming explained (idle replay, no-second-stack design, rollout defaults).