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.

Quick start

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

bash
Copy
openclaw gateway restart

Then verify the plugin is loaded:

bash
Copy
openclaw plugins list

Provider-backed embeddings

can use the same memory embedding provider adapters as . Set and omit to use the provider's configured auth profile, environment variable, or .

json5
Copy
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
        },
      },
    },
  },
}

This path works with provider auth profiles that expose embedding credentials. For example, GitHub Copilot can be used when the Copilot profile/plan supports embeddings:

json5
Copy
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "github-copilot",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

OpenAI Codex / ChatGPT OAuth (

) is not an OpenAI Platform embeddings credential. For OpenAI embeddings, use an OpenAI API key auth profile, , or . OAuth-only users can use another embedding-capable provider such as GitHub Copilot or Ollama.

Ollama embeddings

For Ollama embeddings, prefer the bundled Ollama embedding provider. It uses the native Ollama

endpoint and follows the same auth/base URL rules as the Ollama provider documented in Ollama.

json5
Copy
{
  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,
        },
      },
    },
  },
}

Set

for non-standard embedding models. OpenClaw knows the dimensions for and ; custom models need the value in config so LanceDB can create the vector column.

For small local embedding models, lower

if you see context length errors from the local server.

OpenAI-compatible providers

Some OpenAI-compatible embedding providers reject the

parameter, while others ignore it and always return vectors. therefore omits on embedding requests and accepts either float-array responses or base64-encoded float32 responses.

If you have a raw OpenAI-compatible embeddings endpoint that does not have a bundled provider adapter, omit

(or leave it as ) and set plus . This preserves the direct OpenAI-compatible client path.

Set

for providers whose model dimensions are not built in. For example, ZhiPu uses dimensions:

json5
Copy
{
  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,
          },
        },
      },
    },
  },
}

Recall and capture limits

has two separate text limits:

controls auto-recall, the tool, the query path, and . 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.

controls whether a response is short enough to be considered for automatic capture. It does not cap recall query embeddings.

Commands

When

is the active memory plugin, it registers the CLI namespace:

bash
Copy
openclaw ltm list
openclaw ltm search "project preferences"
openclaw ltm stats

The plugin also extends

with a non-vector subcommand that runs against the LanceDB table directly:

bash
Copy
openclaw memory query --cols id,text,createdAt --limit 20
openclaw memory query --filter "category = 'preference'" --order-by createdAt:desc

• text

  Copy

  --cols <columns>
  : comma-separated column allowlist (defaults to
  text

  Copy

  id
  ,
  text

  Copy

  text
  ,
  text

  Copy

  importance
  ,
  text

  Copy

  category
  ,
  text

  Copy

  createdAt
  ).
• text

  Copy

  --filter <condition>
  : SQL-style WHERE clause; capped at 200 characters and restricted to alphanumerics, comparison operators, quotes, parentheses, and a small set of safe punctuation.
• text

  Copy

  --limit <n>
  : positive integer; default
  text

  Copy

  10
  .
• text

  Copy

  --order-by <column>:<asc|desc>
  : in-memory sort applied after the filter; the sort column is auto-included in the projection.

Agents also get LanceDB memory tools from the active memory plugin:

• text

  Copy

  memory_recall
  for LanceDB-backed recall
• text

  Copy

  memory_store
  for saving important facts, preferences, decisions, and entities
• text

  Copy

  memory_forget
  for removing matching memories

Storage

By default, LanceDB data lives under

. Override the path with :

json5
Copy
{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "~/.openclaw/memory/lancedb",
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

accepts string key/value pairs for LanceDB storage backends and supports expansion:

json5
Copy
{
  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

depends on the native 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

or missing error during plugin load, upgrade OpenClaw and restart the Gateway.

If the plugin logs that LanceDB is unavailable on

, use the default memory backend on that machine, move the Gateway to a supported platform, or disable .

Troubleshooting

Input length exceeds the context length

This usually means the embedding model rejected the recall query:

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

Set a lower

, then restart the Gateway:

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

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

bash
Copy
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

, only the built-in OpenAI embedding dimensions are known. For local or custom embedding models, set to the vector size reported by that model.

Plugin loads but no memories appear

Check that

points at , then run:

bash
Copy
openclaw ltm stats
openclaw ltm search "recent preference"

If

is disabled, the plugin will recall existing memories but will not automatically store new ones. Use the tool or enable if you want automatic capture.

Related

• Memory overview
• Active memory
• Memory search
• Memory Wiki
• Ollama