DEV Community

cz
cz

Posted on

OpenClaw Dreaming Guide 2026: Background Memory Consolidation for AI Agents

#ai #openclaw #llm

OpenClaw Dreaming Guide 2026: Background Memory Consolidation for AI Agents

🎯 Core Takeaways (TL;DR)

  • Dreaming is OpenClaw's automatic three-phase background process that turns short-term memory signals into durable long-term knowledge
  • It runs in three stages: Light Sleep (ingest & stage), REM Sleep (reflect & extract patterns), and Deep Sleep (promote to MEMORY.md)
  • Only entries that pass all three threshold gates — minScore 0.8, minRecallCount 3, minUniqueQueries 3 — get promoted
  • Six weighted signals score every candidate: Relevance (0.30), Frequency (0.24), Query diversity (0.15), Recency (0.15), Consolidation (0.10), Conceptual richness (0.06)
  • Dreaming is opt-in and disabled by default — enable with /dreaming on or via config

Table of Contents

  1. Why Dreaming Exists
  2. How It Works: The Three Phases
  3. Deep Ranking Signals Explained
  4. Threshold Gates: What Gets Promoted
  5. The Dream Diary: Human-Readable Output
  6. Where Things Live on Disk
  7. Getting Started
  8. Configuration Reference
  9. Tuning Guide
  10. FAQ

Why Dreaming Exists

OpenClaw agents accumulate memory throughout the day: daily notes, session transcripts, recall traces from searches. Most of this material is useful in the moment but doesn't belong in long-term storage. Without a consolidation step, you face one of two bad outcomes:

  • Too aggressive: every fleeting detail lands in MEMORY.md, bloating it with noise.
  • Too conservative: nothing ever gets promoted, and genuinely important patterns are lost.

Dreaming solves this with a three-phase background sweep that scores short-term signals over time and only promotes the ones that cross evidence thresholds. Think of it as a curatorial pipeline: ingest, reflect, then carefully promote.

💡 Key Insight
Dreaming is opt-in and disabled by default. You choose when and how OpenClaw consolidates memory.

How It Works: The Three Phases

When enabled, memory-core creates a managed cron job (default: 3 AM daily) that runs a full dreaming sweep. Each sweep executes three phases in sequence:

Phase 1: Light Sleep (Sort and Stage)

Light phase is the ingestion layer. It:

  • Reads recent daily memory files (memory/YYYY-MM-DD.md) and parses them into snippet chunks
  • Ingests session transcripts into per-day corpus files under memory/.dreams/session-corpus/
  • Deduplicates entries using Jaccard similarity (threshold 0.9)
  • Stages candidates in the short-term recall store
  • Records "light phase signal" hits — these boost ranking in the deep phase later
  • Writes a ## Light Sleep block into the daily memory file (when storage mode includes inline output)
  • Optionally generates a dream diary narrative entry

⚠️ Important
Light phase never writes to MEMORY.md. It only stages and records signals.

Phase 2: REM Sleep (Reflect and Extract Patterns)

REM phase looks for recurring themes across the staged material. It:

  • Reads all short-term recall entries within the REM lookback window (default: 7 days)
  • Extracts recurring themes by analyzing concept tag frequency
  • Identifies "candidate truths" — entries that show up repeatedly with high confidence
  • Writes a ## REM Sleep block with reflections
  • Records REM signal hits (these also boost deep ranking)
  • Generates a dream diary narrative entry

⚠️ Important
REM phase never writes to MEMORY.md either. It produces reflective signals that inform the deep phase.

Phase 3: Deep Sleep (Promote to Long-Term Memory)

This is where promotion actually happens. Deep phase:

  • Takes all candidates from the short-term recall store
  • Scores each one using six weighted signals (see ranking table below)
  • Applies phase reinforcement boosts from light and REM signal hits
  • Filters out candidates that don't pass the threshold gates
  • Rehydrates surviving snippets from live daily files (so deleted or stale content is skipped)
  • Appends promoted entries to MEMORY.md under a dated ## Promoted From Short-Term Memory section
  • Writes a deep sleep report and generates a dream diary narrative entry

✅ Best Practice
Deep phase is the only phase that writes to MEMORY.md. This separation ensures noisy data never pollutes long-term memory.

Deep Ranking Signals Explained

Every candidate in the short-term recall store is scored using six weighted signals. Here's the complete breakdown:

Signal Weight What It Measures
Relevance 0.30 Average retrieval quality across all recalls
Frequency 0.24 Total number of short-term signals accumulated
Query diversity 0.15 How many distinct query contexts surfaced the entry
Recency 0.15 Time-decayed freshness (14-day half-life)
Consolidation 0.10 Multi-day recurrence strength
Conceptual richness 0.06 Concept-tag density from snippet and path

Light and REM phase hits add a small recency-decayed boost (up to 0.05 and 0.08 respectively) on top of the base score.

Signal Weight Visual 

Relevance         ████████████████████████████████ 0.30
Frequency         █████████████████████████  0.24
Query diversity   ███████████████  0.15
Recency           ███████████████  0.15
Consolidation     ██████████  0.10
Conceptual rich   ██████  0.06
─────────────────────────────────────────────
Total             1.00
Enter fullscreen mode Exit fullscreen mode

Threshold Gates: What Gets Promoted

A candidate must pass all three gates to be promoted:

Gate Default Meaning
minScore 0.8 Weighted composite score must be at least this high
minRecallCount 3 Entry must have been recalled at least this many times
minUniqueQueries 3 Entry must have surfaced from at least this many distinct queries

💡 Why Three Gates?
These gates prevent one-off mentions from being promoted. A memory must demonstrate sustained, diverse relevance — not just a single lucky retrieval.

Phase Reinforcement Boosts

Light and REM phase hits add bonus points on top of the base signal scores:

Phase Maximum Boost Condition
Light Sleep +0.05 Recency-decayed light phase signal hits
REM Sleep +0.08 Recency-decayed REM phase signal hits

The Dream Diary: Human-Readable Output

Alongside the machine-readable state, dreaming produces a human-readable Dream Diary in DREAMS.md. After each phase with enough material, a background subagent generates a short, creative narrative entry (80-180 words) written from the perspective of "a curious, gentle, slightly whimsical mind reflecting on the day."

The diary is visible in the Gateway Dreams tab and is intended for human browsing only — it is not a promotion source.

What the Dream Diary Looks Like 

## Light Sleep
[Creative narrative about the day's memories being gathered]

## REM Sleep
[Whimsical reflection on recurring patterns discovered]

## Deep Sleep
[Final contemplation on what was worth keeping]
Enter fullscreen mode Exit fullscreen mode

Where Things Live on Disk

Machine State (memory/.dreams/)

File Purpose
short-term-recall.json All tracked recall entries and their scores
phase-signals.json Light/REM hit counts per entry key
daily-ingestion.json Daily file change tracking
session-ingestion.json Session file change tracking
session-corpus/YYYY-MM-DD.txt Ingested session message snippets
short-term-promotion.lock File lock during promotion
events.jsonl Audit log of dreaming events

Human-Readable Output

File Purpose
DREAMS.md Dream Diary with ## Light Sleep, ## REM Sleep, ## Deep Sleep blocks
memory/dreaming/deep/YYYY-MM-DD.md Optional separate deep phase reports
MEMORY.md Long-term memory where promoted entries land

Getting Started

Enable Dreaming

The fastest way is the slash command in any channel:

/dreaming on
Enter fullscreen mode Exit fullscreen mode

Or add it to your config file:

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true
          }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Change the Sweep Schedule

Default is 3 AM daily. To run every 6 hours instead:

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true,
            "frequency": "0 */6 * * *"
          }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Check Status 

/dreaming status
Enter fullscreen mode Exit fullscreen mode

Or via CLI:

openclaw memory status --deep
Enter fullscreen mode Exit fullscreen mode

Disable Dreaming 

/dreaming off
Enter fullscreen mode Exit fullscreen mode

Manual and Debugging Workflows

Preview Promotions Without Applying

See what would be promoted if you ran a deep sweep now:

openclaw memory promote
Enter fullscreen mode Exit fullscreen mode

Apply Promotions Manually

Run a deep promotion and write results to MEMORY.md:

openclaw memory promote --apply
Enter fullscreen mode Exit fullscreen mode

Limit to the top 5 candidates:

openclaw memory promote --apply --limit 5
Enter fullscreen mode Exit fullscreen mode

Explain Why Something Would or Wouldn't Promote

Useful for tuning thresholds or understanding the scoring:

openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
Enter fullscreen mode Exit fullscreen mode

Preview REM Reflections

See what REM phase would produce without writing anything:

openclaw memory rem-harness
openclaw memory rem-harness --json
Enter fullscreen mode Exit fullscreen mode

Configuration Reference

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

Key Default Description
enabled false Master switch
frequency "0 3 * * *" Cron schedule for full sweeps
timezone (agent default) Timezone for day boundary calculations
verboseLogging false Detailed candidate logging
storage.mode "inline" "inline", "separate", or "both"
storage.separateReports false Write per-phase report files
phases.light.limit 100 Max candidates to process in light phase
phases.light.lookbackDays 2 How far back light reads daily files
phases.deep.limit 10 Max promotions per sweep
phases.deep.minScore 0.8 Minimum weighted score to promote
phases.deep.minRecallCount 3 Minimum recall signals required
phases.deep.minUniqueQueries 3 Minimum distinct query contexts required
phases.deep.recencyHalfLifeDays 14 Recency decay half-life in days
phases.deep.maxAgeDays 30 Maximum candidate age in days
phases.rem.lookbackDays 7 How far back REM reads recall entries
phases.rem.limit 10 Max REM candidates per sweep
phases.rem.minPatternStrength 0.75 Minimum pattern strength for REM themes

Tuning Guide

Too Many Promotions

If MEMORY.md is growing too fast:

  • Raise phases.deep.minScore (try 0.85 or 0.9)
  • Raise phases.deep.minRecallCount (try 5)
  • Lower phases.deep.limit (try 5)
  • Shorten phases.deep.maxAgeDays so older candidates expire sooner

Too Few Promotions

If nothing is getting promoted and you're losing important context:

  • Lower phases.deep.minScore (try 0.7)
  • Lower phases.deep.minRecallCount to 2
  • Increase phases.deep.limit to allow more per sweep
  • Extend phases.deep.maxAgeDays to give candidates more time to accumulate signals

Sweep Frequency

Frequency Use Case
Daily (default) Good for most users. Low resource usage, steady promotion.
Every 6 hours For active agents with high daily memory throughput.
Weekly (0 3 * * 0) For agents that don't accumulate much short-term memory.

Debugging Candidate Scoring

  • Enable verboseLogging: true to see per-candidate scores in the event log
  • Use openclaw memory promote-explain "<query>" to inspect a specific candidate
  • Check memory/.dreams/events.jsonl for detailed phase execution logs

How Dreaming Integrates with the Rest of OpenClaw 

Daily notes + Sessions + Recall traces
            │
            ▼
┌─────────────────────┐
│    Light Phase       │  Ingest, dedupe, stage, record signals
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│     REM Phase        │  Extract themes, record reinforcement signals
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│    Deep Phase        │  Score, threshold, promote → MEMORY.md
└──────────┬──────────┘
           │
           ▼
    Dream Diary (DREAMS.md) — human-readable narrative only
Enter fullscreen mode Exit fullscreen mode

Key integration points:

  • Memory search (openclaw memory search) feeds short-term recall signals into the promotion pipeline during normal agent operation
  • Daily memory files (memory/YYYY-MM-DD.md) are the primary source material for light phase ingestion
  • Session transcripts (~/.openclaw/agents/<id>/sessions/*.jsonl) are the secondary source
  • Gateway startup reconciles the managed cron job, so config changes take effect on next gateway restart
  • The Dreams UI tab in the Gateway shows live status, phase counts, and the dream diary

🤔 FAQ

Q: What exactly is "dreaming" in the context of AI agents?

A: Dreaming is OpenClaw's background memory consolidation system. It mimics a biological sleep cycle — light sleep for ingestion, REM for pattern recognition, and deep sleep for memory promotion. It runs automatically during off-hours to transform noisy short-term signals into curated long-term knowledge.

Q: How is this different from just writing everything to MEMORY.md?

A: Without dreaming, you face binary outcomes: either over-promote (everything lands in MEMORY.md, bloating it with noise) or under-promote (nothing survives, and important patterns are lost). Dreaming uses evidence-based scoring with six weighted signals and three threshold gates to ensure only truly valuable, repeatedly-relevant entries get promoted.

Q: Can I preview what would be promoted before changes happen?

A: Yes. Use openclaw memory promote to preview without applying, or openclaw memory promote-explain "<query>" to understand why a specific entry would or wouldn't make it. You can also check the Gateway's Dreams tab for live status.

Q: How do I know if my configuration is causing too many or too few promotions?

A: Monitor MEMORY.md growth rate. If it's bloaty, raise minScore and minRecallCount. If you're losing important context, lower thresholds and extend maxAgeDays. The events.jsonl log and promote-explain command give you per-candidate visibility.

Q: Is the Dream Diary purely aesthetic or does it serve a function?

A: The Dream Diary is human-only — it's not a promotion source. It's designed for you to browse and understand what OpenClaw found interesting from your sessions. Think of it as a curiosity artifact: a gentle, slightly whimsical narrative that makes the memory consolidation process transparent and engaging.

Q: What happens to candidates that don't pass the threshold gates?

A: They remain in the short-term recall store and continue accumulating signals on future recalls. If they eventually cross all three gates, they'll promote in a future sweep. Entries that exceed maxAgeDays expire and are removed from consideration.

Summary & Next Steps

OpenClaw's Dreaming system brings disciplined curation to AI agent memory management. By separating ingestion (Light), reflection (REM), and promotion (Deep), it ensures your long-term memory stays clean, relevant, and genuinely useful.

Get started in 30 seconds:

/dreaming on
Enter fullscreen mode Exit fullscreen mode

Check back tomorrow morning — your Dream Diary will be waiting in the Gateway Dreams tab.

For deeper tuning, explore openclaw memory promote --dry-run and openclaw memory status --deep to understand what's happening under the hood.

Originally published at: OpenClaw Dreaming Guide 2026

Top comments (0)