docs: deep audit of memory section -- fix icons, beef up engine pages, restructure config reference

docs/concepts/memory-builtin.md

@@ -14,12 +14,10 @@ a per-agent SQLite database and needs no extra dependencies to get started.
 ## What it provides
 
 - **Keyword search** via FTS5 full-text indexing (BM25 scoring).
-- **Vector search** via embeddings from OpenAI, Gemini, Voyage, Mistral, Ollama,
-  or a local GGUF model.
+- **Vector search** via embeddings from any supported provider.
 - **Hybrid search** that combines both for best results.
-- **CJK support** via trigram tokenization.
-- **sqlite-vec acceleration** for in-database vector queries (optional, falls
-  back to in-process cosine similarity).
+- **CJK support** via trigram tokenization for Chinese, Japanese, and Korean.
+- **sqlite-vec acceleration** for in-database vector queries (optional).
 
 ## Getting started
 
@@ -42,24 +40,66 @@ To set a provider explicitly:
 
 Without an embedding provider, only keyword search is available.
 
-## Index location
+## Supported embedding providers
 
-The index lives at `~/.openclaw/memory/<agentId>.sqlite`. Reindex anytime with:
+| Provider | ID        | Auto-detected | Notes                               |
+| -------- | --------- | ------------- | ----------------------------------- |
+| OpenAI   | `openai`  | Yes           | Default: `text-embedding-3-small`   |
+| Gemini   | `gemini`  | Yes           | Supports multimodal (image + audio) |
+| Voyage   | `voyage`  | Yes           |                                     |
+| Mistral  | `mistral` | Yes           |                                     |
+| Ollama   | `ollama`  | No            | Local, set explicitly               |
+| Local    | `local`   | Yes (first)   | GGUF model, ~0.6 GB download        |
 
-```bash
-openclaw memory index --force
-```
+Auto-detection picks the first provider whose API key can be resolved, in the
+order shown. Set `memorySearch.provider` to override.
+
+## How indexing works
+
+OpenClaw indexes `MEMORY.md` and `memory/*.md` into chunks (~400 tokens with
+80-token overlap) and stores them in a per-agent SQLite database.
+
+- **Index location:** `~/.openclaw/memory/<agentId>.sqlite`
+- **File watching:** changes to memory files trigger a debounced reindex (1.5s).
+- **Auto-reindex:** when the embedding provider, model, or chunking config
+  changes, the entire index is rebuilt automatically.
+- **Reindex on demand:** `openclaw memory index --force`
+
+<Info>
+You can also index Markdown files outside the workspace with
+`memorySearch.extraPaths`. See the
+[configuration reference](/reference/memory-config#additional-memory-paths).
+</Info>
 
 ## When to use
 
-The builtin engine is the right choice for most users. It works out of the box,
-has no external dependencies, and handles keyword + vector search well.
+The builtin engine is the right choice for most users:
+
+- Works out of the box with no extra dependencies.
+- Handles keyword and vector search well.
+- Supports all embedding providers.
+- Hybrid search combines the best of both retrieval approaches.
 
 Consider switching to [QMD](/concepts/memory-qmd) if you need reranking, query
 expansion, or want to index directories outside the workspace.
 
+Consider [Honcho](/concepts/memory-honcho) if you want cross-session memory with
+automatic user modeling.
+
+## Troubleshooting
+
+**Memory search disabled?** Check `openclaw memory status`. If no provider is
+detected, set one explicitly or add an API key.
+
+**Stale results?** Run `openclaw memory index --force` to rebuild. The watcher
+may miss changes in rare edge cases.
+
+**sqlite-vec not loading?** OpenClaw falls back to in-process cosine similarity
+automatically. Check logs for the specific load error.
+
 ## Configuration
 
 For embedding provider setup, hybrid search tuning (weights, MMR, temporal
-decay), batch indexing, multimodal memory, sqlite-vec, and all other config
-knobs, see the [Memory configuration reference](/reference/memory-config).
+decay), batch indexing, multimodal memory, sqlite-vec, extra paths, and all
+other config knobs, see the
+[Memory configuration reference](/reference/memory-config).

docs/concepts/memory-honcho.md

@@ -86,6 +86,17 @@ Settings live under `plugins.entries["openclaw-honcho"].config`:
 For self-hosted instances, point `baseUrl` to your local server (for example
 `http://localhost:8000`) and omit the API key.
 
+## Migrating existing memory
+
+If you have existing workspace memory files (`USER.md`, `MEMORY.md`,
+`IDENTITY.md`, `memory/`, `canvas/`), `openclaw honcho setup` detects and
+offers to migrate them.
+
+<Info>
+Migration is non-destructive -- files are uploaded to Honcho. Originals are
+never deleted or moved.
+</Info>
+
 ## How it works
 
 After every AI turn, the conversation is persisted to Honcho. Both user and

docs/concepts/memory-qmd.md

@@ -19,7 +19,7 @@ binary, and can index content beyond your workspace memory files.
 - **Index session transcripts** -- recall earlier conversations.
 - **Fully local** -- runs via Bun + node-llama-cpp, auto-downloads GGUF models.
 - **Automatic fallback** -- if QMD is unavailable, OpenClaw falls back to the
-  builtin engine.
+  builtin engine seamlessly.
 
 ## Getting started
 
@@ -28,6 +28,7 @@ binary, and can index content beyond your workspace memory files.
 - Install QMD: `bun install -g https://github.com/tobi/qmd`
 - SQLite build that allows extensions (`brew install sqlite` on macOS).
 - QMD must be on the gateway's `PATH`.
+- macOS and Linux work out of the box. Windows is best supported via WSL2.
 
 ### Enable
 
@@ -41,7 +42,22 @@ binary, and can index content beyond your workspace memory files.
 
 OpenClaw creates a self-contained QMD home under
 `~/.openclaw/agents/<agentId>/qmd/` and manages the sidecar lifecycle
-automatically.
+automatically -- collections, updates, and embedding runs are handled for you.
+
+## How the sidecar works
+
+- OpenClaw creates collections from your workspace memory files and any
+  configured `memory.qmd.paths`, then runs `qmd update` + `qmd embed` on boot
+  and periodically (default every 5 minutes).
+- Boot refresh runs in the background so chat startup is not blocked.
+- Searches use the configured `searchMode` (default: `search`; also supports
+  `vsearch` and `query`). If a mode fails, OpenClaw retries with `qmd query`.
+- If QMD fails entirely, OpenClaw falls back to the builtin SQLite engine.
+
+<Info>
+The first search may be slow -- QMD auto-downloads GGUF models (~2 GB) for
+reranking and query expansion on the first `qmd query` run.
+</Info>
 
 ## Indexing extra paths
 
@@ -58,6 +74,10 @@ Point QMD at additional directories to make them searchable:
 }
 ```
 
+Snippets from extra paths appear as `qmd/<collection>/<relative-path>` in
+search results. `memory_get` understands this prefix and reads from the correct
+collection root.
+
 ## Indexing session transcripts
 
 Enable session indexing to recall earlier conversations:
@@ -73,7 +93,35 @@ Enable session indexing to recall earlier conversations:
 }
 ```
 
-Transcripts are exported and indexed in a dedicated QMD collection.
+Transcripts are exported as sanitized User/Assistant turns into a dedicated QMD
+collection under `~/.openclaw/agents/<id>/qmd/sessions/`.
+
+## Search scope
+
+By default, QMD search results are only surfaced in DM sessions (not groups or
+channels). Configure `memory.qmd.scope` to change this:
+
+```json5
+{
+  memory: {
+    qmd: {
+      scope: {
+        default: "deny",
+        rules: [{ action: "allow", match: { chatType: "direct" } }],
+      },
+    },
+  },
+}
+```
+
+When scope denies a search, OpenClaw logs a warning with the derived channel and
+chat type so empty results are easier to debug.
+
+## Citations
+
+When `memory.citations` is `auto` or `on`, search snippets include a
+`Source: <path#line>` footer. Set `memory.citations = "off"` to omit the footer
+while still passing the path to the agent internally.
 
 ## When to use
 
@@ -87,6 +135,21 @@ Choose QMD when you need:
 For simpler setups, the [builtin engine](/concepts/memory-builtin) works well
 with no extra dependencies.
 
+## Troubleshooting
+
+**QMD not found?** Ensure the binary is on the gateway's `PATH`. If OpenClaw
+runs as a service, create a symlink:
+`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`.
+
+**First search very slow?** QMD downloads GGUF models on first use. Pre-warm
+with `qmd query "test"` using the same XDG dirs OpenClaw uses.
+
+**Search times out?** Increase `memory.qmd.limits.timeoutMs` (default: 4000ms).
+Set to `120000` for slower hardware.
+
+**Empty results in group chats?** Check `memory.qmd.scope` -- the default only
+allows DM sessions.
+
 ## Configuration
 
 For the full config surface (`memory.qmd.*`), search modes, update intervals,

docs/concepts/memory.md

@@ -1,12 +1,12 @@
 ---
-title: "Memory"
+title: "Memory Overview"
 summary: "How OpenClaw remembers things across sessions"
 read_when:
   - You want to understand how memory works
   - You want to know what memory files to write
 ---
 
-# Memory
+# Memory Overview
 
 OpenClaw remembers things by writing **plain Markdown files** in your agent's
 workspace. The model only "remembers" what gets saved to disk -- there is no
@@ -61,7 +61,7 @@ For details on how search works, tuning options, and provider setup, see
 SQLite-based. Works out of the box with keyword search, vector similarity, and
 hybrid search. No extra dependencies.
 </Card>
-<Card title="QMD" icon="magnifying-glass" href="/concepts/memory-qmd">
+<Card title="QMD" icon="search" href="/concepts/memory-qmd">
 Local-first sidecar with reranking, query expansion, and the ability to index
 directories outside the workspace.
 </Card>