@@ -0,0 +1,262 @@
1+---
2+summary: "Configure the bundled LanceDB memory plugin, including local Ollama-compatible embeddings"
3+read_when:
4+ - You are configuring the bundled memory-lancedb plugin
5+ - You want LanceDB-backed long-term memory with auto-recall or auto-capture
6+ - You are using local OpenAI-compatible embeddings such as Ollama
7+title: "Memory LanceDB"
8+sidebarTitle: "Memory LanceDB"
9+---
10+11+`memory-lancedb` is a bundled memory plugin that stores long-term memory in
12+LanceDB and uses embeddings for recall. It can automatically recall relevant
13+memories before a model turn and capture important facts after a response.
14+15+Use it when you want a local vector database for memory, need an
16+OpenAI-compatible embedding endpoint, or want to keep a memory database outside
17+the default built-in memory store.
18+19+<Note>
20+`memory-lancedb` is an active memory plugin. Enable it by selecting the memory
21+slot with `plugins.slots.memory = "memory-lancedb"`. Companion plugins such as
22+`memory-wiki` can run beside it, but only one plugin owns the active memory slot.
23+</Note>
24+25+## Quick start
26+27+```json5
28+{
29+ plugins: {
30+ slots: {
31+ memory: "memory-lancedb",
32+ },
33+ entries: {
34+"memory-lancedb": {
35+ enabled: true,
36+ config: {
37+ embedding: {
38+ apiKey: "${OPENAI_API_KEY}",
39+ model: "text-embedding-3-small",
40+ },
41+ autoRecall: true,
42+ autoCapture: false,
43+ },
44+ },
45+ },
46+ },
47+}
48+```
49+50+Restart the Gateway after changing plugin config:
51+52+```bash
53+openclaw gateway restart
54+```
55+56+Then verify the plugin is loaded:
57+58+```bash
59+openclaw plugins list
60+```
61+62+## Ollama embeddings
63+64+`memory-lancedb` calls embeddings through an OpenAI-compatible embeddings API.
65+For Ollama embeddings, use the Ollama `/v1` compatibility endpoint here. This
66+is only for embeddings; the Ollama chat/model provider uses the native Ollama
67+API URL documented in [Ollama](/providers/ollama).
68+69+```json5
70+{
71+ plugins: {
72+ slots: {
73+ memory: "memory-lancedb",
74+ },
75+ entries: {
76+"memory-lancedb": {
77+ enabled: true,
78+ config: {
79+ embedding: {
80+ apiKey: "ollama",
81+ baseUrl: "http://127.0.0.1:11434/v1",
82+ model: "mxbai-embed-large",
83+ dimensions: 1024,
84+ },
85+ recallMaxChars: 400,
86+ autoRecall: true,
87+ autoCapture: false,
88+ },
89+ },
90+ },
91+ },
92+}
93+```
94+95+Set `dimensions` for non-standard embedding models. OpenClaw knows the
96+dimensions for `text-embedding-3-small` and `text-embedding-3-large`; custom
97+models need the value in config so LanceDB can create the vector column.
98+99+For small local embedding models, lower `recallMaxChars` if you see context
100+length errors from the local server.
101+102+## Recall and capture limits
103+104+`memory-lancedb` has two separate text limits:
105+106+| Setting | Default | Range | Applies to |
107+| ----------------- | ------- | --------- | --------------------------------------------- |
108+| `recallMaxChars` | `1000` | 100-10000 | text sent to the embedding API for recall |
109+| `captureMaxChars` | `500` | 100-10000 | assistant message length eligible for capture |
110+111+`recallMaxChars` controls auto-recall, the `memory_recall` tool, the
112+`memory_forget` query path, and `openclaw ltm search`. Auto-recall prefers the
113+latest user message from the turn and falls back to the full prompt only when no
114+user message is available. This keeps channel metadata and large prompt blocks
115+out of the embedding request.
116+117+`captureMaxChars` controls whether a response is short enough to be considered
118+for automatic capture. It does not cap recall query embeddings.
119+120+## Commands
121+122+When `memory-lancedb` is the active memory plugin, it registers the `ltm` CLI
123+namespace:
124+125+```bash
126+openclaw ltm list
127+openclaw ltm search "project preferences"
128+openclaw ltm stats
129+```
130+131+Agents also get LanceDB memory tools from the active memory plugin:
132+133+- `memory_recall` for LanceDB-backed recall
134+- `memory_store` for saving important facts, preferences, decisions, and entities
135+- `memory_forget` for removing matching memories
136+137+## Storage
138+139+By default, LanceDB data lives under `~/.openclaw/memory/lancedb`. Override the
140+path with `dbPath`:
141+142+```json5
143+{
144+ plugins: {
145+ entries: {
146+"memory-lancedb": {
147+ enabled: true,
148+ config: {
149+ dbPath: "~/.openclaw/memory/lancedb",
150+ embedding: {
151+ apiKey: "${OPENAI_API_KEY}",
152+ model: "text-embedding-3-small",
153+ },
154+ },
155+ },
156+ },
157+ },
158+}
159+```
160+161+`storageOptions` accepts string key/value pairs for LanceDB storage backends and
162+supports `${ENV_VAR}` expansion:
163+164+```json5
165+{
166+ plugins: {
167+ entries: {
168+"memory-lancedb": {
169+ enabled: true,
170+ config: {
171+ dbPath: "s3://memory-bucket/openclaw",
172+ storageOptions: {
173+ access_key: "${AWS_ACCESS_KEY_ID}",
174+ secret_key: "${AWS_SECRET_ACCESS_KEY}",
175+ endpoint: "${AWS_ENDPOINT_URL}",
176+ },
177+ embedding: {
178+ apiKey: "${OPENAI_API_KEY}",
179+ model: "text-embedding-3-small",
180+ },
181+ },
182+ },
183+ },
184+ },
185+}
186+```
187+188+## Runtime dependencies
189+190+`memory-lancedb` depends on the native `@lancedb/lancedb` package. Packaged
191+OpenClaw installs first try the bundled runtime dependency and can repair the
192+plugin runtime dependency under OpenClaw state when the bundled import is not
193+available.
194+195+If an older install logs a missing `dist/package.json` or missing
196+`@lancedb/lancedb` error during plugin load, upgrade OpenClaw and restart the
197+Gateway.
198+199+If the plugin logs that LanceDB is unavailable on `darwin-x64`, use the default
200+memory backend on that machine, move the Gateway to a supported platform, or
201+disable `memory-lancedb`.
202+203+## Troubleshooting
204+205+### Input length exceeds the context length
206+207+This usually means the embedding model rejected the recall query:
208+209+```text
210+memory-lancedb: recall failed: Error: 400 the input length exceeds the context length
211+```
212+213+Set a lower `recallMaxChars`, then restart the Gateway:
214+215+```json5
216+{
217+ plugins: {
218+ entries: {
219+"memory-lancedb": {
220+ config: {
221+ recallMaxChars: 400,
222+ },
223+ },
224+ },
225+ },
226+}
227+```
228+229+For Ollama, also verify the embedding server is reachable from the Gateway host:
230+231+```bash
232+curl http://127.0.0.1:11434/v1/embeddings \
233+ -H "Content-Type: application/json" \
234+ -d '{"model":"mxbai-embed-large","input":"hello"}'
235+```
236+237+### Unsupported embedding model
238+239+Without `dimensions`, only the built-in OpenAI embedding dimensions are known.
240+For local or custom embedding models, set `embedding.dimensions` to the vector
241+size reported by that model.
242+243+### Plugin loads but no memories appear
244+245+Check that `plugins.slots.memory` points at `memory-lancedb`, then run:
246+247+```bash
248+openclaw ltm stats
249+openclaw ltm search "recent preference"
250+```
251+252+If `autoCapture` is disabled, the plugin will recall existing memories but will
253+not automatically store new ones. Use the `memory_store` tool or enable
254+`autoCapture` if you want automatic capture.
255+256+## Related
257+258+- [Memory overview](/concepts/memory)
259+- [Active memory](/concepts/active-memory)
260+- [Memory search](/concepts/memory-search)
261+- [Memory Wiki](/plugins/memory-wiki)
262+- [Ollama](/providers/ollama)
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。