Summary

Two related issues from a 2026.5.12 install of memory-lancedb:

1. Severe failure mode: setting plugins.slots.memory: "memory-lancedb" before running openclaw plugins install @openclaw/memory-lancedb causes the gateway to crash with Invalid config at openclaw.json. plugins.slots.memory: plugin not found: memory-lancedb, then enter the container restart loop. Recovery requires editing config from a sibling container that shares the same volume, or stopping the stack to edit from the host.

2. Misleading bundled docs: /app/docs/plugins/memory-lancedb.md (shipped inside the image) describes the plugin and its config as if ready to load, without flagging the install step. The plugin source is excluded from the dist build via "!dist/extensions/memory-lancedb/**" in the workspace package.json (intentional per defaultChoice: "npm" in its install metadata), but the docs read as if the plugin is bundled-and-ready.

Environment

• OpenClaw: 2026.5.12 (image ghcr.io/openclaw/openclaw:2026.5.12)
• Install method: Docker Compose, vanilla setup with a persistent volume for ~/.openclaw
• Node: bundled with image

Reproduction

1. Start with a fresh 2026.5.12 stack. In ~/.openclaw/openclaw.json, configure memory-lancedb and assign it to the memory slot, without first running openclaw plugins install @openclaw/memory-lancedb:

{
  "plugins": {
    "slots": { "memory": "memory-lancedb" },
    "entries": {
      "memory-lancedb": {
        "enabled": true,
        "config": {
          "embedding": {
            "provider": "ollama",
            "baseUrl": "http://...",
            "model": "mxbai-embed-large",
            "dimensions": 1024
          },
          "autoRecall": true,
          "dbPath": "~/.openclaw/memory/lancedb"
        }
      }
    }
  }
}

2. Start the gateway.

3. Observe:

Gateway failed to start: Invalid config at /home/node/.openclaw/openclaw.json.
plugins.slots.memory: plugin not found: memory-lancedb

Container exits, Docker auto-restart kicks in, repeats indefinitely.

What the CLI does right (for reference)

openclaw plugins list already surfaces the correct install hint as a config warning:

plugins.entries.memory-lancedb: plugin not installed: memory-lancedb — install the official external plugin with: openclaw plugins install @openclaw/memory-lancedb

That's perfect text. The gateway's startup validator should use the same message and either skip the slot binding or fail soft instead of entering a restart loop.

Suggested fixes

Fix 1 (severity reduction): graceful fail at gateway boot

In the config validator path that handles plugins.slots.memory, when the referenced plugin is configured-but-not-installed:

• Option A (preferred): log the same warning the CLI emits and continue boot with the slot empty. The next openclaw plugins install auto-flips the slot, so this gives users a self-healing recovery path without any container surgery.
• Option B: refuse to start but exit cleanly so the operator can read the error in docker logs without it scrolling past during restart attempts. Better than a restart loop but worse than soft-fail.

Either is strictly better than today's behavior.

Fix 2 (docs): flag install requirement in bundled docs

In docs/plugins/memory-lancedb.md, lead with an Installation section before the config example:

## Installation

memory-lancedb is published to npm and is not bundled with the OpenClaw dist.
Install it before adding `memory-lancedb` to `plugins.slots.memory`:

    openclaw plugins install @openclaw/memory-lancedb

The CLI auto-assigns the memory slot when no other plugin holds it, and writes
the appropriate entry to your `openclaw.json`.

That single section would have saved a recovery cycle in my install.

Recovery workaround (for others hitting this)

If you're already in the crash-loop:

1. The gateway is crash-looping but its volume mount (~/.openclaw) is intact.
2. If your stack has a sibling container that shares the volume mount (e.g., an openclaw-cli service with restart: "no" and network_mode: "service:openclaw-gateway" — note: the cli will only stay up if the gateway started at least once during boot), exec into it and edit openclaw.json to clear plugins.slots.memory (set the value to empty {} or remove the key). Gateway will pick up the corrected config on its next restart attempt.
3. Then run openclaw plugins install @openclaw/memory-lancedb from the cli — this installs the plugin AND re-assigns the slot in one operation.
4. Restart the gateway one more time so the now-installed plugin is loaded.

Without a sibling container, stop the stack, edit the file from the host filesystem, and bring the stack back up.

Related (not duplicates)

• Memory runtime checks should load the configured memory slot #76567 — runtime checks not consulting the configured slot. Different bug: that one is about a configured-AND-installed plugin's runtime check returning empty. This issue is about configured-but-NOT-installed crash-looping the gateway.
• [Bug]: resolvePluginToolRegistry drops loaded plugins' tools when onlyPluginIds references uninstalled plugins (registryContainsPluginIds is all-or-nothing) #76830 — tool registry dropping memory_* tools when other plugin ids are in onlyPluginIds. Different bug, downstream of this one (occurs after a successful install).

Verification

After running openclaw plugins install @openclaw/memory-lancedb, the install completes cleanly:

Installing @openclaw/memory-lancedb into /home/node/.openclaw/npm…
Linked peerDependency "openclaw" -> /app
Exclusive slot "memory" switched from "memory-core" to "memory-lancedb".
Installed plugin: memory-lancedb
Restart the gateway to load plugins.

After restart: 8 plugins load including memory-lancedb, memory_store/memory_recall/memory_forget tools register, and openclaw ltm stats returns a working pool. End-to-end memory_store → restart → memory_recall persists correctly (verified). The install workflow itself is solid — it's only the failure path on a missing install that needs the soft landing.