LanceDB Hybrid Search Memory Plugin

LanceDB long-term memory plugin with BM25 + vector hybrid search (RRF or linear reranking).

Security Scan

The skill's code and instructions generally match a LanceDB hybrid-memory plugin, but there are inconsistencies (no declared required env vars or provenance, and it overrides the built-in memory plugin), so review and caution are advised before installing.

Purpose & Capability

Name, description, code, and package.json consistently implement a LanceDB memory plugin with hybrid BM25+vector search and OpenAI embeddings. Declared dependencies (@lancedb/lancedb, openai, typebox) are appropriate for the stated functionality.

Instruction Scope

Runtime instructions ask the user to install the plugin into the workspace, run npm install in the plugin folder, update OpenClaw's plugins.load.paths to point at the plugin (the plugin intentionally keeps id "memory-lancedb" and will override the bundled implementation), and restart the gateway. The plugin will create/modify a DB under ~/.openclaw/memory/lancedb and attempt to create an FTS index. These actions are consistent with a memory plugin but overriding the bundled plugin is a significant change the user must intentionally accept.

Install Mechanism

No automated install spec in registry (instruction-only), but SKILL.md directs a manual npm install in the plugin directory. That will fetch packages from the public npm registry (package-lock.json present). Manual install reduces platform-level risk, but running npm install pulls native optional packages for LanceDB; review network activity and postinstall scripts before running.

Credentials

Registry metadata lists no required env vars, but the plugin requires an embedding API key via config (commonly ${OPENAI_API_KEY}) and resolves referenced env vars at runtime. Requesting an OpenAI API key is proportional to the stated purpose, but the skill metadata does not declare this required credential — the mismatch is a transparency concern.

Persistence & Privilege

always is false and the skill is user-invocable (normal). However, the plugin is designed to override the built-in memory-lancedb by keeping the same extension id and asking the user to add the plugin path to OpenClaw's load paths. This is an intentional, powerful behavior: it can replace the bundled memory implementation and should be installed only when you trust the code.

Scan Findings in Context

[imports-@lancedb/lancedb] expected: The plugin imports and lazy-loads @lancedb/lancedb; this is expected for a LanceDB-backed memory plugin.

[uses-process.env-resolveEnvVars] expected: The config parser resolves ${ENV_VAR} placeholders (used for embedding.apiKey and baseUrl). This is expected, but it means runtime failure or secrets use depends on environment variables.

[depends-on-openai-package] expected: openai client is declared as a dependency and likely used to generate embeddings; this is required for the plugin to compute vectors.

What to consider before installing

This plugin appears to implement the claimed hybrid LanceDB memory functionality, but proceed with caution: 1) The registry metadata does not declare required environment credentials, yet the plugin requires an OpenAI embedding API key via its config (e.g. ${OPENAI_API_KEY}). Expect to provide that key. 2) Installing requires running npm install in the plugin folder — review package.json/package-lock.json and be aware npm will fetch native optional packages for LanceDB. 3) The plugin intentionally overrides the bundled memory plugin by keeping the id "memory-lancedb"; this replaces the built-in implementation when you add the plugin path. Back up your OpenClaw config and existing memory DB (~/.openclaw/memory/lancedb) before enabling. 4) If you don't trust the source (no homepage or upstream repo provided), consider running it in a disposable/test environment, manually review the full index.ts (to ensure no hidden network endpoints or unexpected behavior beyond what's shown), or prefer a plugin from a known upstream. If you install, ensure the OpenAI key you supply has appropriate billing/permissions and rotate it if you later remove the plugin.

This skill packages a drop-in OpenClaw memory plugin that adds hybrid search to LanceDB memory:

• Vector search (semantic)
• BM25 full-text search (exact terms)
• Configurable reranking:
  • rrf (Reciprocal Rank Fusion, recommended)
  • linear (weighted combination)

It is based on (and credits) OpenClaw PR openclaw/openclaw#7636.

What you get

A local plugin (extension) located at:

• plugin/ → overrides the built-in plugin id memory-lancedb (adds hybrid search)

Once enabled, it provides the same tools as the bundled LanceDB memory plugin:

• memory_store
• memory_recall
• memory_forget

…but memory_recall/auto-recall/forget now use hybrid search when enabled.

Install / Enable

1. Ensure the skill folder exists (ClawHub install puts it under your workspace):

• ~/.openclaw/workspace/skills/memory-lancedb-hybrid/plugin

2. Install the plugin dependencies (once):

cd ~/.openclaw/workspace/skills/memory-lancedb-hybrid/plugin
npm install --omit=dev

3. Add the plugin to OpenClaw’s plugin load paths.

This plugin keeps the id memory-lancedb, so it will override the bundled memory-lancedb extension when discovered via plugins.load.paths (higher precedence than bundled).

Edit ~/.openclaw/openclaw.json:

{
  plugins: {
    load: {
      // Point at the plugin directory inside this skill
      paths: ["~/.openclaw/workspace/skills/memory-lancedb-hybrid/plugin"]
    },

    // Ensure the memory slot points at LanceDB memory
    slots: {
      memory: "memory-lancedb"
    },

    // Configure LanceDB memory (this override adds the `hybrid` config block)
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small"
          },

          // Optional
          dbPath: "~/.openclaw/memory/lancedb",

          // Optional
          autoCapture: true,
          autoRecall: true,

          // Hybrid search options
          hybrid: {
            enabled: true,
            reranker: "rrf"

            // If using reranker: "linear", you can also set:
            // vectorWeight: 0.7,
            // textWeight: 0.3,
          }
        }
      }
    }
  }
}

4. Restart the Gateway.

Hybrid search needs an FTS index on the text column; the plugin will attempt to create it automatically. If FTS setup fails for any reason, the plugin logs a debug message and falls back to vector-only search.

Config reference

All config lives under plugins.entries.memory-lancedb.config.

• hybrid.enabled (boolean, default true)
• hybrid.reranker (rrf | linear, default rrf)
• hybrid.vectorWeight (number 0–1, default 0.7, only used for linear)
• hybrid.textWeight (number 0–1, default 0.3, only used for linear)

Notes / troubleshooting

• This plugin does not modify OpenClaw’s install on disk; it overrides the bundled memory-lancedb at runtime (remove plugins.load.paths to revert).
• If you already have LanceDB memory data on disk, you can keep using the same dbPath.
• If you see no hybrid effect, make sure hybrid.enabled is true and that the FTS index was created (check Gateway logs).

Files

• plugin/index.ts – plugin implementation (hybrid search)
• plugin/config.ts – config parsing + UI hints
• plugin/openclaw.plugin.json – manifest + JSON Schema (used for strict config validation)