Remote OpenClaw Blog

OpenClaw Dreaming Guide: Memory Consolidation Explained

14 min read · 7 April 2026

What Is Dreaming?

Dreaming is OpenClaw's autonomous memory consolidation system, inspired by how biological sleep consolidates short-term memories into long-term storage. It takes the raw, unstructured conversation history from your agent's daily interactions and distills it into structured, persistent knowledge that improves your agent's performance over time.

Without Dreaming, your OpenClaw agent treats every session as a fresh start. It reads MEMORY.md for persistent context, but that file only contains what you or previous sessions have manually written to it. Valuable patterns — your preferences, recurring workflows, project-specific knowledge, corrections you have made — live only in conversation logs that grow stale and eventually get pruned.

With Dreaming enabled, your agent processes those conversation logs overnight, extracts the valuable signal, and writes it to MEMORY.md automatically. Over days and weeks, your agent builds an increasingly rich understanding of your work patterns, preferences, and domain knowledge — without you needing to manually curate its memory.

Dreaming graduated from beta to General Availability in OpenClaw 4.5 (April 6, 2026) after six months of testing across thousands of operators. It is now production-ready and enabled by default in new installations.

Why Dreaming Matters for Operators

The practical impact of Dreaming is that your agent gets better at its job without you actively teaching it. Here are concrete examples of what Dreaming captures and how it improves agent performance:

• Coding style preferences: If you consistently correct your agent's code to use specific patterns (e.g., preferring early returns over nested conditionals, using specific naming conventions), Dreaming captures these corrections and your agent starts writing code your way by default.
• Project context: Dreaming extracts project-specific knowledge — file structures, API patterns, team conventions, deployment processes — from your conversations. Instead of re-explaining your project setup every session, the knowledge persists in MEMORY.md.
• Communication style: If you prefer concise responses over verbose explanations, or technical depth over simplifications, Dreaming picks up on these patterns and adjusts the agent's default communication style.
• Workflow sequences: Recurring multi-step workflows — "check the staging server, run tests, deploy to production, notify the team" — get captured as known sequences. The agent can execute them more efficiently because it has seen the full flow before.
• Error corrections: When you correct factual mistakes or update outdated information, Dreaming promotes the correction to persistent memory so the agent does not make the same mistake again.

The compounding effect is significant. After a month of Dreaming, operators consistently report that their agents feel noticeably more capable and aligned with their working style. The agent "knows" things it was never explicitly told — because it learned them from the pattern of your interactions.

The Three Phases of Dreaming

Dreaming runs in three sequential phases, each serving a distinct purpose. The naming deliberately echoes biological sleep phases because the functional analogy is surprisingly accurate.

Phase 1: Light Sleep (Scan and Tag)

Light Sleep is the first pass over your conversation history. The agent scans all conversations since the last Dreaming session and tags content by category:

• Preferences: Explicit or implicit statements about how you like things done
• Facts: Project-specific information, technical details, names, dates, configurations
• Corrections: Instances where you corrected the agent's output or understanding
• Workflows: Multi-step processes and sequences
• Decisions: Choices you made and the reasoning behind them
• Noise: Casual conversation, debugging back-and-forth, and other content with no long-term value

Light Sleep is fast — it processes a full day's conversations in under 30 seconds for most operators. The output is a tagged inventory of candidate memories, each marked with a category and a preliminary relevance score.

Phase 2: Deep Sleep (Score and Rank)

Deep Sleep takes the tagged inventory from Light Sleep and applies the weighted scoring algorithm (detailed in the next section) to rank each candidate memory by importance. This is where Dreaming decides what matters enough to promote to permanent memory.

During Deep Sleep, the agent also checks for duplicates and conflicts with existing MEMORY.md content. If a candidate memory contradicts something already in MEMORY.md, Deep Sleep flags it as a potential update rather than a new entry. If a candidate memory is a more detailed version of an existing memory, Deep Sleep marks it for merging.

Deep Sleep is the most computationally intensive phase. For a typical day's conversations, it takes 1-3 minutes. For operators with very high conversation volumes, it can take up to 10 minutes.

Phase 3: REM (Synthesize and Write)

REM is the final phase where Dreaming takes action. It takes the scored, deduplicated, conflict-resolved memories from Deep Sleep and writes them to MEMORY.md.

REM does not simply append raw text. It synthesizes memories into well-structured, concise entries that integrate with the existing content of MEMORY.md. If a new memory relates to an existing section, REM adds it to that section. If it represents a new topic, REM creates a new section with appropriate headers.

REM also handles memory decay — entries in MEMORY.md that have not been reinforced by recent conversations are flagged for potential removal. Dreaming does not delete them automatically (that would be too aggressive) but marks them with a low-confidence tag that the operator can review.

The name "REM" is apt: just as biological REM sleep is when the brain forms new neural connections and consolidates learning, OpenClaw's REM phase is when new knowledge is permanently integrated into the agent's persistent memory.

The Weighted Scoring System

Dreaming uses a multi-factor scoring algorithm to determine which candidate memories deserve promotion to MEMORY.md. Understanding the scoring factors helps you influence what your agent remembers.

The threshold for promotion is a score of 0.6 (on a 0-1 scale). Memories scoring above 0.6 are written to MEMORY.md. Memories scoring between 0.4 and 0.6 are held in a "pending" state and reconsidered in the next Dreaming session — if they are reinforced again, their score increases. Memories below 0.4 are discarded.

You can influence scoring in several ways:

• Repeat important information: Mentioning something across multiple conversations increases its frequency score.
• Correct explicitly: When the agent gets something wrong, saying "No, the correct approach is X" carries a high correction weight.
• Use importance markers: Saying "remember this" or "this is important" triggers the explicit importance factor.
• Use the promote command: Manually promoting a memory bypasses scoring entirely and writes it directly to MEMORY.md.

How MEMORY.md Works

MEMORY.md is a Markdown file that lives in your OpenClaw configuration directory (typically ~/.openclaw/MEMORY.md or in your project's .openclaw/MEMORY.md). It is the persistent memory store that your agent reads at the start of every session.

The file follows a structured format with sections and entries:

# MEMORY.md

## Project: webapp-frontend
- Uses React 18 with TypeScript
- Styling: Tailwind CSS v4, no custom CSS unless necessary
- Testing: Vitest + React Testing Library
- Deploy target: Vercel, auto-deploy from main branch

## Coding Preferences
- Prefer early returns over nested conditionals
- Use named exports, not default exports
- Always destructure props in function signatures
- Error handling: use Result type pattern, not try/catch

## Communication Style
- Keep responses concise — max 3 paragraphs unless asked for detail
- Always show code examples, not just descriptions
- Use bullet points for lists of 3+ items

## Team Context
- Sarah handles backend API (FastAPI + PostgreSQL)
- Mike owns the CI/CD pipeline (GitHub Actions)
- Standups at 9:30 AM PST daily

Dreaming reads this file, respects its existing structure, and adds new entries in the appropriate sections. If Dreaming discovers information about coding preferences, it adds to the "Coding Preferences" section rather than creating a duplicate section.

You can manually edit MEMORY.md at any time. Your manual edits are respected — Dreaming will not overwrite or remove content you have explicitly written. The file is designed to be a collaborative document between you and your agent's Dreaming process.

For detailed configuration of MEMORY.md paths, scoping, and project-level memory, see the OpenClaw Memory Configuration Guide.

The Dream Diary

The Dream Diary is an audit log introduced in OpenClaw 4.5 that records every Dreaming session in detail. It answers the question operators always ask: "What did Dreaming do last night?"

The Dream Diary is stored at ~/.openclaw/dream-diary.log and contains structured entries for each session:

[2026-04-06T03:00:12Z] Dreaming session started
[2026-04-06T03:00:12Z] Light Sleep: Scanning 47 conversations (128,342 tokens)
[2026-04-06T03:00:38Z] Light Sleep complete: 23 candidate memories tagged
[2026-04-06T03:00:38Z] Deep Sleep: Scoring 23 candidates
[2026-04-06T03:01:45Z] Deep Sleep complete: 8 candidates above threshold (0.6)
[2026-04-06T03:01:45Z] REM: Writing 8 memories to MEMORY.md
[2026-04-06T03:02:03Z] PROMOTED: [Preferences] "Use pnpm instead of npm for all projects" (score: 0.82)
[2026-04-06T03:02:03Z] PROMOTED: [Facts] "Production database is on Supabase, project ID: xyz123" (score: 0.71)
[2026-04-06T03:02:03Z] UPDATED: [Coding] "Error handling preference" — merged with existing entry (score: 0.88)
[2026-04-06T03:02:03Z] DISCARDED: [Noise] "Discussion about lunch options" (score: 0.12)
[2026-04-06T03:02:03Z] PENDING: [Workflow] "Deployment checklist sequence" (score: 0.54) — will reconsider next session
[2026-04-06T03:02:18Z] Dreaming session complete: 6 promoted, 2 updated, 12 discarded, 3 pending

The Dream Diary is invaluable for understanding how your agent's memory evolves over time. You can review it daily to catch any incorrect promotions (and manually correct them in MEMORY.md) or weekly to get a sense of what your agent is learning.

{
  "dreaming": {
    "enabled": true
  }
}

{
  "dreaming": {
    "enabled": true,
    "schedule": "0 3 * * *",
    "history_window": "24h",
    "model": "claude-sonnet-4",
    "threshold": 0.6,
    "max_promotions_per_session": 20,
    "memory_path": "~/.openclaw/MEMORY.md",
    "diary_path": "~/.openclaw/dream-diary.log",
    "mode": "auto"
  }
}

# Default: Run at 3AM every day
"schedule": "0 3 * * *"

# Run at 2AM on weekdays only
"schedule": "0 2 * * 1-5"

# Run every 12 hours
"schedule": "0 */12 * * *"

# Run at midnight Sunday for weekly consolidation
"schedule": "0 0 * * 0"

# In an OpenClaw session
/dreaming

# Output:
# Starting Dreaming session...
# Light Sleep: Scanning 12 conversations (34,218 tokens)
# Deep Sleep: Scoring 8 candidates
# REM: Promoting 3 memories to MEMORY.md
# Session complete. Check dream-diary.log for details.

# In an OpenClaw session
promote "Always use pnpm, never npm, for this project"

# Output:
# Promoted to MEMORY.md under [Preferences]:
# "Always use pnpm, never npm, for this project"

# Dry-run REM phase with test candidates
rem-harness --dry-run --input candidates.json

# Output:
# [DRY RUN] Would promote 4 of 7 candidates:
# 1. [Facts] "API rate limit is 100 req/min on free tier" (score: 0.78)
# 2. [Preferences] "Use kebab-case for CSS class names" (score: 0.72)
# 3. [Workflow] "Deploy sequence: test → build → deploy → notify" (score: 0.69)
# 4. [Corrections] "The staging URL is staging.example.com, not stage.example.com" (score: 0.91)
# [DRY RUN] No changes written to MEMORY.md

{
  "dreaming": {
    "enabled": true,
    "model": "gpt-4.1-mini"
  }
}

{
  "dreaming": {
    "enabled": true,
    "mode": "review"
  }
}

# In your project's .openclaw/config.json
{
  "dreaming": {
    "enabled": true,
    "memory_path": "./.openclaw/MEMORY.md"
  }
}