From 598ee39527ae0a134586ad67e332544181c0a2bb Mon Sep 17 00:00:00 2001
From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
Date: Sun, 12 Apr 2026 14:21:51 -0500
Subject: [PATCH] Clarify Active Memory embedding provider setup

---
 docs/concepts/active-memory.md | 117 +++++++++++++++++++++++++++++++--
 1 file changed, 113 insertions(+), 4 deletions(-)

diff --git a/docs/concepts/active-memory.md b/docs/concepts/active-memory.md
index d47b35fd4ec..63046e7c499 100644
--- a/docs/concepts/active-memory.md
+++ b/docs/concepts/active-memory.md
@@ -608,9 +608,24 @@ If active memory is too slow:
 
 ### Embedding provider changed unexpectedly
 
-Active Memory relies on the normal memory search embedding provider under
-`agents.defaults.memorySearch`. If you do not set that provider explicitly,
-OpenClaw auto-detects the first available embedding provider.
+Active Memory uses the normal `memory_search` pipeline under
+`agents.defaults.memorySearch`. That means embedding-provider setup is only a
+requirement when your `memorySearch` setup requires embeddings for the behavior
+you want.
+
+In practice:
+
+- explicit provider setup is **required** if you want a provider that is not
+  auto-detected, such as `ollama`
+- explicit provider setup is **required** if auto-detection does not resolve
+  any usable embedding provider for your environment
+- explicit provider setup is **highly recommended** if you want deterministic
+  provider selection instead of "first available wins"
+- explicit provider setup is usually **not required** if auto-detection already
+  resolves the provider you want and that provider is stable in your deployment
+
+If `memorySearch.provider` is unset, OpenClaw auto-detects the first available
+embedding provider.
 
 That can be confusing in real deployments:
 
@@ -621,9 +636,103 @@ That can be confusing in real deployments:
 - hosted providers can fail with quota or rate-limit errors that only show up
   once Active Memory starts issuing recall searches before each reply
 
-If you care about predictable behavior, pin the memory embedding provider
+Active Memory can still run when embeddings are unavailable if your
+`memorySearch` setup can fall back to lexical-only retrieval, but semantic
+recall quality will usually degrade. If you depend on embedding-backed recall,
+multimodal indexing, or a specific local/remote provider, pin the provider
 explicitly instead of relying on auto-detection.
 
+Common pinning examples:
+
+OpenAI:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "openai",
+        model: "text-embedding-3-small",
+      },
+    },
+  },
+}
+```
+
+Gemini:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "gemini",
+        model: "gemini-embedding-001",
+      },
+    },
+  },
+}
+```
+
+Ollama:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "ollama",
+        model: "nomic-embed-text",
+      },
+    },
+  },
+}
+```
+
+If you expect provider failover on runtime errors such as quota exhaustion,
+pinning a provider alone is not enough. Configure an explicit fallback too:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "openai",
+        fallback: "gemini",
+      },
+    },
+  },
+}
+```
+
+### Debugging provider issues
+
+If Active Memory is slow, empty, or appears to switch providers unexpectedly:
+
+- watch the gateway logs while reproducing the problem; look for lines such as
+  `active-memory: ... start|done`, `memory sync failed (search-bootstrap)`, or
+  provider-specific embedding errors
+- turn on `/trace on` to surface the plugin-owned Active Memory debug summary in
+  the session
+- turn on `/verbose on` if you also want the normal `🧩 Active Memory: ...`
+  status line after each reply
+- run `openclaw memory status --deep` to inspect the current memory-search
+  backend and index health
+- check `agents.defaults.memorySearch.provider` and related auth/config to make
+  sure the provider you expect is actually the one that can resolve at runtime
+- if you use `ollama`, verify the configured embedding model is installed, for
+  example `ollama list`
+
+Example debugging loop:
+
+```text
+1. Start the gateway and watch its logs
+2. In the chat session, run /trace on
+3. Send one message that should trigger Active Memory
+4. Compare the chat-visible debug line with the gateway log lines
+5. If provider choice is ambiguous, pin agents.defaults.memorySearch.provider explicitly
+```
+
 Example:
 
 ```json5