diff --git a/docs/cli/doctor.md b/docs/cli/doctor.md
index 95a387785f51..1da605d5e13a 100644
--- a/docs/cli/doctor.md
+++ b/docs/cli/doctor.md
@@ -209,6 +209,9 @@ the container normally.
 
 `openclaw doctor --fix` is the only owner for persistent file-to-SQLite migrations. It validates and claims each recognized source, writes and verifies canonical rows, records a migration receipt, then removes the retired source. Runtime code does not perform lazy imports or fallback reads.
 
+For the retired QMD memory backend, including config rewrites and derived
+workspace cleanup, see [Migrating from QMD](/concepts/memory-builtin#migrating-from-qmd).
+
 This includes retired MCP OAuth files under `<state-dir>/mcp-oauth/*.json`. Stop the Gateway before repair. Doctor imports valid credentials into `<state-dir>/state/openclaw.sqlite`, preserves an existing canonical SQLite session when both stores exist, drops the obsolete persisted OAuth `state` value, and uses its receipt to prevent a recreated stale file from resurrecting logged-out credentials. Retired `.lock` sidecars fail closed: if Doctor reports a stale owner, verify that no older OpenClaw process is running, remove that sidecar, and rerun Doctor.
 
 ## Shared state SQLite compaction
diff --git a/docs/concepts/memory-builtin.md b/docs/concepts/memory-builtin.md
index dc7768f61c71..fa5377ef65cc 100644
--- a/docs/concepts/memory-builtin.md
+++ b/docs/concepts/memory-builtin.md
@@ -1,9 +1,11 @@
 ---
+doc-schema-version: 1
 summary: "The default SQLite-based memory backend with keyword, vector, and hybrid search"
 title: "Builtin memory engine"
 read_when:
   - You want to understand the default memory backend
   - You want to configure embedding providers or hybrid search
+  - You are migrating from the removed QMD memory backend
 ---
 
 The builtin engine is the default memory backend. It stores your memory index
@@ -112,6 +114,42 @@ You can also index Markdown files outside the workspace with
 [configuration reference](/reference/memory-config#additional-memory-paths).
 </Info>
 
+## Migrating from QMD
+
+QMD has been removed; builtin is the only memory engine. After upgrading, run:
+
+```bash
+openclaw doctor --fix
+```
+
+Doctor removes the retired `memory.backend`, `memory.qmd`, and
+`memory.search.qmd` settings, including agent-scoped `memory.search.qmd`
+forms. It preserves QMD paths and extra collections as the corresponding
+`memory.search.extraPaths` entries, including `{ path, pattern }` globs. When
+Memory Core finds a retired per-agent QMD workspace under
+`~/.openclaw/agents/<agentId>/qmd/`, Doctor also offers to remove its derived
+indexes, model downloads, collection metadata, and session exports.
+
+Canonical memory remains in `MEMORY.md`, `USER.md`, `memory/*.md`, and the
+migrated extra paths. Builtin indexes those same Markdown sources on its next
+sync. The cutover is lossless by construction: no canonical memory content is
+copied or deleted; only derived state is rebuilt.
+
+Builtin now covers most QMD use cases with:
+
+- hybrid BM25 and vector retrieval by default, followed by temporal decay,
+  importance, and project affinity before MMR diversity,
+- bounded lexical query expansion for conversational searches,
+- string or `{ path, pattern }` entries in `memory.search.extraPaths`, and
+- optional image and audio indexing under `extraPaths` only.
+
+QMD query mode's learned cross-encoder reranking and HyDE generation are not
+part of builtin memory. MMR reduces duplicate results but is not a learned
+relevance reranker. To replace QMD's in-process, zero-key GGUF embeddings,
+install the [llama.cpp provider](/plugins/llama-cpp) and set
+`memory.search.provider: "local"`; without an embedding provider, builtin uses
+BM25 keyword search only.
+
 ## When to use
 
 The builtin engine is the right choice for most users:
diff --git a/docs/concepts/memory-qmd.md b/docs/concepts/memory-qmd.md
index 50d355203a67..737194c905bf 100644
--- a/docs/concepts/memory-qmd.md
+++ b/docs/concepts/memory-qmd.md
@@ -1,4 +1,5 @@
 ---
+doc-schema-version: 1
 summary: "QMD memory backend removal and migration"
 read_when:
   - Migrating an installation that used the QMD memory backend
@@ -9,11 +10,5 @@ title: "QMD memory backend removal"
 
 The optional QMD memory backend has been removed. Builtin memory is now the only memory engine.
 
-Run `openclaw doctor --fix` to remove retired `memory.backend`, `memory.qmd.*`, and
-`memory.search.qmd.*` settings, including agent-scoped variants. Your Markdown memory sources are
-indexed by the builtin engine on its next sync. Doctor preserves configured QMD paths and extra
-collections in the corresponding `memory.search.extraPaths` setting, including root-relative glob
-patterns. QMD indexes, exported session Markdown, downloaded models, and collection metadata are
-derived state and do not require migration.
-
-See [Memory](/concepts/memory) for the current architecture and configuration.
+See [Migrating from QMD](/concepts/memory-builtin#migrating-from-qmd) for the
+automatic Doctor migration, builtin feature coverage, and remaining gaps.
diff --git a/docs/concepts/multi-agent.md b/docs/concepts/multi-agent.md
index 4c69abc2f670..999fa754d12e 100644
--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -167,7 +167,8 @@ The QMD cross-agent search path was removed. Builtin memory does not search
 another agent's transcript corpus; each agent searches only its own configured
 memory and eligible same-agent session sources. Put intentionally shared
 Markdown in an explicit shared `memory.search.extraPaths` directory when the
-same reference material should be indexed by multiple agents.
+same reference material should be indexed by multiple agents. For the full
+upgrade path, see [Migrating from QMD](/concepts/memory-builtin#migrating-from-qmd).
 
 ## One WhatsApp number, multiple people (DM split)
 
diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md
index 22fc16c60b61..37d1b94e9e28 100644
--- a/docs/gateway/doctor.md
+++ b/docs/gateway/doctor.md
@@ -161,6 +161,7 @@ Flags:
     - OAuth TLS prerequisites check for OpenAI Codex OAuth profiles.
     - Plugin/tool allowlist warnings when `plugins.allow` is restrictive but tool policy still asks for wildcard or plugin-owned tools.
     - Legacy on-disk state migration (sessions/agent dir/WhatsApp auth).
+    - Retired QMD memory config and derived workspace cleanup; see [Migrating from QMD](/concepts/memory-builtin#migrating-from-qmd).
     - Legacy plugin manifest contract key migration (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
     - Legacy cron store migration (`jobId`, `schedule.cron`, top-level delivery/payload fields, payload `provider`, `notify: true` webhook fallback jobs).
     - Legacy workspace `TOOLS.md` migration into the `## Tools` section of `AGENTS.md`, with the original archived under the state directory before removal.