@openclaw/memory-lancedb 2026.5.1-beta.1

package/lancedb-runtime.ts

@@ -0,0 +1,77 @@
+type LanceDbModule = typeof import("@lancedb/lancedb");
+
+export type LanceDbRuntimeLogger = {
+  info?: (message: string) => void;
+  warn?: (message: string) => void;
+};
+
+type LanceDbRuntimeLoaderDeps = {
+  platform: NodeJS.Platform;
+  arch: NodeJS.Architecture;
+  importBundled: () => Promise<LanceDbModule>;
+};
+
+function buildLoadFailureMessage(error: unknown): string {
+  return [
+    "memory-lancedb: bundled @lancedb/lancedb dependency is unavailable.",
+    "Install or repair the memory-lancedb plugin package dependencies, then restart OpenClaw.",
+    String(error),
+  ].join(" ");
+}
+
+function isUnsupportedNativePlatform(params: {
+  platform: NodeJS.Platform;
+  arch: NodeJS.Architecture;
+}): boolean {
+  return params.platform === "darwin" && params.arch === "x64";
+}
+
+function buildUnsupportedNativePlatformMessage(params: {
+  platform: NodeJS.Platform;
+  arch: NodeJS.Architecture;
+}): string {
+  return [
+    `memory-lancedb: LanceDB runtime is unavailable on ${params.platform}-${params.arch}.`,
+    "The bundled @lancedb/lancedb dependency does not publish a native package for this platform.",
+    "Disable memory-lancedb or switch to a supported memory backend/platform.",
+  ].join(" ");
+}
+
+export function createLanceDbRuntimeLoader(overrides: Partial<LanceDbRuntimeLoaderDeps> = {}): {
+  load: (_logger?: LanceDbRuntimeLogger) => Promise<LanceDbModule>;
+} {
+  const deps: LanceDbRuntimeLoaderDeps = {
+    platform: overrides.platform ?? process.platform,
+    arch: overrides.arch ?? process.arch,
+    importBundled: overrides.importBundled ?? (() => import("@lancedb/lancedb")),
+  };
+
+  let loadPromise: Promise<LanceDbModule> | null = null;
+
+  return {
+    async load(_logger?: LanceDbRuntimeLogger): Promise<LanceDbModule> {
+      if (!loadPromise) {
+        loadPromise = deps.importBundled().catch((error) => {
+          loadPromise = null;
+          if (isUnsupportedNativePlatform({ platform: deps.platform, arch: deps.arch })) {
+            throw new Error(
+              buildUnsupportedNativePlatformMessage({
+                platform: deps.platform,
+                arch: deps.arch,
+              }),
+              { cause: error },
+            );
+          }
+          throw new Error(buildLoadFailureMessage(error), { cause: error });
+        });
+      }
+      return await loadPromise;
+    },
+  };
+}
+
+const defaultLoader = createLanceDbRuntimeLoader();
+
+export async function loadLanceDbModule(logger?: LanceDbRuntimeLogger): Promise<LanceDbModule> {
+  return await defaultLoader.load(logger);
+}

package/memory-lancedb.live.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, test } from "vitest";
+import { installTmpDirHarness } from "./test-helpers.js";
+
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? "";
+const HAS_OPENAI_KEY = Boolean(process.env.OPENAI_API_KEY);
+const liveEnabled = HAS_OPENAI_KEY && process.env.OPENCLAW_LIVE_TEST === "1";
+const describeLive = liveEnabled ? describe : describe.skip;
+
+// Live tests that require OpenAI API key and actually use LanceDB
+describeLive("memory plugin live tests", () => {
+  const { getDbPath } = installTmpDirHarness({ prefix: "openclaw-memory-live-" });
+
+  test("memory tools work end-to-end", async () => {
+    const { default: memoryPlugin } = await import("./index.js");
+    const liveApiKey = OPENAI_API_KEY;
+
+    // Mock plugin API
+    const registeredTools: any[] = [];
+    const registeredClis: any[] = [];
+    const registeredServices: any[] = [];
+    const registeredHooks: Record<string, any[]> = {};
+    const logs: string[] = [];
+
+    const mockApi = {
+      id: "memory-lancedb",
+      name: "Memory (LanceDB)",
+      source: "test",
+      config: {},
+      pluginConfig: {
+        embedding: {
+          apiKey: liveApiKey,
+          model: "text-embedding-3-small",
+        },
+        dbPath: getDbPath(),
+        autoCapture: false,
+        autoRecall: false,
+      },
+      runtime: {},
+      logger: {
+        info: (msg: string) => logs.push(`[info] ${msg}`),
+        warn: (msg: string) => logs.push(`[warn] ${msg}`),
+        error: (msg: string) => logs.push(`[error] ${msg}`),
+        debug: (msg: string) => logs.push(`[debug] ${msg}`),
+      },
+      registerTool: (tool: any, opts: any) => {
+        registeredTools.push({ tool, opts });
+      },
+      registerCli: (registrar: any, opts: any) => {
+        registeredClis.push({ registrar, opts });
+      },
+      registerService: (service: any) => {
+        registeredServices.push(service);
+      },
+      on: (hookName: string, handler: any) => {
+        if (!registeredHooks[hookName]) {
+          registeredHooks[hookName] = [];
+        }
+        registeredHooks[hookName].push(handler);
+      },
+      resolvePath: (p: string) => p,
+    };
+
+    // Register plugin
+    memoryPlugin.register(mockApi as any);
+
+    // Check registration
+    expect(registeredTools.length).toBe(3);
+    expect(registeredTools.map((t) => t.opts?.name)).toContain("memory_recall");
+    expect(registeredTools.map((t) => t.opts?.name)).toContain("memory_store");
+    expect(registeredTools.map((t) => t.opts?.name)).toContain("memory_forget");
+    expect(registeredClis.length).toBe(1);
+    expect(registeredServices.length).toBe(1);
+
+    // Get tool functions
+    const storeTool = registeredTools.find((t) => t.opts?.name === "memory_store")?.tool;
+    const recallTool = registeredTools.find((t) => t.opts?.name === "memory_recall")?.tool;
+    const forgetTool = registeredTools.find((t) => t.opts?.name === "memory_forget")?.tool;
+
+    // Test store
+    const storeResult = await storeTool.execute("test-call-1", {
+      text: "The user prefers dark mode for all applications",
+      importance: 0.8,
+      category: "preference",
+    });
+
+    expect(storeResult.details?.action).toBe("created");
+    const storedId = storeResult.details?.id;
+    expect(storedId).toMatch(/.+/);
+
+    // Test recall
+    const recallResult = await recallTool.execute("test-call-2", {
+      query: "dark mode preference",
+      limit: 5,
+    });
+
+    expect(recallResult.details?.count).toBeGreaterThan(0);
+    expect(recallResult.details?.memories?.[0]?.text).toContain("dark mode");
+
+    // Test duplicate detection
+    const duplicateResult = await storeTool.execute("test-call-3", {
+      text: "The user prefers dark mode for all applications",
+    });
+
+    expect(duplicateResult.details?.action).toBe("duplicate");
+
+    // Test forget
+    const forgetResult = await forgetTool.execute("test-call-4", {
+      memoryId: storedId,
+    });
+
+    expect(forgetResult.details?.action).toBe("deleted");
+
+    // Verify it's gone
+    const recallAfterForget = await recallTool.execute("test-call-5", {
+      query: "dark mode preference",
+      limit: 5,
+    });
+
+    expect(recallAfterForget.details?.count).toBe(0);
+  }, 60000); // 60s timeout for live API calls
+});

package/openclaw.plugin.json

@@ -0,0 +1,129 @@
+{
+  "id": "memory-lancedb",
+  "activation": {
+    "onStartup": false
+  },
+  "kind": "memory",
+  "uiHints": {
+    "embedding.apiKey": {
+      "label": "Embedding API Key",
+      "sensitive": true,
+      "placeholder": "sk-proj-...",
+      "help": "Optional API key override for OpenAI-compatible embeddings; omit to use configured provider auth"
+    },
+    "embedding.provider": {
+      "label": "Embedding Provider",
+      "placeholder": "openai",
+      "help": "Memory embedding provider adapter to use (for example openai, github-copilot, ollama)"
+    },
+    "embedding.model": {
+      "label": "Embedding Model",
+      "placeholder": "text-embedding-3-small",
+      "help": "OpenAI embedding model to use"
+    },
+    "embedding.baseUrl": {
+      "label": "Base URL",
+      "placeholder": "https://api.openai.com/v1",
+      "help": "Optional provider or OpenAI-compatible embedding endpoint base URL",
+      "advanced": true
+    },
+    "embedding.dimensions": {
+      "label": "Dimensions",
+      "placeholder": "1536",
+      "help": "Vector dimensions for custom models (required for non-standard models)",
+      "advanced": true
+    },
+    "dbPath": {
+      "label": "Database Path",
+      "placeholder": "~/.openclaw/memory/lancedb",
+      "advanced": true
+    },
+    "autoCapture": {
+      "label": "Auto-Capture",
+      "help": "Automatically capture important information from conversations"
+    },
+    "autoRecall": {
+      "label": "Auto-Recall",
+      "help": "Automatically inject relevant memories into context"
+    },
+    "dreaming": {
+      "label": "Dreaming",
+      "help": "Optional dreaming config consumed when this plugin owns the memory slot"
+    },
+    "captureMaxChars": {
+      "label": "Capture Max Chars",
+      "help": "Maximum message length eligible for auto-capture",
+      "advanced": true,
+      "placeholder": "500"
+    },
+    "recallMaxChars": {
+      "label": "Recall Query Max Chars",
+      "help": "Maximum prompt/query length embedded for memory recall. Lower for small local embedding models.",
+      "advanced": true,
+      "placeholder": "1000"
+    },
+    "storageOptions": {
+      "label": "Storage Options",
+      "advanced": true,
+      "help": "Storage configuration options (access_key, secret_key, endpoint, etc.); supports ${ENV_VAR} values"
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "embedding": {
+        "type": "object",
+        "minProperties": 1,
+        "additionalProperties": false,
+        "minProperties": 1,
+        "properties": {
+          "apiKey": {
+            "type": "string"
+          },
+          "provider": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "baseUrl": {
+            "type": "string"
+          },
+          "dimensions": {
+            "type": "number"
+          }
+        }
+      },
+      "dbPath": {
+        "type": "string"
+      },
+      "autoCapture": {
+        "type": "boolean"
+      },
+      "autoRecall": {
+        "type": "boolean"
+      },
+      "dreaming": {
+        "type": "object"
+      },
+      "captureMaxChars": {
+        "type": "number",
+        "minimum": 100,
+        "maximum": 10000
+      },
+      "recallMaxChars": {
+        "type": "number",
+        "minimum": 100,
+        "maximum": 10000
+      },
+      "storageOptions": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "string"
+        }
+      }
+    },
+    "required": ["embedding"]
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@openclaw/memory-lancedb",
+  "version": "2026.5.1-beta.1",
+  "description": "OpenClaw LanceDB-backed long-term memory plugin with auto-recall/capture",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
+  "type": "module",
+  "dependencies": {
+    "@lancedb/lancedb": "^0.27.2",
+    "openai": "^6.35.0",
+    "typebox": "1.1.37"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@openclaw/memory-lancedb",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.4.25"
+    },
+    "build": {
+      "openclawVersion": "2026.5.1-beta.1"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/test-helpers.ts

@@ -0,0 +1,25 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { resolvePreferredOpenClawTmpDir } from "openclaw/plugin-sdk/temp-path";
+import { afterEach, beforeEach } from "vitest";
+
+export function installTmpDirHarness(params: { prefix: string }) {
+  let tmpDir = "";
+  let dbPath = "";
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(resolvePreferredOpenClawTmpDir(), params.prefix));
+    dbPath = path.join(tmpDir, "lancedb");
+  });
+
+  afterEach(async () => {
+    if (tmpDir) {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  return {
+    getTmpDir: () => tmpDir,
+    getDbPath: () => dbPath,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}