From a780151fd1aaabf1f576e21af45aaa0fb84659a2 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Wed, 15 Apr 2026 11:46:25 +0100 Subject: [PATCH] docs: add experimental-features page and de-experimentalize dreaming --- docs/.i18n/glossary.zh-CN.json | 4 +++ docs/cli/memory.md | 2 +- docs/concepts/dreaming.md | 6 ++-- docs/concepts/experimental-features.md | 47 +++++++++++++++++++++++++ docs/concepts/memory.md | 8 ++--- docs/docs.json | 3 +- docs/gateway/configuration-reference.md | 2 +- docs/gateway/local-models.md | 3 +- docs/reference/memory-config.md | 2 +- 9 files changed, 65 insertions(+), 12 deletions(-) create mode 100644 docs/concepts/experimental-features.md diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index cc591c0b98f..736d59a6c76 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -83,6 +83,10 @@ "source": "Diffs", "target": "Diffs" }, + { + "source": "Dreaming", + "target": "Dreaming" + }, { "source": "Capability Cookbook", "target": "能力扩展手册" diff --git a/docs/cli/memory.md b/docs/cli/memory.md index 0e2d8bbd08d..e6a964ed70a 100644 --- a/docs/cli/memory.md +++ b/docs/cli/memory.md @@ -121,7 +121,7 @@ openclaw memory rem-harness [--agent ] [--include-promoted] [--json] - `--include-promoted`: include already promoted deep candidates. - `--json`: print JSON output. -## Dreaming (experimental) +## Dreaming Dreaming is the background memory consolidation system with three cooperative phases: **light** (sort/stage short-term material), **deep** (promote durable diff --git a/docs/concepts/dreaming.md b/docs/concepts/dreaming.md index 49f548e6af0..719cb3e62e5 100644 --- a/docs/concepts/dreaming.md +++ b/docs/concepts/dreaming.md @@ -1,5 +1,5 @@ --- -title: "Dreaming (experimental)" +title: "Dreaming" summary: "Background memory consolidation with light, deep, and REM phases plus a Dream Diary" read_when: - You want memory promotion to run automatically @@ -7,7 +7,7 @@ read_when: - You want to tune consolidation without polluting MEMORY.md --- -# Dreaming (experimental) +# Dreaming Dreaming is the background memory consolidation system in `memory-core`. It helps OpenClaw move strong short-term signals into durable memory while @@ -215,7 +215,7 @@ All settings live under `plugins.entries.memory-core.config.dreaming`. Phase policy, thresholds, and storage behavior are internal implementation details (not user-facing config). -See [Memory configuration reference](/reference/memory-config#dreaming-experimental) +See [Memory configuration reference](/reference/memory-config#dreaming) for the full key list. ## Dreams UI diff --git a/docs/concepts/experimental-features.md b/docs/concepts/experimental-features.md new file mode 100644 index 00000000000..013902b26f1 --- /dev/null +++ b/docs/concepts/experimental-features.md @@ -0,0 +1,47 @@ +--- +title: "Experimental Features" +summary: "What experimental flags mean in OpenClaw and which ones are currently documented" +read_when: + - You see an `.experimental` config key and want to know whether it is stable + - You want to try preview runtime features without confusing them with normal defaults + - You want one place to find the currently documented experimental flags +--- + +# Experimental features + +Experimental features in OpenClaw are **opt-in preview surfaces**. They are +behind explicit flags because they still need real-world mileage before they +deserve a stable default or a long-lived public contract. + +Treat them differently from normal config: + +- Keep them **off by default** unless the related doc tells you to try one. +- Expect **shape and behavior to change** faster than stable config. +- Prefer the stable path first when one already exists. +- If you are rolling OpenClaw out broadly, test experimental flags in a smaller + environment before baking them into a shared baseline. + +## Currently documented flags + +| Surface | Key | Use it when | More | +| ------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| Local model runtime | `agents.defaults.experimental.localModelLean` | A smaller or stricter local backend chokes on OpenClaw's full default tool surface | [Local Models](/gateway/local-models) | +| Memory search | `agents.defaults.memorySearch.experimental.sessionMemory` | You want `memory_search` to index prior session transcripts and accept the extra storage/indexing cost | [Memory configuration reference](/reference/memory-config#session-memory-search-experimental) | +| Structured planning tool | `tools.experimental.planTool` | You want the structured `update_plan` tool exposed for multi-step work tracking in compatible runtimes and UIs | [Gateway configuration reference](/gateway/configuration-reference#toolsexperimental) | + +## Local model lean mode + +`agents.defaults.experimental.localModelLean: true` is a pressure-release valve +for weaker local-model setups. It trims heavyweight default tools like +`browser`, `cron`, and `message` so the prompt shape is smaller and less brittle +for small-context or stricter OpenAI-compatible backends. + +That is intentionally **not** the normal path. If your backend handles the full +runtime cleanly, leave this off. + +## Experimental does not mean hidden + +If a feature is experimental, OpenClaw should say so plainly in docs and in the +config path itself. What it should **not** do is smuggle preview behavior into a +stable-looking default knob and pretend that is normal. That's how config +surfaces get messy. diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index 09354593c72..423583a092b 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -20,7 +20,7 @@ Your agent has three memory-related files: 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 +- **`DREAMS.md`** (optional) -- Dream Diary and dreaming sweep summaries for human review, including grounded historical backfill entries. These files live in the agent workspace (default `~/.openclaw/workspace`). @@ -114,7 +114,7 @@ important facts in the conversation that are not yet written to a file, they will be saved automatically before the summary happens. -## Dreaming (experimental) +## Dreaming Dreaming is an optional background consolidation pass for memory. It collects short-term signals, scores candidates, and promotes only qualified items into @@ -131,7 +131,7 @@ It is designed to keep long-term memory high signal: for human review. For phase behavior, scoring signals, and Dream Diary details, see -[Dreaming (experimental)](/concepts/dreaming). +[Dreaming](/concepts/dreaming). ## Grounded backfill and live promotion @@ -184,7 +184,7 @@ openclaw memory index --force # Rebuild the index - [Memory Wiki](/plugins/memory-wiki) -- compiled knowledge vault and wiki-native tools - [Memory Search](/concepts/memory-search) -- search pipeline, providers, and tuning -- [Dreaming (experimental)](/concepts/dreaming) -- background promotion +- [Dreaming](/concepts/dreaming) -- background promotion from short-term recall to long-term memory - [Memory configuration reference](/reference/memory-config) -- all config knobs - [Compaction](/concepts/compaction) -- how compaction interacts with memory diff --git a/docs/docs.json b/docs/docs.json index fc7bb058e0f..326520299a8 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1062,7 +1062,8 @@ "concepts/agent-workspace", "concepts/soul", "concepts/oauth", - "start/bootstrapping" + "start/bootstrapping", + "concepts/experimental-features" ] }, { diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 71ca3a97ac9..9b29b875c09 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -2764,7 +2764,7 @@ 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 phases and thresholds. +- `plugins.entries.memory-core.config.dreaming`: memory dreaming 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). diff --git a/docs/gateway/local-models.md b/docs/gateway/local-models.md index 28b1c2a12d7..3074406eae6 100644 --- a/docs/gateway/local-models.md +++ b/docs/gateway/local-models.md @@ -167,7 +167,8 @@ Compatibility notes for stricter OpenAI-compatible backends: OpenClaw agent turns, first try `agents.defaults.experimental.localModelLean: true` to drop heavyweight default tools like `browser`, `cron`, and `message`; this is an experimental - flag, not a stable default-mode setting. If that still fails, try + flag, not a stable default-mode setting. See + [Experimental Features](/concepts/experimental-features). If that still fails, try `models.providers..models[].compat.supportsTools: false`. - If the backend still fails only on larger OpenClaw runs, the remaining issue is usually upstream model/server capacity or a backend bug, not OpenClaw's diff --git a/docs/reference/memory-config.md b/docs/reference/memory-config.md index 2cae17b9ed0..527521aea59 100644 --- a/docs/reference/memory-config.md +++ b/docs/reference/memory-config.md @@ -479,7 +479,7 @@ Default is DM-only. `match.keyPrefix` matches the normalized session key; --- -## Dreaming (experimental) +## Dreaming Dreaming is configured under `plugins.entries.memory-core.config.dreaming`, not under `agents.defaults.memorySearch`.