openclaw/docs/concepts/dreaming.md

title	summary	read_when
Dreaming (experimental)	Background promotion from short-term recall into long-term memory	You want memory promotion to run automatically You want to understand dreaming modes and thresholds You want to tune consolidation without polluting MEMORY.md

Dreaming (experimental)

Dreaming is the background memory consolidation pass in memory-core.

It is called "dreaming" because the system revisits what came up during the day and decides what is worth keeping as durable context.

Dreaming is experimental, opt-in, and off by default.

What dreaming does

1. Tracks short-term recall events from memory_search hits in memory/YYYY-MM-DD.md.
2. Scores those recall candidates with weighted signals.
3. Promotes only qualified candidates into MEMORY.md.

This keeps long-term memory focused on durable, repeated context instead of one-off details.

Promotion signals

Dreaming combines six signals:

• Frequency: how often the same candidate was recalled.
• Relevance: how strong recall scores were when it was retrieved.
• Query diversity: how many distinct query intents surfaced it.
• Recency: temporal weighting over recent recalls.
• Consolidation: whether recalls repeated across distinct days instead of one burst.
• Conceptual richness: derived concept tags from the note path and snippet text.

Promotion requires all configured threshold gates to pass, not just one signal.

Signal weights

Signal	Weight	Description
Frequency	0.24	How often the same entry was recalled
Relevance	0.30	Average recall scores when retrieved
Query diversity	0.15	Count of distinct query intents that surfaced it
Recency	0.15	Temporal decay (recencyHalfLifeDays, default 14)
Consolidation	0.10	Reward recalls repeated across multiple days
Conceptual richness	0.06	Reward entries with richer derived concept tags

How it works

1. Recall tracking -- Every memory_search hit is recorded to memory/.dreams/short-term-recall.json with recall count, scores, query hash, recall days, and concept tags.
2. Scheduled scoring -- On the configured cadence, candidates are ranked using weighted signals. All threshold gates must pass simultaneously.
3. Workspace fan-out -- Each dreaming cycle runs once per configured memory workspace, so one agent's sessions consolidate into that agent's memory workspace.
4. Promotion -- Before appending anything, dreaming re-reads the current daily note and skips candidates whose source snippet no longer exists. Qualifying live entries are appended to MEMORY.md with a promoted timestamp.
5. Cleanup -- Already-promoted entries are filtered from future cycles. A file lock prevents concurrent runs.

Modes

dreaming.mode controls cadence and default thresholds:

Mode	Cadence	minScore	minRecallCount	minUniqueQueries	recencyHalfLifeDays
off	Disabled	--	--	--	--
core	Daily 3 AM	0.75	3	2	14
rem	Every 6 hours	0.85	4	3	14
deep	Every 12 hours	0.80	3	3	14

Scheduling model

When dreaming is enabled, memory-core manages the recurring schedule automatically. You do not need to manually create a cron job for this feature.

You can still tune behavior with explicit overrides such as:

• dreaming.cron (cron expression)
• dreaming.timezone
• dreaming.limit
• dreaming.minScore
• dreaming.minRecallCount
• dreaming.minUniqueQueries
• dreaming.recencyHalfLifeDays
• dreaming.maxAgeDays
• dreaming.verboseLogging

Configure

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "mode": "core",
            "recencyHalfLifeDays": 21,
            "maxAgeDays": 30
          }
        }
      }
    }
  }
}

Chat commands

Switch modes and check status from chat:

/dreaming core          # Switch to core mode (nightly)
/dreaming rem           # Switch to rem mode (every 6h)
/dreaming deep          # Switch to deep mode (every 12h)
/dreaming off           # Disable dreaming
/dreaming status        # Show current config and cadence
/dreaming help          # Show mode guide

CLI commands

Preview and apply promotions from the command line:

# Preview promotion candidates
openclaw memory promote

# Apply promotions to MEMORY.md
openclaw memory promote --apply

# Limit preview count
openclaw memory promote --limit 5

# Include already-promoted entries
openclaw memory promote --include-promoted

# Manual runs inherit dreaming thresholds unless you override them
openclaw memory promote --apply

# Check dreaming status
openclaw memory status --deep

See memory CLI for the full flag reference.

Dreams UI

When dreaming is enabled, the Gateway sidebar shows a Dreams tab with memory stats (short-term count, long-term count, promoted count) and the next scheduled cycle time. Daily counters honor dreaming.timezone when set and otherwise fall back to the configured user timezone.

Manual openclaw memory promote runs use the same dreaming thresholds by default, so scheduled and on-demand promotion stay aligned unless you pass CLI overrides.

Further reading

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