Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

docs/plugins/memory-lancedb.md

@@ -0,0 +1,364 @@
+---
+summary: "Configure the official external LanceDB memory plugin, including local Ollama-compatible embeddings"
+read_when:
+  - 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 an official external plugin that stores long-term memory in
+LanceDB with vector search. It can auto-recall relevant memories before a model
+turn and auto-capture important facts after a response.
+
+Use it for a local vector database, an OpenAI-compatible embedding endpoint, or
+a memory store outside the default built-in memory backend.
+
+## Installation
+
+```bash
+openclaw plugins install @openclaw/memory-lancedb
+```
+
+The plugin is published to npm; it is not bundled into the OpenClaw runtime
+image. Installing it writes the plugin entry, enables it, and switches
+`plugins.slots.memory` to `memory-lancedb`. If another plugin currently owns
+the memory slot, that plugin is disabled with a warning.
+
+<Note>
+Companion plugins such as `memory-wiki` can run alongside `memory-lancedb`,
+but only one plugin owns the active memory slot at a time.
+</Note>
+
+## Quick start
+
+```json5
+{
+  plugins: {
+    slots: {
+      memory: "memory-lancedb",
+    },
+    entries: {
+      "memory-lancedb": {
+        enabled: true,
+        config: {
+          embedding: {
+            provider: "openai",
+            model: "text-embedding-3-small",
+          },
+          autoRecall: true,
+          autoCapture: false,
+        },
+      },
+    },
+  },
+}
+```
+
+Restart the Gateway after changing plugin config, then verify it loaded:
+
+```bash
+openclaw gateway restart
+openclaw plugins list
+```
+
+## Embedding config
+
+`embedding` is required and must include at least one field. `provider`
+defaults to `openai`; `model` defaults to `text-embedding-3-small`.
+
+| Field                  | Type          | Notes                                                                    |
+| ---------------------- | ------------- | ------------------------------------------------------------------------ |
+| `embedding.provider`   | string        | Adapter id, e.g. `openai`, `github-copilot`, `ollama`. Default `openai`. |
+| `embedding.model`      | string        | Default `text-embedding-3-small`.                                        |
+| `embedding.apiKey`     | string        | Optional; supports `${ENV_VAR}` expansion.                               |
+| `embedding.baseUrl`    | string        | Optional; supports `${ENV_VAR}` expansion.                               |
+| `embedding.dimensions` | integer (>=1) | Required for models not in the built-in table (see below).               |
+
+Two request paths exist:
+
+- **Provider adapter path** (default): set `embedding.provider` and omit
+  `embedding.apiKey`/`embedding.baseUrl`. The plugin resolves the provider's
+  configured auth profile, environment variable, or
+  `models.providers.<provider>.apiKey` through the same memory embedding
+  adapters `memory-core` uses. This is the path for `github-copilot`, `ollama`,
+  and any other bundled provider with embedding support.
+- **Direct OpenAI-compatible client path**: leave `embedding.provider` unset
+  (or `"openai"`) and set `embedding.apiKey` plus `embedding.baseUrl`. Use this
+  for a raw OpenAI-compatible embeddings endpoint that has no bundled provider
+  adapter.
+
+OpenAI Codex / ChatGPT OAuth is not an OpenAI Platform embeddings credential.
+For OpenAI embeddings use an OpenAI API key auth profile, `OPENAI_API_KEY`, or
+`models.providers.openai.apiKey`. OAuth-only users should pick another
+embedding-capable provider such as `github-copilot` or `ollama`.
+
+```json5
+{
+  plugins: {
+    entries: {
+      "memory-lancedb": {
+        enabled: true,
+        config: {
+          embedding: {
+            provider: "github-copilot",
+            model: "text-embedding-3-small",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Some OpenAI-compatible embedding endpoints reject the `encoding_format`
+parameter; others ignore it and always return `number[]`. `memory-lancedb`
+omits `encoding_format` on requests and accepts either float-array or
+base64-encoded float32 responses, so both response shapes work without config.
+
+### Dimensions
+
+OpenClaw has a built-in dimension for `text-embedding-3-small` (1536) and
+`text-embedding-3-large` (3072) only. Any other model needs an explicit
+`embedding.dimensions` so LanceDB can create the vector column, for example
+ZhiPu `embedding-3` at 2048 dimensions:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "memory-lancedb": {
+        enabled: true,
+        config: {
+          embedding: {
+            apiKey: "${ZHIPU_API_KEY}",
+            baseUrl: "https://open.bigmodel.cn/api/paas/v4",
+            model: "embedding-3",
+            dimensions: 2048,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Ollama embeddings
+
+Use the bundled Ollama provider adapter path (`embedding.provider: "ollama"`).
+It calls Ollama's native `/api/embed` endpoint and follows the same auth/base
+URL rules as the [Ollama](/providers/ollama) provider.
+
+```json5
+{
+  plugins: {
+    slots: {
+      memory: "memory-lancedb",
+    },
+    entries: {
+      "memory-lancedb": {
+        enabled: true,
+        config: {
+          embedding: {
+            provider: "ollama",
+            baseUrl: "http://127.0.0.1:11434",
+            model: "mxbai-embed-large",
+            dimensions: 1024,
+          },
+          recallMaxChars: 400,
+          autoRecall: true,
+          autoCapture: false,
+        },
+      },
+    },
+  },
+}
+```
+
+`mxbai-embed-large` is not in the built-in dimension table, so `dimensions` is
+required. For small local embedding models, lower `recallMaxChars` if the
+local server returns context-length errors.
+
+## Recall and capture limits
+
+| Setting           | Default | Range                        | Applies to                                                 |
+| ----------------- | ------- | ---------------------------- | ---------------------------------------------------------- |
+| `recallMaxChars`  | `1000`  | 100-10000                    | Text sent to the embedding API for recall.                 |
+| `captureMaxChars` | `500`   | 100-10000                    | Message length eligible for auto-capture.                  |
+| `customTriggers`  | `[]`    | 0-50 items, each <=100 chars | Literal phrases that make auto-capture consider a message. |
+
+`recallMaxChars` bounds the `before_prompt_build` auto-recall query, the
+`memory_recall` tool, the `memory_forget` query path, and `openclaw ltm
+search`. Auto-recall embeds the latest user message from the turn and falls
+back to the full prompt only when no user message is present, keeping channel
+metadata and large prompt blocks out of the embedding request.
+
+`captureMaxChars` gates whether a user message from the turn's `agent_end`
+event is short enough to be considered for auto-capture; it does not affect
+recall queries.
+
+`customTriggers` adds literal auto-capture phrases without regex. Built-in
+triggers cover common English, Czech, Chinese, Japanese, and Korean memory
+phrases (`remember`, `prefer`, `记住`, `覚えて`, `기억해`, and similar).
+
+Auto-capture also rejects text that looks like envelope/transport metadata,
+prompt-injection payloads, or already-injected `<relevant-memories>` context,
+and caps at 3 captured memories per agent turn.
+
+## Commands
+
+`memory-lancedb` registers the `ltm` CLI namespace whenever it is installed
+(not only when it owns the active memory slot):
+
+```bash
+openclaw ltm list [--limit <n>] [--order-by-created-at]
+openclaw ltm search <query> [--limit <n>]
+openclaw ltm stats
+```
+
+`ltm query` runs a non-vector query directly against the LanceDB table:
+
+```bash
+openclaw ltm query --cols id,text,createdAt --limit 20
+openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc
+```
+
+| Flag                              | Default                                 | Notes                                                                                                                                     |
+| --------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `--cols <columns>`                | `id,text,importance,category,createdAt` | Comma-separated column allowlist.                                                                                                         |
+| `--filter <condition>`            | none                                    | SQL-style WHERE clause. Max 200 chars; only alphanumerics, `_-`, whitespace, and `='"<>!.,()%*` are allowed.                              |
+| `--limit <n>`                     | `10`                                    | Positive integer.                                                                                                                         |
+| `--order-by <column>:<asc\|desc>` | none                                    | Sorted in memory after the filter runs; the sort column is auto-added to the projection and stripped from output if it was not requested. |
+
+Agents get three tools from the active memory plugin:
+
+- `memory_recall`: vector search over stored memories.
+- `memory_store`: save a fact, preference, decision, or entity (rejects text
+  that looks like a prompt-injection payload; skips near-duplicate stores).
+- `memory_forget`: delete by `memoryId`, or by `query` (auto-deletes a single
+  match above 90% score, otherwise lists candidate IDs to disambiguate).
+
+## Storage
+
+LanceDB data defaults to `~/.openclaw/memory/lancedb`. Override 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
+(e.g. S3-compatible object storage) 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 and platform support
+
+`memory-lancedb` depends on the native `@lancedb/lancedb` package, owned by the
+plugin package (not the OpenClaw core dist). Gateway startup does not repair
+plugin dependencies; if the native dependency is missing or fails to load,
+reinstall or update the plugin package and restart the Gateway.
+
+`@lancedb/lancedb` does not publish a native build for `darwin-x64` (Intel
+Mac). On that platform the plugin logs that LanceDB is unavailable at load
+time; use the default memory backend, run the Gateway on a supported
+platform/architecture, or disable `memory-lancedb`.
+
+## Troubleshooting
+
+### Input length exceeds the context length
+
+The embedding model rejected the recall query:
+
+```text
+memory-lancedb: recall failed: Error: 400 the input length exceeds the context length
+```
+
+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 using its native embed endpoint:
+
+```bash
+curl http://127.0.0.1:11434/api/embed \
+  -H "Content-Type: application/json" \
+  -d '{"model":"mxbai-embed-large","input":"hello"}'
+```
+
+### Unsupported embedding model
+
+Without `embedding.dimensions`, only the built-in OpenAI embedding dimensions
+are known (`text-embedding-3-small`, `text-embedding-3-large`). For any other
+model, set `embedding.dimensions` to the vector size that model reports.
+
+### Plugin loads but no memories appear
+
+Confirm `plugins.slots.memory` points at `memory-lancedb`, then run:
+
+```bash
+openclaw ltm stats
+openclaw ltm search "recent preference"
+```
+
+If `autoCapture` is disabled, the plugin still recalls existing memories but
+does not store new ones automatically. Use the `memory_store` tool, or enable
+`autoCapture`.
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Active memory](/concepts/active-memory)
+- [Memory search](/concepts/memory-search)
+- [Memory Wiki](/plugins/memory-wiki)
+- [Ollama](/providers/ollama)