From d1787b73db66bbb773bb0282b1b69d99a33c1667 Mon Sep 17 00:00:00 2001
From: Gio Lodi <giodl73@gmail.com>
Date: Fri, 15 May 2026 21:27:38 -0700
Subject: [PATCH] fix(config): warn for missing official memory slot

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/plugins/memory-lancedb.md              | 18 +++++++++++---
 src/config/config.plugin-validation.test.ts | 27 +++++++++++++++++++++
 src/config/validation.ts                    |  4 ++-
 3 files changed, 45 insertions(+), 4 deletions(-)

diff --git a/docs/plugins/memory-lancedb.md b/docs/plugins/memory-lancedb.md
index ce49893bd2f..caf25491437 100644
--- a/docs/plugins/memory-lancedb.md
+++ b/docs/plugins/memory-lancedb.md
@@ -1,14 +1,14 @@
 ---
-summary: "Configure the bundled LanceDB memory plugin, including local Ollama-compatible embeddings"
+summary: "Configure the official external LanceDB memory plugin, including local Ollama-compatible embeddings"
 read_when:
-  - You are configuring the bundled memory-lancedb plugin
+  - You are configuring the memory-lancedb plugin
   - You want LanceDB-backed long-term memory with auto-recall or auto-capture
   - You are using local OpenAI-compatible embeddings such as Ollama
 title: "Memory LanceDB"
 sidebarTitle: "Memory LanceDB"
 ---
 
-`memory-lancedb` is a bundled memory plugin that stores long-term memory in
+`memory-lancedb` is an official external memory plugin that stores long-term memory in
 LanceDB and uses embeddings for recall. It can automatically recall relevant
 memories before a model turn and capture important facts after a response.
 
@@ -16,6 +16,18 @@ Use it when you want a local vector database for memory, need an
 OpenAI-compatible embedding endpoint, or want to keep a memory database outside
 the default built-in memory store.
 
+## Installation
+
+Install `memory-lancedb` before setting `plugins.slots.memory = "memory-lancedb"`:
+
+```bash
+openclaw plugins install @openclaw/memory-lancedb
+```
+
+The plugin is published to npm and is not bundled into the OpenClaw runtime image.
+The installer writes the plugin entry and switches the memory slot when no other
+plugin owns it.
+
 <Note>
 `memory-lancedb` is an active memory plugin. Enable it by selecting the memory
 slot with `plugins.slots.memory = "memory-lancedb"`. Companion plugins such as
diff --git a/src/config/config.plugin-validation.test.ts b/src/config/config.plugin-validation.test.ts
index 6f8c39a021b..f5344123944 100644
--- a/src/config/config.plugin-validation.test.ts
+++ b/src/config/config.plugin-validation.test.ts
@@ -330,6 +330,33 @@ describe("config plugin validation", () => {
     ).toBe(false);
   });
 
+  it("warns instead of failing when an official external memory slot plugin is not installed", () => {
+    const res = validateConfigObjectWithPlugins(
+      {
+        agents: { list: [{ id: "pi" }] },
+        plugins: {
+          slots: { memory: "memory-lancedb" },
+          entries: { "memory-lancedb": { enabled: true } },
+        },
+      },
+      {
+        env: suiteEnv(),
+        pluginMetadataSnapshot: {
+          manifestRegistry: {
+            plugins: [],
+            diagnostics: [],
+          },
+        },
+      },
+    );
+
+    expect(res.ok).toBe(true);
+    const message =
+      "plugin not installed: memory-lancedb — install the official external plugin with: openclaw plugins install @openclaw/memory-lancedb";
+    expectPathMessage(res.warnings, "plugins.slots.memory", message);
+    expectPathMessage(res.warnings, "plugins.entries.memory-lancedb", message);
+  });
+
   it.runIf(process.platform !== "win32")(
     "reports configured blocked plugins without stale not-found wording",
     async () => {
diff --git a/src/config/validation.ts b/src/config/validation.ts
index 83dbae82308..6f7a8530b71 100644
--- a/src/config/validation.ts
+++ b/src/config/validation.ts
@@ -1557,7 +1557,9 @@ function validateConfigObjectWithPluginsBase(
     memorySlot.trim() &&
     !knownIds.has(memorySlot)
   ) {
-    pushMissingPluginIssue("plugins.slots.memory", memorySlot);
+    pushMissingPluginIssue("plugins.slots.memory", memorySlot, {
+      warnOnly: Boolean(formatMissingOfficialExternalPluginWarning(memorySlot)),
+    });
   }
 
   let selectedMemoryPluginId: string | null = null;