openclaw/docs/plugins/memory-lancedb.md

summary, read_when, title, sidebarTitle

summary	read_when	title	sidebarTitle
Configure the bundled LanceDB memory plugin, including local Ollama-compatible embeddings	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	Memory LanceDB	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

{
  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:

openclaw gateway restart

Then verify the plugin is loaded:

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.

{
  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:

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:

{
  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:

{
  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:

memory-lancedb: recall failed: Error: 400 the input length exceeds the context length

Set a lower recallMaxChars, then restart the Gateway:

{
  plugins: {
    entries: {
      "memory-lancedb": {
        config: {
          recallMaxChars: 400,
        },
      },
    },
  },
}

For Ollama, also verify the embedding server is reachable from the Gateway host:

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:

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
• Active memory
• Memory search
• Memory Wiki
• Ollama