fix(memory): bound lancedb recall embedding queries

docs/plugins/memory-lancedb.md

@@ -0,0 +1,262 @@
+---
+summary: "Configure the bundled LanceDB memory plugin, including local Ollama-compatible embeddings"
+read_when:
+  - You are configuring the bundled 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
+LanceDB and uses embeddings for recall. It can automatically recall relevant
+memories before a model turn and capture important facts after a response.
+
+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.
+
+<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
+`memory-wiki` can run beside it, but only one plugin owns the active memory slot.
+</Note>
+
+## Quick start
+
+```json5
+{
+  plugins: {
+    slots: {
+      memory: "memory-lancedb",
+    },
+    entries: {
+      "memory-lancedb": {
+        enabled: true,
+        config: {
+          embedding: {
+            apiKey: "${OPENAI_API_KEY}",
+            model: "text-embedding-3-small",
+          },
+          autoRecall: true,
+          autoCapture: false,
+        },
+      },
+    },
+  },
+}
+```
+
+Restart the Gateway after changing plugin config:
+
+```bash
+openclaw gateway restart
+```
+
+Then verify the plugin is loaded:
+
+```bash
+openclaw plugins list
+```
+
+## Ollama embeddings
+
+`memory-lancedb` calls embeddings through an OpenAI-compatible embeddings API.
+For Ollama embeddings, use the Ollama `/v1` compatibility endpoint here. This
+is only for embeddings; the Ollama chat/model provider uses the native Ollama
+API URL documented in [Ollama](/providers/ollama).
+
+```json5
+{
+  plugins: {
+    slots: {
+      memory: "memory-lancedb",
+    },
+    entries: {
+      "memory-lancedb": {
+        enabled: true,
+        config: {
+          embedding: {
+            apiKey: "ollama",
+            baseUrl: "http://127.0.0.1:11434/v1",
+            model: "mxbai-embed-large",
+            dimensions: 1024,
+          },
+          recallMaxChars: 400,
+          autoRecall: true,
+          autoCapture: false,
+        },
+      },
+    },
+  },
+}
+```
+
+Set `dimensions` for non-standard embedding models. OpenClaw knows the
+dimensions for `text-embedding-3-small` and `text-embedding-3-large`; custom
+models need the value in config so LanceDB can create the vector column.
+
+For small local embedding models, lower `recallMaxChars` if you see context
+length errors from the local server.
+
+## Recall and capture limits
+
+`memory-lancedb` has two separate text limits:
+
+| Setting           | Default | Range     | Applies to                                    |
+| ----------------- | ------- | --------- | --------------------------------------------- |
+| `recallMaxChars`  | `1000`  | 100-10000 | text sent to the embedding API for recall     |
+| `captureMaxChars` | `500`   | 100-10000 | assistant message length eligible for capture |
+
+`recallMaxChars` controls auto-recall, the `memory_recall` tool, the
+`memory_forget` query path, and `openclaw ltm search`. Auto-recall prefers the
+latest user message from the turn and falls back to the full prompt only when no
+user message is available. This keeps channel metadata and large prompt blocks
+out of the embedding request.
+
+`captureMaxChars` controls whether a response is short enough to be considered
+for automatic capture. It does not cap recall query embeddings.
+
+## Commands
+
+When `memory-lancedb` is the active memory plugin, it registers the `ltm` CLI
+namespace:
+
+```bash
+openclaw ltm list
+openclaw ltm search "project preferences"
+openclaw ltm stats
+```
+
+Agents also get LanceDB memory tools from the active memory plugin:
+
+- `memory_recall` for LanceDB-backed recall
+- `memory_store` for saving important facts, preferences, decisions, and entities
+- `memory_forget` for removing matching memories
+
+## Storage
+
+By default, LanceDB data lives under `~/.openclaw/memory/lancedb`. Override the
+path with `dbPath`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "memory-lancedb": {
+        enabled: true,
+        config: {
+          dbPath: "~/.openclaw/memory/lancedb",
+          embedding: {
+            apiKey: "${OPENAI_API_KEY}",
+            model: "text-embedding-3-small",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+`storageOptions` accepts string key/value pairs for LanceDB storage backends and
+supports `${ENV_VAR}` expansion:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "memory-lancedb": {
+        enabled: true,
+        config: {
+          dbPath: "s3://memory-bucket/openclaw",
+          storageOptions: {
+            access_key: "${AWS_ACCESS_KEY_ID}",
+            secret_key: "${AWS_SECRET_ACCESS_KEY}",
+            endpoint: "${AWS_ENDPOINT_URL}",
+          },
+          embedding: {
+            apiKey: "${OPENAI_API_KEY}",
+            model: "text-embedding-3-small",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Runtime dependencies
+
+`memory-lancedb` depends on the native `@lancedb/lancedb` package. Packaged
+OpenClaw installs first try the bundled runtime dependency and can repair the
+plugin runtime dependency under OpenClaw state when the bundled import is not
+available.
+
+If an older install logs a missing `dist/package.json` or missing
+`@lancedb/lancedb` error during plugin load, upgrade OpenClaw and restart the
+Gateway.
+
+If the plugin logs that LanceDB is unavailable on `darwin-x64`, use the default
+memory backend on that machine, move the Gateway to a supported platform, or
+disable `memory-lancedb`.
+
+## Troubleshooting
+
+### Input length exceeds the context length
+
+This usually means the embedding model rejected the recall query:
+
+```text
+memory-lancedb: recall failed: Error: 400 the input length exceeds the context length
+```
+
+Set a lower `recallMaxChars`, then restart the Gateway:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "memory-lancedb": {
+        config: {
+          recallMaxChars: 400,
+        },
+      },
+    },
+  },
+}
+```
+
+For Ollama, also verify the embedding server is reachable from the Gateway host:
+
+```bash
+curl http://127.0.0.1:11434/v1/embeddings \
+  -H "Content-Type: application/json" \
+  -d '{"model":"mxbai-embed-large","input":"hello"}'
+```
+
+### Unsupported embedding model
+
+Without `dimensions`, only the built-in OpenAI embedding dimensions are known.
+For local or custom embedding models, set `embedding.dimensions` to the vector
+size reported by that model.
+
+### Plugin loads but no memories appear
+
+Check that `plugins.slots.memory` points at `memory-lancedb`, then run:
+
+```bash
+openclaw ltm stats
+openclaw ltm search "recent preference"
+```
+
+If `autoCapture` is disabled, the plugin will recall existing memories but will
+not automatically store new ones. Use the `memory_store` tool or enable
+`autoCapture` if you want automatic capture.
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Active memory](/concepts/active-memory)
+- [Memory search](/concepts/memory-search)
+- [Memory Wiki](/plugins/memory-wiki)
+- [Ollama](/providers/ollama)