openclaw/docs/concepts/dreaming.md

title	summary	read_when
Dreaming (experimental)	Background memory consolidation with light, deep, and REM phases plus a Dream Diary	You want memory promotion to run automatically You want to understand what each dreaming phase does You want to tune consolidation without polluting MEMORY.md

Dreaming (experimental)

Dreaming is the background memory consolidation system in memory-core. It helps OpenClaw move strong short-term signals into durable memory while keeping the process explainable and reviewable.

Dreaming is opt-in and disabled by default.

What dreaming writes

Dreaming keeps two kinds of output:

• Machine state in memory/.dreams/ (recall store, phase signals, ingestion checkpoints, locks).
• Human-readable output in DREAMS.md (or existing dreams.md) and optional phase report files under memory/dreaming/<phase>/YYYY-MM-DD.md.

Long-term promotion still writes only to MEMORY.md.

Phase model

Dreaming uses three cooperative phases:

Phase	Purpose	Durable write
Light	Sort and stage recent short-term material	No
Deep	Score and promote durable candidates	Yes (MEMORY.md)
REM	Reflect on themes and recurring ideas	No

These phases are internal implementation details, not separate user-configured "modes."

Light phase

Light phase ingests recent daily memory signals and recall traces, dedupes them, and stages candidate lines.

• Reads from short-term recall state and recent daily memory files.
• Writes a managed ## Light Sleep block when storage includes inline output.
• Records reinforcement signals for later deep ranking.
• Never writes to MEMORY.md.

Deep phase

Deep phase decides what becomes long-term memory.

• Ranks candidates using weighted scoring and threshold gates.
• Requires minScore, minRecallCount, and minUniqueQueries to pass.
• Rehydrates snippets from live daily files before writing, so stale/deleted snippets are skipped.
• Appends promoted entries to MEMORY.md.
• Writes a ## Deep Sleep summary into DREAMS.md and optionally writes memory/dreaming/deep/YYYY-MM-DD.md.

REM phase

REM phase extracts patterns and reflective signals.

• Builds theme and reflection summaries from recent short-term traces.
• Writes a managed ## REM Sleep block when storage includes inline output.
• Records REM reinforcement signals used by deep ranking.
• Never writes to MEMORY.md.

Dream Diary

Dreaming also keeps a narrative Dream Diary in DREAMS.md. After each phase has enough material, memory-core runs a best-effort background subagent turn (using the default runtime model) and appends a short diary entry.

This diary is for human reading in the Dreams UI, not a promotion source.

Deep ranking signals

Deep ranking uses six weighted base signals plus phase reinforcement:

Signal	Weight	Description
Frequency	0.24	How many short-term signals the entry accumulated
Relevance	0.30	Average retrieval quality for the entry
Query diversity	0.15	Distinct query/day contexts that surfaced it
Recency	0.15	Time-decayed freshness score
Consolidation	0.10	Multi-day recurrence strength
Conceptual richness	0.06	Concept-tag density from snippet/path

Light and REM phase hits add a small recency-decayed boost from memory/.dreams/phase-signals.json.

Scheduling

When enabled, memory-core auto-manages one cron job for a full dreaming sweep. Each sweep runs phases in order: light -> REM -> deep.

Default cadence behavior:

Setting	Default
dreaming.frequency	0 3 * * *

Quick start

Enable dreaming:

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true
          }
        }
      }
    }
  }
}

Enable dreaming with a custom sweep cadence:

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true,
            "timezone": "America/Los_Angeles",
            "frequency": "0 */6 * * *"
          }
        }
      }
    }
  }
}

Slash command

/dreaming status
/dreaming on
/dreaming off
/dreaming help

CLI workflow

Use CLI promotion for preview or manual apply:

openclaw memory promote
openclaw memory promote --apply
openclaw memory promote --limit 5
openclaw memory status --deep

Manual memory promote uses deep-phase thresholds by default unless overridden with CLI flags.

Key defaults

All settings live under plugins.entries.memory-core.config.dreaming.

Key	Default
enabled	false
frequency	0 3 * * *

Phase policy, thresholds, and storage behavior are internal implementation details (not user-facing config).

See Memory configuration reference for the full key list.

Dreams UI

When enabled, the Gateway Dreams tab shows:

• current dreaming enabled state
• phase-level status and managed-sweep presence
• short-term, long-term, and promoted-today counts
• next scheduled run timing
• an expandable Dream Diary reader backed by doctor.memory.dreamDiary

Related

• Memory
• Memory Search
• memory CLI
• Memory configuration reference