openclaw-openclaw/docs/plugins/memory-lancedb.md

summary, read_when, title, sidebarTitle

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

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.

Companion plugins such as `memory-wiki` can run alongside `memory-lancedb`, but only one plugin owns the active memory slot at a time.

Quick start

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

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.

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

{
  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 provider.

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

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:

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:

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

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

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

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 using its native embed endpoint:

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:

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