openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(sync): mirror docs from openclaw/openclaw@61e61ccc18

Browse Source
This commit is contained in:
openclaw-docs-sync[bot] 2026-04-06 00:19:33 +00:00
parent 14025d43e9
commit 45eba7aa07
8 changed files with 159 additions and 370 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.openclaw-sync/source.json
View File

@ -1,5 +1,5 @@
{
"repository": "openclaw/openclaw",
"sha": "1ee30dc70a768de3cc8a6ac122a695a24308a2a5",
"syncedAt": "2026-04-06T00:18:38.825Z"
"sha": "61e61ccc182f27beaa704927c0255693ce43581f",
"syncedAt": "2026-04-06T00:19:32.448Z"
}

57
docs/cli/memory.md
View File

@ -34,8 +34,6 @@ openclaw memory status --deep --index
openclaw memory status --deep --index --verbose
openclaw memory status --agent main
openclaw memory index --agent main --verbose
openclaw memory promote-explain "router vlan"
openclaw memory rem-harness --json
```
## Options
@ -80,9 +78,9 @@ openclaw memory promote [--apply] [--limit <n>] [--include-promoted]
Full options:
- Ranks short-term candidates from `memory/YYYY-MM-DD.md` using weighted recall signals (`frequency`, `relevance`, `query diversity`, `recency`).
- Uses recall events captured when `memory_search` returns daily-memory hits.
- When dreaming is enabled, `memory-core` auto-manages a cron job for the deep phase that triggers promotion in the background (no manual `openclaw cron add` required).
- Ranks short-term candidates from `memory/YYYY-MM-DD.md` using weighted promotion signals (`frequency`, `relevance`, `query diversity`, `recency`, `consolidation`, `conceptual richness`).
- Uses short-term signals from both memory recalls and daily-ingestion passes, plus light/REM phase reinforcement signals.
- When dreaming is enabled, `memory-core` auto-manages one cron job that runs a full sweep (`light -> REM -> deep`) in the background (no manual `openclaw cron add` required).
- `--agent <id>`: scope to a single agent (default: the default agent).
- `--limit <n>`: max candidates to return/apply.
- `--min-score <n>`: minimum weighted promotion score.
@ -92,54 +90,26 @@ Full options:
- `--include-promoted`: include already promoted candidates in output.
- `--json`: print JSON output.
`memory promote-explain`:
Explain why a specific candidate would or would not promote, with a full score breakdown.
```bash
openclaw memory promote-explain "<selector>"
```
- `<selector>`: candidate key, path fragment, or snippet fragment to match.
- `--agent <id>`: scope to a single agent (default: the default agent).
- `--include-promoted`: include already promoted candidates.
- `--json`: print JSON output.
`memory rem-harness`:
Preview REM reflections, candidate truths, and deep promotion output without writing anything. Useful for staging and debugging the REM phase before it runs for real.
```bash
openclaw memory rem-harness [--json] [--agent <id>] [--include-promoted]
```
- `--agent <id>`: scope to a single agent (default: the default agent).
- `--include-promoted`: include already promoted deep candidates.
- `--json`: print JSON output.
See [Dreaming](/concepts/dreaming) for the full phase model and how REM fits in.
## Dreaming (experimental)
Dreaming is the background memory consolidation system with three cooperative
phases: **light** (organize into `DREAMS.md` in inline mode), **deep**
(promote into `MEMORY.md`), and **REM** (reflect and find patterns in
`DREAMS.md` in inline mode).
phases: **light** (sort/stage short-term material), **deep** (promote durable
facts into `MEMORY.md`), and **REM** (reflect and surface themes).
- Enable with `plugins.entries.memory-core.config.dreaming.enabled: true`.
- Toggle from chat with `/dreaming on|off` or `/dreaming enable|disable light|deep|rem`.
- Each phase runs on its own cron schedule, managed automatically by `memory-core`.
- Only the deep phase writes durable memory to `MEMORY.md`. With default inline storage, Light and REM write to `DREAMS.md`.
- Toggle from chat with `/dreaming on|off` (or inspect with `/dreaming status`).
- Dreaming runs on one managed sweep schedule (`dreaming.frequency`) and executes phases in order: light, REM, deep.
- Only the deep phase writes durable memory to `MEMORY.md`.
- Human-readable phase output and diary entries are written to `DREAMS.md` (or existing `dreams.md`), with optional per-phase reports in `memory/dreaming/<phase>/YYYY-MM-DD.md`.
- Ranking uses weighted signals: recall frequency, retrieval relevance, query diversity, temporal recency, cross-day consolidation, and derived concept richness.
- Promotion re-reads the live daily note before writing to `MEMORY.md`, so edited or deleted short-term snippets do not get promoted from stale recall-store snapshots.
- Scheduled and manual `memory promote` runs share the same deep phase defaults unless you pass CLI threshold overrides.
- Automatic runs fan out across configured memory workspaces.
Default phase schedules:
Default scheduling:
- **Light**: every 6 hours (`0 */6 * * *`), `lookbackDays=2`, `limit=100`
- **Deep**: daily at 3 AM (`0 3 * * *`), `limit=10`, `minScore=0.8`, `minRecallCount=3`, `minUniqueQueries=3`, `recencyHalfLifeDays=14`
- **REM**: weekly, Sunday 5 AM (`0 5 * * 0`), `lookbackDays=7`, `limit=10`
- **Sweep cadence**: `dreaming.frequency = 0 3 * * *`
- **Deep thresholds**: `minScore=0.8`, `minRecallCount=3`, `minUniqueQueries=3`, `recencyHalfLifeDays=14`, `maxAgeDays=30`
Example:
@ -165,6 +135,5 @@ Notes:
- `memory status` includes any extra paths configured via `memorySearch.extraPaths`.
- If effectively active memory remote API key fields are configured as SecretRefs, the command resolves those values from the active gateway snapshot. If gateway is unavailable, the command fails fast.
- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
- Override each phase schedule with `phases.<phase>.cron` and fine-tune deep promotion with `phases.deep.minScore`, `phases.deep.minRecallCount`, `phases.deep.minUniqueQueries`, `phases.deep.recencyHalfLifeDays`, and `phases.deep.maxAgeDays`.
- Set `plugins.entries.memory-core.config.dreaming.verboseLogging` to `true` to emit per-run candidate and apply details into the normal gateway logs while tuning the feature.
- Tune scheduled sweep cadence with `dreaming.frequency`. Deep promotion policy is otherwise internal; use CLI flags on `memory promote` when you need one-off manual overrides.
- See [Dreaming](/concepts/dreaming) for full phase descriptions and configuration reference.

326
docs/concepts/dreaming.md
View File

@ -1,64 +1,109 @@
---
title: "Dreaming (experimental)"
summary: "Background memory consolidation with three cooperative phases: light, deep, and REM"
summary: "Background memory consolidation with light, deep, and REM phases plus a Dream Diary"
read_when:
- You want memory promotion to run automatically
- You want to understand the three dreaming phases
- 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
revisits what came up during conversations and decides what is worth keeping as
durable context.
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 uses three cooperative **phases**, not competing modes. Each phase has
a distinct job, writes to a distinct target, and runs on its own schedule.
Dreaming is **opt-in** and disabled by default.
## The three phases
## What dreaming writes
### Light
Dreaming keeps two kinds of output:
Light dreaming sorts the recent mess. It scans recent memory traces, dedupes
them by Jaccard similarity, clusters related entries, and stages candidate
memories into the shared dreaming trail file (`DREAMS.md`) when inline storage
is enabled.
- **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`.
Light does **not** write anything into `MEMORY.md`. It only organizes and
stages. Think: "what from today might matter later?"
Long-term promotion still writes only to `MEMORY.md`.
### Deep
## Phase model
Deep dreaming decides what becomes durable memory. It runs the real promotion
logic: weighted scoring across six signals, threshold gates, recall count,
unique query diversity, recency decay, and max age filtering.
Dreaming uses three cooperative phases:
Deep is the **only** phase allowed to write durable facts into `MEMORY.md`.
It also owns recovery when memory is thin (health drops below a configured
threshold). Think: "what is true enough to keep?"
| 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 |
### REM
These phases are internal implementation details, not separate user-configured
"modes."
REM dreaming looks for patterns and reflection. It examines recent material,
identifies recurring themes through concept tag clustering, and writes
higher-order notes and reflections into `DREAMS.md` when inline storage is
enabled.
### Light phase
REM writes to `DREAMS.md` in inline mode, **not** `MEMORY.md`.
Its output is interpretive, not canonical. Think: "what pattern am I noticing?"
Light phase ingests recent daily memory signals and recall traces, dedupes them,
and stages candidate lines.
## Hard boundaries
- 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`.
| Phase | Job | Writes to | Does NOT write to |
| ----- | --------- | ------------------------- | ----------------- |
| Light | Organize | `DREAMS.md` (inline mode) | MEMORY.md |
| Deep | Preserve | MEMORY.md | -- |
| REM | Interpret | `DREAMS.md` (inline mode) | 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 all three phases (recommended):
Enable dreaming:
```json
{
@ -76,7 +121,7 @@ Enable all three phases (recommended):
}
```
Enable only deep promotion:
Enable dreaming with a custom sweep cadence:
```json
{
@ -86,11 +131,8 @@ Enable only deep promotion:
"config": {
"dreaming": {
"enabled": true,
"phases": {
"light": { "enabled": false },
"deep": { "enabled": true },
"rem": { "enabled": false }
}
"timezone": "America/Los_Angeles",
"frequency": "0 */6 * * *"
}
}
}
@ -99,205 +141,57 @@ Enable only deep promotion:
}
```
## Configuration
All dreaming settings live under `plugins.entries.memory-core.config.dreaming`
in `openclaw.json`. See [Memory configuration reference](/reference/memory-config#dreaming-experimental)
for the full key list.
### Global settings
| Key | Type | Default | Description |
| ---------------- | --------- | ---------- | ------------------------------------------------------------ |
| `enabled` | `boolean` | `true` | Master switch for all phases |
| `timezone` | `string` | unset | Timezone for schedule evaluation and dreaming date bucketing |
| `verboseLogging` | `boolean` | `false` | Emit detailed per-run dreaming logs |
| `storage.mode` | `string` | `"inline"` | Inline `DREAMS.md`, separate reports, or both |
### Light phase config
| Key | Type | Default | Description |
| ------------------ | ---------- | ------------------------------- | --------------------------------- |
| `enabled` | `boolean` | `true` | Enable light phase |
| `cron` | `string` | `0 */6 * * *` | Schedule (default: every 6 hours) |
| `lookbackDays` | `number` | `2` | How many days of traces to scan |
| `limit` | `number` | `100` | Max candidates to stage per run |
| `dedupeSimilarity` | `number` | `0.9` | Jaccard threshold for dedup |
| `sources` | `string[]` | `["daily","sessions","recall"]` | Data sources to scan |
### Deep phase config
| Key | Type | Default | Description |
| --------------------- | ---------- | ----------------------------------------------- | ------------------------------------ |
| `enabled` | `boolean` | `true` | Enable deep phase |
| `cron` | `string` | `0 3 * * *` | Schedule (default: daily at 3 AM) |
| `limit` | `number` | `10` | Max candidates to promote per cycle |
| `minScore` | `number` | `0.8` | Minimum weighted score for promotion |
| `minRecallCount` | `number` | `3` | Minimum recall count threshold |
| `minUniqueQueries` | `number` | `3` | Minimum distinct query count |
| `recencyHalfLifeDays` | `number` | `14` | Days for recency score to halve |
| `maxAgeDays` | `number` | `30` | Max daily-note age for promotion |
| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | Data sources |
### Deep recovery config
Recovery kicks in when long-term memory health drops below a threshold.
| Key | Type | Default | Description |
| --------------------------------- | --------- | ------- | ------------------------------------------ |
| `recovery.enabled` | `boolean` | `true` | Enable automatic recovery |
| `recovery.triggerBelowHealth` | `number` | `0.35` | Health score threshold to trigger recovery |
| `recovery.lookbackDays` | `number` | `30` | How far back to look for recovery material |
| `recovery.maxRecoveredCandidates` | `number` | `20` | Max candidates to recover per run |
| `recovery.minRecoveryConfidence` | `number` | `0.9` | Minimum confidence for recovery candidates |
| `recovery.autoWriteMinConfidence` | `number` | `0.97` | Auto-write threshold (skip manual review) |
### REM phase config
| Key | Type | Default | Description |
| -------------------- | ---------- | --------------------------- | --------------------------------------- |
| `enabled` | `boolean` | `true` | Enable REM phase |
| `cron` | `string` | `0 5 * * 0` | Schedule (default: weekly, Sunday 5 AM) |
| `lookbackDays` | `number` | `7` | How many days of material to reflect on |
| `limit` | `number` | `10` | Max patterns or themes to write |
| `minPatternStrength` | `number` | `0.75` | Minimum tag co-occurrence strength |
| `sources` | `string[]` | `["memory","daily","deep"]` | Data sources for reflection |
### Execution overrides
Each phase accepts an `execution` block to override global defaults:
| Key | Type | Default | Description |
| ----------------- | -------- | ------------ | ------------------------------ |
| `speed` | `string` | `"balanced"` | `fast`, `balanced`, or `slow` |
| `thinking` | `string` | `"medium"` | `low`, `medium`, or `high` |
| `budget` | `string` | `"medium"` | `cheap`, `medium`, `expensive` |
| `model` | `string` | unset | Override model for this phase |
| `maxOutputTokens` | `number` | unset | Cap output tokens |
| `temperature` | `number` | unset | Sampling temperature (0-2) |
| `timeoutMs` | `number` | unset | Phase timeout in milliseconds |
## Promotion signals (deep phase)
Deep dreaming combines six weighted signals. Promotion requires all configured
threshold gates to pass simultaneously.
| 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 |
## Chat commands
## Slash command
```
/dreaming status # Show phase config and cadence
/dreaming on # Enable all phases
/dreaming off # Disable all phases
/dreaming enable light|deep|rem # Enable a specific phase
/dreaming disable light|deep|rem # Disable a specific phase
/dreaming help # Show usage guide
/dreaming status
/dreaming on
/dreaming off
/dreaming help
```
## CLI commands
## CLI workflow
Preview and apply deep promotions from the command line:
Use CLI promotion for preview or manual apply:
```bash
# 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
# Check dreaming status
openclaw memory status --deep
```
See [memory CLI](/cli/memory) for the full flag reference.
Manual `memory promote` uses deep-phase thresholds by default unless overridden
with CLI flags.
### Preview and explain tools
## Key defaults
Two additional subcommands help you inspect promotion and REM behavior without writing anything:
All settings live under `plugins.entries.memory-core.config.dreaming`.
```bash
# Explain why a candidate would or would not promote
openclaw memory promote-explain "meeting notes"
| Key | Default |
| ----------- | ----------- |
| `enabled` | `false` |
| `frequency` | `0 3 * * *` |
# Preview REM reflections, candidate truths, and deep promotions
openclaw memory rem-harness --json
```
Phase policy, thresholds, and storage behavior are internal implementation
details (not user-facing config).
See [memory CLI](/cli/memory) for full options.
## How it works
### Light phase pipeline
1. Read short-term recall entries from `memory/.dreams/short-term-recall.json`.
2. Filter entries within `lookbackDays` of the current time.
3. Deduplicate by Jaccard similarity (configurable threshold).
4. Sort by average recall score, take up to `limit` entries.
5. Write staged candidates into `DREAMS.md` under a `## Light Sleep` block when
inline storage is enabled.
### Deep phase pipeline
1. Read and rank short-term recall candidates using weighted signals.
2. Apply threshold gates: `minScore`, `minRecallCount`, `minUniqueQueries`.
3. Filter by `maxAgeDays` and apply recency decay.
4. Fan out across configured memory workspaces.
5. Re-read the live daily note before writing (skip stale or deleted snippets).
6. Append qualifying entries to `MEMORY.md` with promoted timestamps.
7. Mark promoted entries to exclude them from future cycles.
8. If health is below `recovery.triggerBelowHealth`, run the recovery pass.
### REM phase pipeline
1. Read recent memory traces within `lookbackDays`.
2. Cluster concept tags by co-occurrence.
3. Filter patterns by `minPatternStrength`.
4. Write themes and reflections into `DREAMS.md` under a `## REM Sleep` block
when inline storage is enabled.
## Scheduling
Each phase manages its own cron job automatically. When dreaming is enabled,
`memory-core` reconciles managed cron jobs on gateway startup. You do not need
to manually create cron entries.
| Phase | Default schedule | Description |
| ----- | ---------------- | ------------------- |
| Light | `0 */6 * * *` | Every 6 hours |
| Deep | `0 3 * * *` | Daily at 3 AM |
| REM | `0 5 * * 0` | Weekly, Sunday 5 AM |
Override any schedule with the phase `cron` key. All schedules honor the global
`timezone` setting.
See [Memory configuration reference](/reference/memory-config#dreaming-experimental)
for the full key list.
## 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.
When enabled, the Gateway **Dreams** tab shows:
Manual `openclaw memory promote` runs use the same deep phase thresholds by
default, so scheduled and on-demand promotion stay aligned unless you pass CLI
overrides.
- 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](/concepts/memory)
- [Memory Search](/concepts/memory-search)
- [Memory configuration reference](/reference/memory-config)
- [memory CLI](/cli/memory)
- [Memory configuration reference](/reference/memory-config)

20
docs/concepts/memory.md
View File

@ -14,12 +14,14 @@ hidden state.
## How it works
Your agent has two places to store memories:
Your agent has three memory-related files:
- **`MEMORY.md`** -- long-term memory. Durable facts, preferences, and
decisions. Loaded at the start of every DM session.
- **`memory/YYYY-MM-DD.md`** -- daily notes. Running context and observations.
Today and yesterday's notes are loaded automatically.
- **`DREAMS.md`** (experimental, optional) -- Dream Diary and dreaming sweep
summaries for human review.
These files live in the agent workspace (default `~/.openclaw/workspace`).
@ -85,20 +87,22 @@ will be saved automatically before the summary happens.
## Dreaming (experimental)
Dreaming is an optional background consolidation pass for memory. It revisits
short-term recalls from daily files (`memory/YYYY-MM-DD.md`), scores them, and
promotes only qualified items into long-term memory (`MEMORY.md`).
Dreaming is an optional background consolidation pass for memory. It collects
short-term signals, scores candidates, and promotes only qualified items into
long-term memory (`MEMORY.md`).
It is designed to keep long-term memory high signal:
- **Opt-in**: disabled by default.
- **Scheduled**: when enabled, `memory-core` manages the recurring task
automatically.
- **Scheduled**: when enabled, `memory-core` auto-manages one recurring cron job
for a full dreaming sweep.
- **Thresholded**: promotions must pass score, recall frequency, and query
diversity gates.
- **Reviewable**: phase summaries and diary entries are written to `DREAMS.md`
for human review.
For mode behavior (`off`, `core`, `rem`, `deep`), scoring signals, and tuning
knobs, see [Dreaming (experimental)](/concepts/dreaming).
For phase behavior, scoring signals, and Dream Diary details, see
[Dreaming (experimental)](/concepts/dreaming).
## CLI

15
docs/gateway/configuration-reference.md
View File

@ -2611,17 +2611,10 @@ See [Local Models](/gateway/local-models). TL;DR: run a large local model via LM
- `plugins.entries.xai.config.xSearch`: xAI X Search (Grok web search) settings.
- `enabled`: enable the X Search provider.
- `model`: Grok model to use for search (e.g. `"grok-4-1-fast"`).
- `plugins.entries.memory-core.config.dreaming`: memory dreaming (experimental) settings. See [Dreaming](/concepts/dreaming) for modes and thresholds.
- `mode`: dreaming cadence preset (`"off"`, `"core"`, `"rem"`, `"deep"`). Default: `"off"`.
- `cron`: optional cron expression override for the dreaming schedule.
- `timezone`: timezone for schedule evaluation (falls back to `agents.defaults.userTimezone`).
- `limit`: maximum candidates to promote per cycle.
- `minScore`: minimum weighted score threshold for promotion.
- `minRecallCount`: minimum recall count threshold.
- `minUniqueQueries`: minimum distinct query count threshold.
- `recencyHalfLifeDays`: days for the recency score to decay by half. Default: `14`.
- `maxAgeDays`: optional maximum daily-note age in days allowed for promotion.
- `verboseLogging`: emit detailed per-run dreaming logs into the normal gateway log stream.
- `plugins.entries.memory-core.config.dreaming`: memory dreaming (experimental) settings. See [Dreaming](/concepts/dreaming) for phases and thresholds.
- `enabled`: master dreaming switch (default `false`).
- `frequency`: cron cadence for each full dreaming sweep (`"0 3 * * *"` by default).
- phase policy and thresholds are implementation details (not user-facing config keys).
- Enabled Claude bundle plugins can also contribute embedded Pi defaults from `settings.json`; OpenClaw applies those as sanitized agent settings, not as raw OpenClaw config patches.
- `plugins.slots.memory`: pick the active memory plugin id, or `"none"` to disable memory plugins.
- `plugins.slots.contextEngine`: pick the active context engine plugin id; defaults to `"legacy"` unless you install and select another engine.

104
docs/reference/memory-config.md
View File

@ -376,92 +376,19 @@ Default is DM-only. `match.keyPrefix` matches the normalized session key;
## Dreaming (experimental)
Dreaming is configured under `plugins.entries.memory-core.config.dreaming`,
not under `agents.defaults.memorySearch`. Dreaming uses three cooperative
phases (light, deep, REM), each with its own schedule and config. For
conceptual details and chat commands, see [Dreaming](/concepts/dreaming).
not under `agents.defaults.memorySearch`.
### Global settings
Dreaming runs as one scheduled sweep and uses internal light/deep/REM phases as
an implementation detail.
| Key | Type | Default | Description |
| ------------------------- | --------- | ---------- | ------------------------------------------------------------ |
| `enabled` | `boolean` | `true` | Master switch for all phases |
| `timezone` | `string` | unset | Timezone for schedule evaluation and dreaming date bucketing |
| `verboseLogging` | `boolean` | `false` | Emit detailed per-run dreaming logs |
| `storage.mode` | `string` | `"inline"` | Inline `DREAMS.md`, separate reports, or both |
| `storage.separateReports` | `boolean` | `false` | Write separate report files per phase |
For conceptual behavior and slash commands, see [Dreaming](/concepts/dreaming).
### Light phase (`phases.light`)
### User settings
Scans recent traces, dedupes, and stages candidates into `DREAMS.md` when
inline storage is enabled.
Does **not** write to `MEMORY.md`.
| Key | Type | Default | Description |
| ------------------ | ---------- | ------------------------------- | --------------------------- |
| `enabled` | `boolean` | `true` | Enable light phase |
| `cron` | `string` | `0 */6 * * *` | Schedule (every 6 hours) |
| `lookbackDays` | `number` | `2` | Days of traces to scan |
| `limit` | `number` | `100` | Max candidates to stage |
| `dedupeSimilarity` | `number` | `0.9` | Jaccard threshold for dedup |
| `sources` | `string[]` | `["daily","sessions","recall"]` | Data sources |
### Deep phase (`phases.deep`)
Promotes qualified candidates into `MEMORY.md`. The **only** phase that
writes durable facts. Also owns recovery when memory is thin.
| Key | Type | Default | Description |
| --------------------- | ---------- | ----------------------------------------------- | ------------------------------------ |
| `enabled` | `boolean` | `true` | Enable deep phase |
| `cron` | `string` | `0 3 * * *` | Schedule (daily at 3 AM) |
| `limit` | `number` | `10` | Max candidates to promote per cycle |
| `minScore` | `number` | `0.8` | Minimum weighted score for promotion |
| `minRecallCount` | `number` | `3` | Minimum recall count threshold |
| `minUniqueQueries` | `number` | `3` | Minimum distinct query count |
| `recencyHalfLifeDays` | `number` | `14` | Days for recency score to halve |
| `maxAgeDays` | `number` | `30` | Max daily-note age for promotion |
| `sources` | `string[]` | `["daily","memory","sessions","logs","recall"]` | Data sources |
#### Deep recovery (`phases.deep.recovery`)
| Key | Type | Default | Description |
| ------------------------ | --------- | ------- | ------------------------------------------ |
| `enabled` | `boolean` | `true` | Enable automatic recovery |
| `triggerBelowHealth` | `number` | `0.35` | Health score threshold to trigger recovery |
| `lookbackDays` | `number` | `30` | How far back to look for recovery material |
| `maxRecoveredCandidates` | `number` | `20` | Max candidates to recover per run |
| `minRecoveryConfidence` | `number` | `0.9` | Minimum confidence for recovery candidates |
| `autoWriteMinConfidence` | `number` | `0.97` | Auto-write threshold (skip manual review) |
### REM phase (`phases.rem`)
Writes themes, reflections, and pattern notes into `DREAMS.md` when inline
storage is enabled.
Does **not** write to `MEMORY.md`.
| Key | Type | Default | Description |
| -------------------- | ---------- | --------------------------- | ---------------------------------- |
| `enabled` | `boolean` | `true` | Enable REM phase |
| `cron` | `string` | `0 5 * * 0` | Schedule (weekly, Sunday 5 AM) |
| `lookbackDays` | `number` | `7` | Days of material to reflect on |
| `limit` | `number` | `10` | Max patterns or themes to write |
| `minPatternStrength` | `number` | `0.75` | Minimum tag co-occurrence strength |
| `sources` | `string[]` | `["memory","daily","deep"]` | Data sources for reflection |
### Execution overrides
Each phase accepts an `execution` block. There is also a global
`execution.defaults` block that phases inherit from.
| Key | Type | Default | Description |
| ----------------- | -------- | ------------ | ------------------------------ |
| `speed` | `string` | `"balanced"` | `fast`, `balanced`, or `slow` |
| `thinking` | `string` | `"medium"` | `low`, `medium`, or `high` |
| `budget` | `string` | `"medium"` | `cheap`, `medium`, `expensive` |
| `model` | `string` | unset | Override model for this phase |
| `maxOutputTokens` | `number` | unset | Cap output tokens |
| `temperature` | `number` | unset | Sampling temperature (0-2) |
| `timeoutMs` | `number` | unset | Phase timeout in milliseconds |
| Key | Type | Default | Description |
| ----------- | --------- | ----------- | ------------------------------------------------- |
| `enabled` | `boolean` | `false` | Enable or disable dreaming entirely |
| `frequency` | `string` | `0 3 * * *` | Optional cron cadence for the full dreaming sweep |
### Example
@ -473,12 +400,7 @@ Each phase accepts an `execution` block. There is also a global
config: {
dreaming: {
enabled: true,
timezone: "America/New_York",
phases: {
light: { cron: "0 */4 * * *", lookbackDays: 3 },
deep: { minScore: 0.85, recencyHalfLifeDays: 21 },
rem: { lookbackDays: 14 },
},
frequency: "0 3 * * *",
},
},
},
@ -486,3 +408,9 @@ Each phase accepts an `execution` block. There is also a global
},
}
```
Notes:
- Dreaming writes machine state to `memory/.dreams/`.
- Dreaming writes human-readable narrative output to `DREAMS.md` (or existing `dreams.md`).
- The light/deep/REM phase policy and thresholds are internal behavior, not user-facing config.

2
docs/tools/slash-commands.md
View File

@ -122,7 +122,7 @@ Text + native (when enabled):
- `/model <name>` (alias: `/models`; or `/<alias>` from `agents.defaults.models.*.alias`)
- `/queue <mode>` (plus options like `debounce:2s cap:25 drop:summarize`; send `/queue` to see current settings)
- `/bash <command>` (host-only; alias for `! <command>`; requires `commands.bash: true` + `tools.elevated` allowlists)
- `/dreaming [on|off|status|help]` or `/dreaming [enable|disable] [light|deep|rem]` (toggle dreaming phases or show status; see [Dreaming](/concepts/dreaming))
- `/dreaming [on|off|status|help]` (toggle global dreaming or show status; see [Dreaming](/concepts/dreaming))
Text-only:

1
docs/web/control-ui.md
View File

@ -87,6 +87,7 @@ The Control UI can localize itself on first load based on your browser locale, a
- Channels: built-in plus bundled/external plugin channels status, QR login, and per-channel config (`channels.status`, `web.login.*`, `config.patch`)
- Instances: presence list + refresh (`system-presence`)
- Sessions: list + per-session model/thinking/fast/verbose/reasoning overrides (`sessions.list`, `sessions.patch`)
- Dreams: dreaming status, enable/disable toggle, and Dream Diary reader (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
- Cron jobs: list/add/edit/run/enable/disable + run history (`cron.*`)
- Skills: status, enable/disable, install, API key updates (`skills.*`)
- Nodes: list + caps (`node.list`)