From 8c1b4288b2523913f2c1f99999bf20b9f5ac251f Mon Sep 17 00:00:00 2001
From: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
Date: Thu, 4 Jun 2026 22:57:57 +0800
Subject: [PATCH] docs(memory): document explicit provider failures

---
 docs/concepts/memory-search.md  | 11 +++++++++--
 docs/reference/memory-config.md | 15 +++++++++++----
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/docs/concepts/memory-search.md b/docs/concepts/memory-search.md
index de9fac2eb417..76ad1944d08e 100644
--- a/docs/concepts/memory-search.md
+++ b/docs/concepts/memory-search.md
@@ -76,9 +76,16 @@ flowchart LR
 - **BM25 keyword search** finds exact matches (IDs, error strings, config
   keys).
 
-If only one path is available (no embeddings or no FTS), the other runs alone.
+If only one path is available, the other runs alone. Intentional FTS-only mode
+(`provider: "none"`) and automatic/default provider selection can still use
+lexical ranking when embeddings are unavailable.
 
-When embeddings are unavailable, OpenClaw still uses lexical ranking over FTS results instead of falling back to raw exact-match ordering only. That degraded mode boosts chunks with stronger query-term coverage and relevant file paths, which keeps recall useful even without `sqlite-vec` or an embedding provider.
+Explicit non-local embedding providers are different. If you set
+`memorySearch.provider` to a concrete remote-backed provider and that provider
+is unavailable at runtime, `memory_search` reports memory as unavailable instead
+of silently using FTS-only results. This keeps a broken configured semantic
+provider visible. Set `provider: "none"` for deliberate FTS-only recall, or fix
+the provider/auth configuration to restore semantic ranking.
 
 ## Improving search quality
 
diff --git a/docs/reference/memory-config.md b/docs/reference/memory-config.md
index 94b93f9628da..9d8fff6fe22e 100644
--- a/docs/reference/memory-config.md
+++ b/docs/reference/memory-config.md
@@ -67,10 +67,17 @@ automatically re-embedding everything. Rebuild when you are ready with
 `openclaw memory index --force --agent <id>`.
 </Warning>
 
-If OpenAI embeddings are unreachable from your network, memory recall fails open
-instead of blocking the turn. Set the existing `memorySearch.provider` field to a
-reachable local, Ollama, regional, or OpenAI-compatible provider to restore
-semantic ranking.
+When `provider` is unset, legacy `provider: "auto"` is present, or
+`provider: "none"` intentionally selects FTS-only mode, memory recall can still
+use lexical FTS ranking when embeddings are unavailable.
+
+Explicit non-local providers fail closed. If you set `memorySearch.provider` to
+a concrete remote-backed provider such as OpenAI, Gemini, Voyage, Mistral,
+Bedrock, GitHub Copilot, DeepInfra, Ollama, LM Studio, or an OpenAI-compatible
+custom provider, and that provider is unavailable at runtime, `memory_search`
+returns an unavailable result instead of silently using FTS-only recall. Fix the
+provider/auth configuration, switch to a reachable provider, or set
+`provider: "none"` if you want deliberate FTS-only recall.
 
 ### Custom provider ids