What is OpenClaw dreaming? DREAMS.md and the 3 a.m. memory run, explained

OpenClaw 2 consolidates memory overnight: light, REM and deep phases at 03:00 by default, a Dream Diary in DREAMS.md, promotions into MEMORY.md. What it does, what it costs, and the keys that tune or stop it.

The short answer

Dreaming is OpenClaw’s background memory consolidation, and since OpenClaw 2 it is on by default. Once a day, at 03:00 by default, the agent runs up to three short background turns (a light, a REM and a deep phase) that sift what it noticed recently, write a diary entry to DREAMS.md in the workspace, and, in the deep phase only, promote the strongest items into MEMORY.md. It runs on your agent’s default model unless you point it at another, so it costs a few model calls a night. Turn it off with one key, dreaming.enabled: false, in the memory-core plugin’s config.

What “dreaming” means here

The docs define it plainly: dreaming “moves strong short-term signals into durable memory while keeping the process explainable and reviewable.” Your agent’s conversations leave a trail of things it looked up, was told, and reached for again. Most of that should fade. Some of it is worth keeping without anyone typing “remember this”. Dreaming is the job that decides which is which, overnight, when nobody is talking to the agent.

The three phases run in order. Light stages recent material and removes duplicates. REM builds theme summaries and records how often each item was reinforced. Both are explicitly forbidden from touching MEMORY.md. Deep ranks the candidates and promotes the ones that clear every gate: a minimum score, a minimum recall count, and a minimum number of distinct queries that reached for them. The “grounded” in OpenClaw’s “grounded dreaming” refers to a separate lane for material replayed from past sessions or backfilled daily notes, so the diary shows which entries came from history rather than from live conversation. One safety rule is worth knowing: before it builds the consolidation prompt, the plugin drops any candidate whose provenance is marked untrusted or system, so a web page your agent read cannot dream itself into permanent memory.

What lands on disk

DREAMS.md at the workspace root is the human side: a dated Dream Diary you can open and read. Phase reports can appear under memory/dreaming/, one dated file per phase. The machine state (recall store, phase signals, checkpoints, and the pre-images of anything it rewrote) lives in the plugin’s SQLite store. And MEMORY.md changes only when the deep phase promotes something.

Expect the files before there is anything in them. On a pod we run, the first 03:00 sweep after installation created workspace/memory/dreaming/ with five entries and a 177-byte DREAMS.md while reporting candidates=0, applied=0: the machinery ran, found nothing worth promoting, and said so. That is normal for a young agent. How OpenClaw memory works covers the files dreaming feeds into.

The fresh-install quirk

There is one interaction to know about if you install OpenClaw and do not talk to it the same day. The bootstrapping docs say a workspace “counts as configured once SOUL.md, IDENTITY.md, or USER.md has diverged from its starter template, or a memory/ folder exists.” Dreaming creates that folder at 03:00. So an agent that has never been spoken to by then wakes up counted as configured: it skips the hatching conversation, deletes BOOTSTRAP.md, and answers your first message as an ordinary assistant with the default identity. We watched exactly this on a pod that was installed one morning and left alone overnight (OpenClaw 2026.9.1). The fix is either to say hello before the first 03:00 or to write the identity files yourself; nothing is lost except the guided first conversation.

What it costs

Each phase is a background model turn on the workspace agent’s default model unless dreaming.model names another. The plugin shares a background budget with the rest of the system: “at most three runs in total, with up to three available to memory-core,” and if the configured model is unavailable it retries once on the agent’s default. Three turns a night is small next to a day of conversation, but the model matters more than the count: a route with prompt caching makes these turns cost a fraction of a cent, and one without it can cost ten times as much for the same work. The model guide has the measured figures. If you run a metered key and want the cheapest possible night, set dreaming.model to a small model; the consolidation prompt does not need a frontier one.

Tuning it, reading it, turning it off

The keys live under plugins.entries.memory-core.config:

dreaming.enabled     # true by default
dreaming.frequency   # cron, default "0 3 * * *"
dreaming.timezone    # the clock the cron reads; servers usually run UTC
dreaming.model       # a model id; unset = the agent's default
phases.deep.maxPriorEntryLossFraction   # 0.25
phases.deep.maxPromotedSnippetTokens    # 160

The timezone matters more than it looks. A server’s clock is almost always UTC, so “03:00” is 03:00 UTC unless you set dreaming.timezone: late evening in the Americas, mid-morning in East Asia. And because dreaming is a Gateway job, it runs only while the Gateway is running: an always-on machine dreams every night, a laptop that sleeps at 3 a.m. mostly does not.

You can also run the same machinery by hand, which is the best way to understand it:

openclaw memory promote                    # dry run: what would be promoted
openclaw memory promote --apply            # do it now
openclaw memory promote-explain "<query>"  # why an item would or would not make it
openclaw memory rem-harness                # exercise the REM phase

The two deep-phase limits are the guard rails: one promotion pass may not discard more than a quarter of the prior entries, and each promoted snippet is capped at 160 tokens. If your MEMORY.md is hand-curated and you would rather nothing edited it overnight, turning dreaming off costs you only the automatic half; the agent still writes memory when you ask it to.