diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 62ec18809..5be1c3fc2 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -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" } diff --git a/docs/cli/memory.md b/docs/cli/memory.md index 3b198ee14..24621ad56 100644 --- a/docs/cli/memory.md +++ b/docs/cli/memory.md @@ -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 ] [--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 `: scope to a single agent (default: the default agent). - `--limit `: max candidates to return/apply. - `--min-score `: 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 "" -``` - -- ``: candidate key, path fragment, or snippet fragment to match. -- `--agent `: 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 ] [--include-promoted] -``` - -- `--agent `: 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//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..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. diff --git a/docs/concepts/dreaming.md b/docs/concepts/dreaming.md index 706202834..2506b4697 100644 --- a/docs/concepts/dreaming.md +++ b/docs/concepts/dreaming.md @@ -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//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) diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index f77fa5631..ec4cfb446 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -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 diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index a8ada9ad0..9fe57359b 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -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. diff --git a/docs/reference/memory-config.md b/docs/reference/memory-config.md index 70e60bf1f..9d25195f7 100644 --- a/docs/reference/memory-config.md +++ b/docs/reference/memory-config.md @@ -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. diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md index 30a875810..c70e1e8a7 100644 --- a/docs/tools/slash-commands.md +++ b/docs/tools/slash-commands.md @@ -122,7 +122,7 @@ Text + native (when enabled): - `/model ` (alias: `/models`; or `/` from `agents.defaults.models.*.alias`) - `/queue ` (plus options like `debounce:2s cap:25 drop:summarize`; send `/queue` to see current settings) - `/bash ` (host-only; alias for `! `; 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: diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index 80fa027a1..3016d136c 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -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`)