diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 0ba5a4569..421c37ae6 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "7f77ecff77aace88ff8687800316f20c0fd5e831", - "syncedAt": "2026-04-27T23:56:29.172Z" + "sha": "32d76e2429ab341b4714c384d23492f8f21d3a28", + "syncedAt": "2026-04-27T23:59:35.257Z" } diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 068b06265..e930bb4bb 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -343,6 +343,10 @@ "source": "Ollama Web Search", "target": "Ollama Web 搜索" }, + { + "source": "Memory LanceDB", + "target": "Memory LanceDB" + }, { "source": "onboarding", "target": "新手引导" diff --git a/docs/concepts/memory.md b/docs/concepts/memory.md index b02d8f1bd..7affc9abe 100644 --- a/docs/concepts/memory.md +++ b/docs/concepts/memory.md @@ -89,6 +89,10 @@ directories outside the workspace. AI-native cross-session memory with user modeling, semantic search, and multi-agent awareness. Plugin install. + +Bundled LanceDB-backed memory with OpenAI-compatible embeddings, auto-recall, +auto-capture, and local Ollama embedding support. + ## Knowledge wiki layer @@ -179,6 +183,7 @@ openclaw memory index --force # Rebuild the index - [Builtin memory engine](/concepts/memory-builtin): default SQLite backend. - [QMD memory engine](/concepts/memory-qmd): advanced local-first sidecar. - [Honcho memory](/concepts/memory-honcho): AI-native cross-session memory. +- [Memory LanceDB](/plugins/memory-lancedb): LanceDB-backed plugin with OpenAI-compatible embeddings. - [Memory Wiki](/plugins/memory-wiki): compiled knowledge vault and wiki-native tools. - [Memory search](/concepts/memory-search): search pipeline, providers, and tuning. - [Dreaming](/concepts/dreaming): background promotion from short-term recall to long-term memory. @@ -191,3 +196,4 @@ openclaw memory index --force # Rebuild the index - [Memory search](/concepts/memory-search) - [Builtin memory engine](/concepts/memory-builtin) - [Honcho memory](/concepts/memory-honcho) +- [Memory LanceDB](/plugins/memory-lancedb) diff --git a/docs/docs.json b/docs/docs.json index f5a444d2f..710f82dc4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1200,6 +1200,7 @@ "plugins/webhooks", "plugins/voice-call", "plugins/memory-wiki", + "plugins/memory-lancedb", "plugins/message-presentation", "plugins/skill-workshop", "plugins/zalouser", @@ -2665,6 +2666,7 @@ "ja-JP/plugins/webhooks", "ja-JP/plugins/voice-call", "ja-JP/plugins/memory-wiki", + "ja-JP/plugins/memory-lancedb", "ja-JP/plugins/message-presentation", "ja-JP/plugins/skill-workshop", "ja-JP/plugins/zalouser", @@ -3515,6 +3517,7 @@ "es/plugins/webhooks", "es/plugins/voice-call", "es/plugins/memory-wiki", + "es/plugins/memory-lancedb", "es/plugins/message-presentation", "es/plugins/skill-workshop", "es/plugins/zalouser", @@ -4365,6 +4368,7 @@ "pt-BR/plugins/webhooks", "pt-BR/plugins/voice-call", "pt-BR/plugins/memory-wiki", + "pt-BR/plugins/memory-lancedb", "pt-BR/plugins/message-presentation", "pt-BR/plugins/skill-workshop", "pt-BR/plugins/zalouser", @@ -5215,6 +5219,7 @@ "ko/plugins/webhooks", "ko/plugins/voice-call", "ko/plugins/memory-wiki", + "ko/plugins/memory-lancedb", "ko/plugins/message-presentation", "ko/plugins/skill-workshop", "ko/plugins/zalouser", @@ -6065,6 +6070,7 @@ "de/plugins/webhooks", "de/plugins/voice-call", "de/plugins/memory-wiki", + "de/plugins/memory-lancedb", "de/plugins/message-presentation", "de/plugins/skill-workshop", "de/plugins/zalouser", @@ -6915,6 +6921,7 @@ "fr/plugins/webhooks", "fr/plugins/voice-call", "fr/plugins/memory-wiki", + "fr/plugins/memory-lancedb", "fr/plugins/message-presentation", "fr/plugins/skill-workshop", "fr/plugins/zalouser", @@ -7765,6 +7772,7 @@ "ar/plugins/webhooks", "ar/plugins/voice-call", "ar/plugins/memory-wiki", + "ar/plugins/memory-lancedb", "ar/plugins/message-presentation", "ar/plugins/skill-workshop", "ar/plugins/zalouser", @@ -8615,6 +8623,7 @@ "it/plugins/webhooks", "it/plugins/voice-call", "it/plugins/memory-wiki", + "it/plugins/memory-lancedb", "it/plugins/message-presentation", "it/plugins/skill-workshop", "it/plugins/zalouser", @@ -9465,6 +9474,7 @@ "tr/plugins/webhooks", "tr/plugins/voice-call", "tr/plugins/memory-wiki", + "tr/plugins/memory-lancedb", "tr/plugins/message-presentation", "tr/plugins/skill-workshop", "tr/plugins/zalouser", @@ -10315,6 +10325,7 @@ "uk/plugins/webhooks", "uk/plugins/voice-call", "uk/plugins/memory-wiki", + "uk/plugins/memory-lancedb", "uk/plugins/message-presentation", "uk/plugins/skill-workshop", "uk/plugins/zalouser", @@ -11165,6 +11176,7 @@ "id/plugins/webhooks", "id/plugins/voice-call", "id/plugins/memory-wiki", + "id/plugins/memory-lancedb", "id/plugins/message-presentation", "id/plugins/skill-workshop", "id/plugins/zalouser", @@ -12015,6 +12027,7 @@ "pl/plugins/webhooks", "pl/plugins/voice-call", "pl/plugins/memory-wiki", + "pl/plugins/memory-lancedb", "pl/plugins/message-presentation", "pl/plugins/skill-workshop", "pl/plugins/zalouser", diff --git a/docs/plugins/memory-lancedb.md b/docs/plugins/memory-lancedb.md new file mode 100644 index 000000000..7cac365ed --- /dev/null +++ b/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. + + +`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. + + +## 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) diff --git a/docs/tools/plugin.md b/docs/tools/plugin.md index 52a0df329..9c0fb729d 100644 --- a/docs/tools/plugin.md +++ b/docs/tools/plugin.md @@ -155,6 +155,10 @@ plugin discovery rather than silently falling back to source paths. - `memory-core` — bundled memory search (default via `plugins.slots.memory`) - `memory-lancedb` — install-on-demand long-term memory with auto-recall/capture (set `plugins.slots.memory = "memory-lancedb"`) + + See [Memory LanceDB](/plugins/memory-lancedb) for OpenAI-compatible + embedding setup, Ollama examples, recall limits, and troubleshooting. +