From 85427441a280fca2d0b69f7419e6def32f4d52d3 Mon Sep 17 00:00:00 2001
From: Mariano Belinky <mbelinky@gmail.com>
Date: Wed, 8 Apr 2026 23:48:02 +0200
Subject: [PATCH] Docs/memory: explain grounded backfill flows

---
 docs/concepts/memory.md | 37 ++++++++++++++++++++++++++++++++++++-
 docs/gateway/doctor.md  | 30 ++++++++++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)

diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md
index 3e3d6c21cba..09354593c72 100644
--- a/docs/concepts/memory.md
+++ b/docs/concepts/memory.md
@@ -21,7 +21,7 @@ Your agent has three memory-related files:
 - **`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.
+  summaries for human review, including grounded historical backfill entries.
 
 These files live in the agent workspace (default `~/.openclaw/workspace`).
 
@@ -133,6 +133,41 @@ It is designed to keep long-term memory high signal:
 For phase behavior, scoring signals, and Dream Diary details, see
 [Dreaming (experimental)](/concepts/dreaming).
 
+## Grounded backfill and live promotion
+
+The dreaming system now has two closely related review lanes:
+
+- **Live dreaming** works from the short-term dreaming store under
+  `memory/.dreams/` and is what the normal deep phase uses when deciding what
+  can graduate into `MEMORY.md`.
+- **Grounded backfill** reads historical `memory/YYYY-MM-DD.md` notes as
+  standalone day files and writes structured review output into `DREAMS.md`.
+
+Grounded backfill is useful when you want to replay older notes and inspect what
+the system thinks is durable without manually editing `MEMORY.md`.
+
+When you use:
+
+```bash
+openclaw memory rem-backfill --path ./memory --stage-short-term
+```
+
+the grounded durable candidates are not promoted directly. They are staged into
+the same short-term dreaming store the normal deep phase already uses. That
+means:
+
+- `DREAMS.md` stays the human review surface.
+- the short-term store stays the machine-facing ranking surface.
+- `MEMORY.md` is still only written by deep promotion.
+
+If you decide the replay was not useful, you can remove the staged artifacts
+without touching ordinary diary entries or normal recall state:
+
+```bash
+openclaw memory rem-backfill --rollback
+openclaw memory rem-backfill --rollback-short-term
+```
+
 ## CLI
 
 ```bash
diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md
index 83ddb3d169f..9f6db957e6f 100644
--- a/docs/gateway/doctor.md
+++ b/docs/gateway/doctor.md
@@ -93,6 +93,36 @@ cat ~/.openclaw/openclaw.json
 - Source install checks (pnpm workspace mismatch, missing UI assets, missing tsx binary).
 - Writes updated config + wizard metadata.
 
+## Dreams UI backfill and reset
+
+The Control UI Dreams scene includes **Backfill** and **Reset** actions for the
+grounded diary workflow. These actions use gateway doctor-style RPC methods, but
+they are **not** part of `openclaw doctor` CLI repair/migration.
+
+What they do:
+
+- **Backfill** scans historical `memory/YYYY-MM-DD.md` files in the active
+  workspace, runs the grounded REM diary pass, and writes reversible backfill
+  entries into `DREAMS.md`.
+- **Reset** removes only those marked backfill diary entries from `DREAMS.md`.
+
+What they do **not** do by themselves:
+
+- they do not edit `MEMORY.md`
+- they do not run full doctor migrations
+- they do not automatically stage grounded candidates into the live short-term
+  promotion store
+
+If you want grounded historical replay to influence the normal deep promotion
+lane, use the CLI flow instead:
+
+```bash
+openclaw memory rem-backfill --path ./memory --stage-short-term
+```
+
+That stages grounded durable candidates into the short-term dreaming store while
+keeping `DREAMS.md` as the review surface.
+
 ## Detailed behavior and rationale
 
 ### 0) Optional update (git installs)