@xdarkicex/openclaw-memory-libravdb 1.6.20 → 1.6.21

package/README.md

@@ -75,7 +75,8 @@ Then activate the plugin in `~/.openclaw/openclaw.json`:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     },
     "entries": {
       "libravdb-memory": {
@@ -185,6 +186,8 @@ All keys are optional. For the full reference, see [Configuration](./docs/config
 | `sidecarPath` | string | `auto` | `"auto"` probes standard paths; set `unix:/path` or `tcp:host:port` to override |
 | `embeddingProfile` | string | `nomic-embed-text-v1.5` | Primary embedding model |
 | `fallbackProfile` | string | `bge-small-en-v1.5` | Fallback profile for dimension mismatches |
+| `embeddingRuntimePath` | string | — | Required with `embeddingBackend: "onnx-local"`; path to `libonnxruntime` visible to `libravdbd` |
+| `embeddingModelPath` | string | — | Required with `embeddingBackend: "onnx-local"`; directory containing `embedding.json`, `model.onnx`, and `tokenizer.json` |
 | `onnxDevice` | string | `auto` | ONNX execution provider; set `cpu` to bypass CoreML/MPS on Intel Macs |
 | `userId` | string | auto-derived | Stable identity for cross-session durable memory |
 | `crossSessionRecall` | boolean | `true` | When `false`, only session-scoped memories are retrieved |

package/dist/index.js

@@ -5162,7 +5162,7 @@ var require_create_descriptor_set = __commonJS({
           return `enum ${this.typeName}`;
         },
         getComments() {
-          const path4 = this.parent ? [
+          const path5 = this.parent ? [
             ...this.parent.getComments().sourcePath,
             FieldNumber.DescriptorProto_EnumType,
             this.parent.proto.enumType.indexOf(this.proto)
@@ -5170,7 +5170,7 @@ var require_create_descriptor_set = __commonJS({
             FieldNumber.FileDescriptorProto_EnumType,
             this.file.proto.enumType.indexOf(this.proto)
           ];
-          return findComments(file.proto.sourceCodeInfo, path4);
+          return findComments(file.proto.sourceCodeInfo, path5);
         },
         getFeatures() {
           var _a2, _b2;
@@ -5201,12 +5201,12 @@ var require_create_descriptor_set = __commonJS({
             return str;
           },
           getComments() {
-            const path4 = [
+            const path5 = [
               ...this.parent.getComments().sourcePath,
               FieldNumber.EnumDescriptorProto_Value,
               this.parent.proto.value.indexOf(this.proto)
             ];
-            return findComments(file.proto.sourceCodeInfo, path4);
+            return findComments(file.proto.sourceCodeInfo, path5);
           },
           getFeatures() {
             var _a3;
@@ -5237,7 +5237,7 @@ var require_create_descriptor_set = __commonJS({
           return `message ${this.typeName}`;
         },
         getComments() {
-          const path4 = this.parent ? [
+          const path5 = this.parent ? [
             ...this.parent.getComments().sourcePath,
             FieldNumber.DescriptorProto_NestedType,
             this.parent.proto.nestedType.indexOf(this.proto)
@@ -5245,7 +5245,7 @@ var require_create_descriptor_set = __commonJS({
             FieldNumber.FileDescriptorProto_MessageType,
             this.file.proto.messageType.indexOf(this.proto)
           ];
-          return findComments(file.proto.sourceCodeInfo, path4);
+          return findComments(file.proto.sourceCodeInfo, path5);
         },
         getFeatures() {
           var _a2, _b2;
@@ -5280,11 +5280,11 @@ var require_create_descriptor_set = __commonJS({
           return `service ${this.typeName}`;
         },
         getComments() {
-          const path4 = [
+          const path5 = [
             FieldNumber.FileDescriptorProto_Service,
             this.file.proto.service.indexOf(this.proto)
           ];
-          return findComments(file.proto.sourceCodeInfo, path4);
+          return findComments(file.proto.sourceCodeInfo, path5);
         },
         getFeatures() {
           var _a2;
@@ -5344,12 +5344,12 @@ var require_create_descriptor_set = __commonJS({
           return `rpc ${parent.typeName}.${name}`;
         },
         getComments() {
-          const path4 = [
+          const path5 = [
             ...this.parent.getComments().sourcePath,
             FieldNumber.ServiceDescriptorProto_Method,
             this.parent.proto.method.indexOf(this.proto)
           ];
-          return findComments(parent.file.proto.sourceCodeInfo, path4);
+          return findComments(parent.file.proto.sourceCodeInfo, path5);
         },
         getFeatures() {
           var _a2;
@@ -5370,12 +5370,12 @@ var require_create_descriptor_set = __commonJS({
           return `oneof ${parent.typeName}.${this.name}`;
         },
         getComments() {
-          const path4 = [
+          const path5 = [
             ...this.parent.getComments().sourcePath,
             FieldNumber.DescriptorProto_OneofDecl,
             this.parent.proto.oneofDecl.indexOf(this.proto)
           ];
-          return findComments(parent.file.proto.sourceCodeInfo, path4);
+          return findComments(parent.file.proto.sourceCodeInfo, path5);
         },
         getFeatures() {
           var _a;
@@ -5411,12 +5411,12 @@ var require_create_descriptor_set = __commonJS({
           return `field ${this.parent.typeName}.${this.name}`;
         },
         getComments() {
-          const path4 = [
+          const path5 = [
             ...this.parent.getComments().sourcePath,
             FieldNumber.DescriptorProto_Field,
             this.parent.proto.field.indexOf(this.proto)
           ];
-          return findComments(file.proto.sourceCodeInfo, path4);
+          return findComments(file.proto.sourceCodeInfo, path5);
         },
         getFeatures() {
           var _a2;
@@ -5493,7 +5493,7 @@ var require_create_descriptor_set = __commonJS({
           return `extension ${this.typeName}`;
         },
         getComments() {
-          const path4 = this.parent ? [
+          const path5 = this.parent ? [
             ...this.parent.getComments().sourcePath,
             FieldNumber.DescriptorProto_Extension,
             this.parent.proto.extension.indexOf(proto)
@@ -5501,7 +5501,7 @@ var require_create_descriptor_set = __commonJS({
             FieldNumber.FileDescriptorProto_Extension,
             this.file.proto.extension.indexOf(proto)
           ];
-          return findComments(file.proto.sourceCodeInfo, path4);
+          return findComments(file.proto.sourceCodeInfo, path5);
         },
         getFeatures() {
           var _a;
@@ -8624,14 +8624,14 @@ var require_util = __commonJS({
         }
         const port = url.port != null ? url.port : url.protocol === "https:" ? 443 : 80;
         let origin = url.origin != null ? url.origin : `${url.protocol}//${url.hostname}:${port}`;
-        let path4 = url.path != null ? url.path : `${url.pathname || ""}${url.search || ""}`;
+        let path5 = url.path != null ? url.path : `${url.pathname || ""}${url.search || ""}`;
         if (origin.endsWith("/")) {
           origin = origin.substring(0, origin.length - 1);
         }
-        if (path4 && !path4.startsWith("/")) {
-          path4 = `/${path4}`;
+        if (path5 && !path5.startsWith("/")) {
+          path5 = `/${path5}`;
         }
-        url = new URL(origin + path4);
+        url = new URL(origin + path5);
       }
       return url;
     }
@@ -10245,20 +10245,20 @@ var require_parseParams = __commonJS({
 var require_basename = __commonJS({
   "node_modules/.pnpm/@fastify+busboy@2.1.1/node_modules/@fastify/busboy/lib/utils/basename.js"(exports, module) {
     "use strict";
-    module.exports = function basename(path4) {
-      if (typeof path4 !== "string") {
+    module.exports = function basename(path5) {
+      if (typeof path5 !== "string") {
         return "";
       }
-      for (var i = path4.length - 1; i >= 0; --i) {
-        switch (path4.charCodeAt(i)) {
+      for (var i = path5.length - 1; i >= 0; --i) {
+        switch (path5.charCodeAt(i)) {
           case 47:
           // '/'
           case 92:
-            path4 = path4.slice(i + 1);
-            return path4 === ".." || path4 === "." ? "" : path4;
+            path5 = path5.slice(i + 1);
+            return path5 === ".." || path5 === "." ? "" : path5;
         }
       }
-      return path4 === ".." || path4 === "." ? "" : path4;
+      return path5 === ".." || path5 === "." ? "" : path5;
     };
   }
 });
@@ -13288,7 +13288,7 @@ var require_request = __commonJS({
     }
     var Request = class _Request {
       constructor(origin, {
-        path: path4,
+        path: path5,
         method,
         body,
         headers,
@@ -13302,11 +13302,11 @@ var require_request = __commonJS({
         throwOnError,
         expectContinue
       }, handler) {
-        if (typeof path4 !== "string") {
+        if (typeof path5 !== "string") {
           throw new InvalidArgumentError("path must be a string");
-        } else if (path4[0] !== "/" && !(path4.startsWith("http://") || path4.startsWith("https://")) && method !== "CONNECT") {
+        } else if (path5[0] !== "/" && !(path5.startsWith("http://") || path5.startsWith("https://")) && method !== "CONNECT") {
           throw new InvalidArgumentError("path must be an absolute URL or start with a slash");
-        } else if (invalidPathRegex.exec(path4) !== null) {
+        } else if (invalidPathRegex.exec(path5) !== null) {
           throw new InvalidArgumentError("invalid request path");
         }
         if (typeof method !== "string") {
@@ -13369,7 +13369,7 @@ var require_request = __commonJS({
         this.completed = false;
         this.aborted = false;
         this.upgrade = upgrade || null;
-        this.path = query ? util.buildURL(path4, query) : path4;
+        this.path = query ? util.buildURL(path5, query) : path5;
         this.origin = origin;
         this.idempotent = idempotent == null ? method === "HEAD" || method === "GET" : idempotent;
         this.blocking = blocking == null ? false : blocking;
@@ -14377,9 +14377,9 @@ var require_RedirectHandler = __commonJS({
           return this.handler.onHeaders(statusCode, headers, resume, statusText);
         }
         const { origin, pathname, search } = util.parseURL(new URL(this.location, this.opts.origin && new URL(this.opts.path, this.opts.origin)));
-        const path4 = search ? `${pathname}${search}` : pathname;
+        const path5 = search ? `${pathname}${search}` : pathname;
         this.opts.headers = cleanRequestHeaders(this.opts.headers, statusCode === 303, this.opts.origin !== origin);
-        this.opts.path = path4;
+        this.opts.path = path5;
         this.opts.origin = origin;
         this.opts.maxRedirections = 0;
         this.opts.query = null;
@@ -15619,7 +15619,7 @@ var require_client = __commonJS({
         writeH2(client, client[kHTTP2Session], request3);
         return;
       }
-      const { body, method, path: path4, host, upgrade, headers, blocking, reset } = request3;
+      const { body, method, path: path5, host, upgrade, headers, blocking, reset } = request3;
       const expectsPayload = method === "PUT" || method === "POST" || method === "PATCH";
       if (body && typeof body.read === "function") {
         body.read(0);
@@ -15669,7 +15669,7 @@ var require_client = __commonJS({
       if (blocking) {
         socket[kBlocking] = true;
       }
-      let header = `${method} ${path4} HTTP/1.1\r
+      let header = `${method} ${path5} HTTP/1.1\r
 `;
       if (typeof host === "string") {
         header += `host: ${host}\r
@@ -15732,7 +15732,7 @@ upgrade: ${upgrade}\r
       return true;
     }
     function writeH2(client, session, request3) {
-      const { body, method, path: path4, host, upgrade, expectContinue, signal, headers: reqHeaders } = request3;
+      const { body, method, path: path5, host, upgrade, expectContinue, signal, headers: reqHeaders } = request3;
       let headers;
       if (typeof reqHeaders === "string") headers = Request[kHTTP2CopyHeaders](reqHeaders.trim());
       else headers = reqHeaders;
@@ -15775,7 +15775,7 @@ upgrade: ${upgrade}\r
         });
         return true;
       }
-      headers[HTTP2_HEADER_PATH] = path4;
+      headers[HTTP2_HEADER_PATH] = path5;
       headers[HTTP2_HEADER_SCHEME] = "https";
       const expectsPayload = method === "PUT" || method === "POST" || method === "PATCH";
       if (body && typeof body.read === "function") {
@@ -18015,20 +18015,20 @@ var require_mock_utils = __commonJS({
       }
       return true;
     }
-    function safeUrl(path4) {
-      if (typeof path4 !== "string") {
-        return path4;
+    function safeUrl(path5) {
+      if (typeof path5 !== "string") {
+        return path5;
       }
-      const pathSegments = path4.split("?");
+      const pathSegments = path5.split("?");
       if (pathSegments.length !== 2) {
-        return path4;
+        return path5;
       }
       const qp = new URLSearchParams(pathSegments.pop());
       qp.sort();
       return [...pathSegments, qp.toString()].join("?");
     }
-    function matchKey(mockDispatch2, { path: path4, method, body, headers }) {
-      const pathMatch = matchValue(mockDispatch2.path, path4);
+    function matchKey(mockDispatch2, { path: path5, method, body, headers }) {
+      const pathMatch = matchValue(mockDispatch2.path, path5);
       const methodMatch = matchValue(mockDispatch2.method, method);
       const bodyMatch = typeof mockDispatch2.body !== "undefined" ? matchValue(mockDispatch2.body, body) : true;
       const headersMatch = matchHeaders(mockDispatch2, headers);
@@ -18046,7 +18046,7 @@ var require_mock_utils = __commonJS({
     function getMockDispatch(mockDispatches, key) {
       const basePath = key.query ? buildURL(key.path, key.query) : key.path;
       const resolvedPath = typeof basePath === "string" ? safeUrl(basePath) : basePath;
-      let matchedMockDispatches = mockDispatches.filter(({ consumed }) => !consumed).filter(({ path: path4 }) => matchValue(safeUrl(path4), resolvedPath));
+      let matchedMockDispatches = mockDispatches.filter(({ consumed }) => !consumed).filter(({ path: path5 }) => matchValue(safeUrl(path5), resolvedPath));
       if (matchedMockDispatches.length === 0) {
         throw new MockNotMatchedError(`Mock dispatch not matched for path '${resolvedPath}'`);
       }
@@ -18083,9 +18083,9 @@ var require_mock_utils = __commonJS({
       }
     }
     function buildKey(opts) {
-      const { path: path4, method, body, headers, query } = opts;
+      const { path: path5, method, body, headers, query } = opts;
       return {
-        path: path4,
+        path: path5,
         method,
         body,
         headers,
@@ -18534,10 +18534,10 @@ var require_pending_interceptors_formatter = __commonJS({
       }
       format(pendingInterceptors) {
         const withPrettyHeaders = pendingInterceptors.map(
-          ({ method, path: path4, data: { statusCode }, persist, times, timesInvoked, origin }) => ({
+          ({ method, path: path5, data: { statusCode }, persist, times, timesInvoked, origin }) => ({
             Method: method,
             Origin: origin,
-            Path: path4,
+            Path: path5,
             "Status code": statusCode,
             Persistent: persist ? "\u2705" : "\u274C",
             Invocations: timesInvoked,
@@ -23157,8 +23157,8 @@ var require_util6 = __commonJS({
         }
       }
     }
-    function validateCookiePath(path4) {
-      for (const char of path4) {
+    function validateCookiePath(path5) {
+      for (const char of path5) {
         const code = char.charCodeAt(0);
         if (code < 33 || char === ";") {
           throw new Error("Invalid cookie path");
@@ -24838,11 +24838,11 @@ var require_undici = __commonJS({
           if (typeof opts.path !== "string") {
             throw new InvalidArgumentError("invalid opts.path");
           }
-          let path4 = opts.path;
+          let path5 = opts.path;
           if (!opts.path.startsWith("/")) {
-            path4 = `/${path4}`;
+            path5 = `/${path5}`;
           }
-          url = new URL(util.parseOrigin(url).origin + path4);
+          url = new URL(util.parseOrigin(url).origin + path5);
         } else {
           if (!opts) {
             opts = typeof url === "object" ? url : {};
@@ -25030,7 +25030,7 @@ function deriveIdentityParts() {
 function deriveAutoId(parts) {
   return `${parts.username}@${parts.host}#${parts.homeHash}`;
 }
-function writeIdentityFile(path4, userId, parts) {
+function writeIdentityFile(path5, userId, parts) {
   const identity = {
     userId,
     derivedFrom: {
@@ -25041,15 +25041,15 @@ function writeIdentityFile(path4, userId, parts) {
     },
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  const dir = dirname(path4);
+  const dir = dirname(path5);
   mkdirSync(dir, { recursive: true });
-  const tmp = `${path4}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+  const tmp = `${path5}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
   writeFileSync(tmp, JSON.stringify(identity, null, 2) + "\n", { mode: 384 });
-  renameSync(tmp, path4);
+  renameSync(tmp, path5);
   if (process.platform === "win32") {
     try {
       execSync(
-        `icacls "${path4}" /inheritance:r /grant:r "%USERNAME%:(R,W)"`,
+        `icacls "${path5}" /inheritance:r /grant:r "%USERNAME%:(R,W)"`,
         { stdio: "ignore", timeout: 5e3 }
       );
     } catch {
@@ -35670,11 +35670,11 @@ var Http2SessionManager = class {
    * Clients must call notifyResponseByteRead() whenever they successfully read
    * data from the http2.ClientHttp2Stream.
    */
-  async request(method, path4, headers, options) {
+  async request(method, path5, headers, options) {
     for (; ; ) {
       const ready2 = await this.gotoReady();
       try {
-        const stream = ready2.conn.request(Object.assign(Object.assign({}, headers), { ":method": method, ":path": path4 }), options);
+        const stream = ready2.conn.request(Object.assign(Object.assign({}, headers), { ":method": method, ":path": path5 }), options);
         ready2.registerRequest(stream);
         return stream;
       } catch (e) {
@@ -36983,12 +36983,39 @@ function loadSecretFromEnv(logger) {
 }
 
 // src/plugin-runtime.ts
+import { existsSync as existsSync2, statSync } from "node:fs";
+import path4 from "node:path";
 var DEFAULT_RPC_TIMEOUT_MS = 3e4;
 var VALID_TLS_MODES = ["auto", "tls", "insecure"];
 var isTlsModeValid = (m) => VALID_TLS_MODES.includes(m);
 function daemonProvisioningHint() {
   return "If you installed the npm package, install and start libravdbd separately; the package does not provision the daemon binary, ONNX Runtime, or model assets.";
 }
+function validateEmbeddingConfig(cfg) {
+  if (cfg.embeddingBackend !== "onnx-local") {
+    return;
+  }
+  const runtimePath = cfg.embeddingRuntimePath?.trim();
+  const modelPath = cfg.embeddingModelPath?.trim();
+  if (!runtimePath || !modelPath) {
+    throw new Error(
+      `LibraVDB: embeddingBackend="onnx-local" requires embeddingRuntimePath and embeddingModelPath. Start libravdbd with matching LIBRAVDB_ONNX_RUNTIME and LIBRAVDB_EMBEDDING_MODEL values.`
+    );
+  }
+  if (!shouldValidateLocalEmbeddingPaths(cfg)) {
+    return;
+  }
+  if (!pathExistsAsFile(runtimePath)) {
+    throw new Error(
+      `LibraVDB: embeddingRuntimePath must point to a readable ONNX Runtime library: ${runtimePath}`
+    );
+  }
+  if (!pathExistsAsDirectory(modelPath) || !pathExistsAsFile(path4.join(modelPath, "embedding.json"))) {
+    throw new Error(
+      `LibraVDB: embeddingModelPath must point to a directory containing embedding.json: ${modelPath}`
+    );
+  }
+}
 function createPluginRuntime(cfg, logger = console) {
   let started = null;
   let stopped = false;
@@ -37001,6 +37028,7 @@ function createPluginRuntime(cfg, logger = console) {
     if (!started) {
       let client;
       started = (async () => {
+        validateEmbeddingConfig(cfg);
         validateTlsConfig(cfg, logger);
         client = new LibravDBClient({
           endpoint: cfg.grpcEndpoint || cfg.sidecarPath,
@@ -37070,6 +37098,32 @@ function createPluginRuntime(cfg, logger = console) {
     }
   };
 }
+function shouldValidateLocalEmbeddingPaths(cfg) {
+  const endpoint = resolveClientEndpoint(cfg.grpcEndpoint || cfg.sidecarPath).trim();
+  if (!endpoint || endpoint === "auto" || endpoint.startsWith("unix:")) {
+    return true;
+  }
+  if (!endpoint.startsWith("tcp:")) {
+    return false;
+  }
+  const target = endpoint.slice("tcp:".length);
+  const host = target.startsWith("[") ? target.slice(1, target.indexOf("]")) : target.split(":")[0];
+  return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+function pathExistsAsFile(filePath) {
+  try {
+    return existsSync2(filePath) && statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+function pathExistsAsDirectory(dirPath) {
+  try {
+    return existsSync2(dirPath) && statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
 function validateTlsConfig(cfg, logger) {
   if (cfg.grpcEndpointTlsMode !== void 0 && !isTlsModeValid(cfg.grpcEndpointTlsMode)) {
     throw new Error(

package/dist/plugin-runtime.d.ts

@@ -28,5 +28,6 @@ export interface PluginRuntime {
     shutdown(): Promise<void>;
 }
 export declare function daemonProvisioningHint(): string;
+export declare function validateEmbeddingConfig(cfg: PluginConfig): void;
 export declare function createPluginRuntime(cfg: PluginConfig, logger?: LoggerLike): PluginRuntime;
 export declare function enrichStartupError(error: unknown, healthMessage?: string): Error;

package/dist/plugin-runtime.js

@@ -1,5 +1,7 @@
-import { LibravDBClient } from "./libravdb-client.js";
+import { LibravDBClient, resolveClientEndpoint } from "./libravdb-client.js";
 import { formatError } from "./format-error.js";
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
 export const DEFAULT_RPC_TIMEOUT_MS = 30000;
 export const STARTUP_HEALTH_TIMEOUT_MS = 2000;
 export const VALID_TLS_MODES = ["auto", "tls", "insecure"];
@@ -10,6 +12,26 @@ export function resolveStartupHealthTimeoutMs(cfg) {
 export function daemonProvisioningHint() {
     return "If you installed the npm package, install and start libravdbd separately; the package does not provision the daemon binary, ONNX Runtime, or model assets.";
 }
+export function validateEmbeddingConfig(cfg) {
+    if (cfg.embeddingBackend !== "onnx-local") {
+        return;
+    }
+    const runtimePath = cfg.embeddingRuntimePath?.trim();
+    const modelPath = cfg.embeddingModelPath?.trim();
+    if (!runtimePath || !modelPath) {
+        throw new Error(`LibraVDB: embeddingBackend="onnx-local" requires embeddingRuntimePath and embeddingModelPath. ` +
+            `Start libravdbd with matching LIBRAVDB_ONNX_RUNTIME and LIBRAVDB_EMBEDDING_MODEL values.`);
+    }
+    if (!shouldValidateLocalEmbeddingPaths(cfg)) {
+        return;
+    }
+    if (!pathExistsAsFile(runtimePath)) {
+        throw new Error(`LibraVDB: embeddingRuntimePath must point to a readable ONNX Runtime library: ${runtimePath}`);
+    }
+    if (!pathExistsAsDirectory(modelPath) || !pathExistsAsFile(path.join(modelPath, "embedding.json"))) {
+        throw new Error(`LibraVDB: embeddingModelPath must point to a directory containing embedding.json: ${modelPath}`);
+    }
+}
 export function createPluginRuntime(cfg, logger = console) {
     let started = null;
     let stopped = false;
@@ -22,6 +44,7 @@ export function createPluginRuntime(cfg, logger = console) {
         if (!started) {
             let client;
             started = (async () => {
+                validateEmbeddingConfig(cfg);
                 validateTlsConfig(cfg, logger);
                 client = new LibravDBClient({
                     endpoint: cfg.grpcEndpoint || cfg.sidecarPath,
@@ -97,6 +120,37 @@ export function createPluginRuntime(cfg, logger = console) {
         },
     };
 }
+function shouldValidateLocalEmbeddingPaths(cfg) {
+    // Resolve the same endpoint the client will use — respects LIBRAVDB_GRPC_ENDPOINT env var
+    const endpoint = resolveClientEndpoint(cfg.grpcEndpoint || cfg.sidecarPath).trim();
+    if (!endpoint || endpoint === "auto" || endpoint.startsWith("unix:")) {
+        return true;
+    }
+    if (!endpoint.startsWith("tcp:")) {
+        return false;
+    }
+    const target = endpoint.slice("tcp:".length);
+    const host = target.startsWith("[")
+        ? target.slice(1, target.indexOf("]"))
+        : target.split(":")[0];
+    return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+function pathExistsAsFile(filePath) {
+    try {
+        return existsSync(filePath) && statSync(filePath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function pathExistsAsDirectory(dirPath) {
+    try {
+        return existsSync(dirPath) && statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function validateTlsConfig(cfg, logger) {
     if (cfg.grpcEndpointTlsMode !== undefined &&
         !isTlsModeValid(cfg.grpcEndpointTlsMode)) {

package/dist/types.d.ts

@@ -15,6 +15,8 @@ export interface PluginConfig {
     crossSessionRecall?: boolean;
     useSessionRecallProjection?: boolean;
     useSessionSummarySearchExperiment?: boolean;
+    /** Path to the daemon-visible ONNX Runtime library.
+     * Required when embeddingBackend is "onnx-local". */
     embeddingRuntimePath?: string;
     /** Optional ONNX execution provider override passed through to libravdbd.
      *  Use "cpu" to bypass CoreML/MPS on Intel Macs or fragile GPU/NPU providers. */
@@ -22,6 +24,8 @@ export interface PluginConfig {
     embeddingBackend?: "bundled" | "onnx-local" | "gguf" | "custom-local" | "remote";
     embeddingProfile?: string;
     fallbackProfile?: string;
+    /** Path to a daemon-visible model directory containing embedding.json.
+     * Required when embeddingBackend is "onnx-local". */
     embeddingModelPath?: string;
     embeddingTokenizerPath?: string;
     embeddingDimensions?: number;

package/docs/configuration.md

@@ -87,10 +87,10 @@ address, explicitly set `grpcEndpointTlsMode: "tls"` to match:
 |---|---|---|---|
 | `embeddingProfile` | string | `nomic-embed-text-v1.5` | Primary embedding model |
 | `fallbackProfile` | string | `bge-small-en-v1.5` | Fallback when primary model fails dimension checks |
-| `embeddingBackend` | string | — | `bundled`, `onnx-local`, or `custom-local` |
+| `embeddingBackend` | string | — | `bundled`, `onnx-local`, `custom-local`, or `remote` |
 | `onnxDevice` | string | `auto` | ONNX execution provider: `auto`, `cpu`, `coreml` (macOS), `cuda` (Linux/Windows), `directml` (Windows), `openvino` (Linux) |
-| `embeddingRuntimePath` | string | — | Path to ONNX runtime library (maps to `LIBRAVDB_ONNX_RUNTIME`) |
-| `embeddingModelPath` | string | — | Path to custom embedding model `.onnx` file |
+| `embeddingRuntimePath` | string | — | Path to ONNX runtime library visible to the daemon (maps to `LIBRAVDB_ONNX_RUNTIME`; required with `embeddingBackend: "onnx-local"`) |
+| `embeddingModelPath` | string | — | Path to the model directory containing `embedding.json`, `model.onnx`, and `tokenizer.json` (maps to `LIBRAVDB_EMBEDDING_MODEL`; required with `embeddingBackend: "onnx-local"`) |
 | `embeddingTokenizerPath` | string | — | Path to custom tokenizer file |
 | `embeddingDimensions` | number | — | Embedding dimension override |
 | `embeddingNormalize` | boolean | — | Enable embedding normalization |

package/docs/install.md

@@ -37,7 +37,8 @@ openclaw plugins install @xdarkicex/openclaw-memory-libravdb
 ```
 
 If you use the OpenClaw.ai plugin UI instead of the CLI, install the same
-package and then assign the plugin id `libravdb-memory` to the `memory` slot.
+package and then assign the plugin id `libravdb-memory` to the `memory` and
+`contextEngine` slots.
 
 Activate the plugin in `~/.openclaw/openclaw.json`:
 
@@ -45,7 +46,8 @@ Activate the plugin in `~/.openclaw/openclaw.json`:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     }
   }
 }
@@ -57,7 +59,8 @@ If you run the daemon on a non-default endpoint, add a plugin config:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     },
     "entries": {
       "libravdb-memory": {
@@ -73,7 +76,7 @@ If you run the daemon on a non-default endpoint, add a plugin config:
 
 When `sidecarPath` is set to `"auto"`, the plugin resolves endpoints in this order on macOS/Linux:
 
-1. `LIBRAVDB_RPC_ENDPOINT` if it is set to a valid daemon endpoint
+1. `LIBRAVDB_GRPC_ENDPOINT` if it is set to a valid daemon endpoint
 2. `$HOME/.libravdbd/run/libravdb.sock` if it exists
 3. `/opt/homebrew/var/libravdbd/run/libravdb.sock` if it exists
 4. `/usr/local/var/libravdbd/run/libravdb.sock` if it exists
@@ -81,7 +84,7 @@ When `sidecarPath` is set to `"auto"`, the plugin resolves endpoints in this ord
 
 ## Sidecar Daemon Install
 
-The daemon owns the local database, embeddings, and JSON-RPC endpoint.
+The daemon owns the local database, embeddings, and gRPC endpoint.
 
 Default endpoints:
 
@@ -155,12 +158,68 @@ libravdbd serve
 That mode is useful for debugging or validating a local release asset before
 you wrap it in `brew services`, `systemd`, or `launchd`.
 
+### Containers and Docker
+
+The npm plugin does not start `libravdbd`. In a container, either run a separate
+daemon sidecar or use a small entrypoint wrapper that starts the daemon before
+the OpenClaw gateway.
+
+Keep the daemon assets and database in a mounted volume and point both the
+daemon and plugin at paths inside the container:
+
+```sh
+export LIBRAVDB_GRPC_ENDPOINT=unix:/home/node/.openclaw/libravdbd/run/libravdb.sock
+export LIBRAVDB_DB_PATH=/home/node/.openclaw/libravdbd/data.libravdb
+export LIBRAVDB_ONNX_RUNTIME=/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so
+export LIBRAVDB_EMBEDDING_MODEL=/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5
+export LIBRAVDB_ONNX_DEVICE=cpu
+libravdbd serve &
+
+# Wait for socket to be ready
+for i in {1..30}; do
+  [ -S "$LIBRAVDB_GRPC_ENDPOINT" ] && break
+  sleep 0.5
+done
+
+node dist/index.js gateway --bind lan --port 18789
+```
+
+Use matching plugin config:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
+    },
+    "entries": {
+      "libravdb-memory": {
+        "enabled": true,
+        "config": {
+          "sidecarPath": "unix:/home/node/.openclaw/libravdbd/run/libravdb.sock",
+          "embeddingBackend": "onnx-local",
+          "embeddingRuntimePath": "/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so",
+          "embeddingModelPath": "/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5",
+          "onnxDevice": "cpu"
+        }
+      }
+    }
+  }
+}
+```
+
+For public bots, deny manual memory tools unless users are supposed to query the
+store directly. The context engine can still use LibraVDB for recall while
+`memory_search` and `memory_get` remain unavailable to channel users.
+
 ## Lifecycle Management
 
 ### Plugin Lifecycle
 
 - Install the package with `openclaw plugins install`.
-- Activate it by assigning `libravdb-memory` to the `memory` slot.
+- Activate it by assigning `libravdb-memory` to the `memory` and
+  `contextEngine` slots.
 - Update it with your normal OpenClaw plugin update flow.
 - Disable it by removing the slot assignment from `~/.openclaw/openclaw.json`.
 
@@ -185,7 +244,7 @@ openclaw memory status
 Healthy output should show that:
 
 - the daemon answered the local health check
-- the memory slot is active
+- the memory and context-engine slots are active
 - the plugin can read stored counts and runtime settings
 
 If OpenClaw cannot reach the daemon, verify the endpoint first:

package/docs/installation.md

@@ -60,20 +60,22 @@ or run `libravdbd serve` in a terminal for validation.
 
 ## Activation
 
-Assign `libravdb-memory` to the OpenClaw memory slot:
+Assign `libravdb-memory` to the OpenClaw memory and context-engine slots:
 
 ```json
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     }
   }
 }
 ```
 
-The plugin registers both memory and context-engine capabilities at runtime;
-current OpenClaw config only needs the `memory` slot assignment.
+The memory slot owns `openclaw memory ...` and memory-runtime calls. The
+context-engine slot enables automatic bootstrap, ingest, after-turn, and recall
+hooks during sessions.
 
 If the daemon uses a non-default endpoint, add `sidecarPath`:
 
@@ -81,7 +83,8 @@ If the daemon uses a non-default endpoint, add `sidecarPath`:
 {
   "plugins": {
     "slots": {
-      "memory": "libravdb-memory"
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
     },
     "entries": {
       "libravdb-memory": {
@@ -97,7 +100,7 @@ If the daemon uses a non-default endpoint, add `sidecarPath`:
 
 When `sidecarPath` is `"auto"`, macOS/Linux endpoint resolution checks:
 
-1. `LIBRAVDB_RPC_ENDPOINT`
+1. `LIBRAVDB_GRPC_ENDPOINT`
 2. `$HOME/.libravdbd/run/libravdb.sock`
 3. `/opt/homebrew/var/libravdbd/run/libravdb.sock`
 4. `/usr/local/var/libravdbd/run/libravdb.sock`
@@ -117,6 +120,59 @@ Default data path:
 $HOME/.libravdbd/data_nomic-embed-text-v1_5.libravdb
 ```
 
+## Container Layout
+
+In Docker, keep the daemon, model assets, socket, logs, and database in the
+same mounted OpenClaw state volume. A typical container-side layout is:
+
+```text
+/home/node/.openclaw/bin/libravdbd
+/home/node/.openclaw/libravdbd/run/libravdb.sock
+/home/node/.openclaw/libravdbd/data.libravdb
+/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so
+/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5/embedding.json
+```
+
+Start the daemon with explicit local ONNX paths before starting the gateway:
+
+```sh
+LIBRAVDB_GRPC_ENDPOINT=unix:/home/node/.openclaw/libravdbd/run/libravdb.sock \
+LIBRAVDB_DB_PATH=/home/node/.openclaw/libravdbd/data.libravdb \
+LIBRAVDB_ONNX_RUNTIME=/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so \
+LIBRAVDB_EMBEDDING_MODEL=/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5 \
+LIBRAVDB_ONNX_DEVICE=cpu \
+  /home/node/.openclaw/bin/libravdbd serve
+```
+
+Then configure the plugin with the same socket and asset paths:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "libravdb-memory",
+      "contextEngine": "libravdb-memory"
+    },
+    "entries": {
+      "libravdb-memory": {
+        "enabled": true,
+        "config": {
+          "sidecarPath": "unix:/home/node/.openclaw/libravdbd/run/libravdb.sock",
+          "embeddingBackend": "onnx-local",
+          "embeddingRuntimePath": "/home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so",
+          "embeddingModelPath": "/home/node/.openclaw/libravdbd/models/nomic-embed-text-v1.5",
+          "onnxDevice": "cpu"
+        }
+      }
+    }
+  }
+}
+```
+
+Do not let a container initialize a database with deterministic fallback
+embeddings and later switch the same file to ONNX embeddings. Move the fallback
+database aside first, then let the daemon create a fresh ONNX-backed store.
+
 ## Verification
 
 Run:
@@ -157,6 +213,8 @@ Common causes:
 - `sidecarPath` points at the wrong endpoint
 - ONNX Runtime assets are missing or unpacked in the wrong place
 - a model asset failed checksum validation
+- `embeddingBackend` is set to `onnx-local` but `embeddingRuntimePath` or
+  `embeddingModelPath` is missing from plugin config
 
 Check the daemon first:
 
@@ -171,6 +229,15 @@ For foreground debugging:
 libravdbd serve
 ```
 
+### Deterministic fallback embeddings
+
+If daemon logs mention deterministic fallback mode, the daemon did not find the
+configured ONNX runtime or model manifest. Stop the daemon, set
+`LIBRAVDB_ONNX_RUNTIME` and `LIBRAVDB_EMBEDDING_MODEL`, confirm the model
+directory contains `embedding.json`, then restart. If a database was created
+while fallback mode was active, move that `.libravdb` file and its adjacent
+`.embedding.json` aside before starting with ONNX assets.
+
 ### Incompatible database or embedding profile
 
 If the daemon exits with `database format is incompatible` or `database
@@ -202,9 +269,10 @@ setup, or republish the release with corrected checksums.
 
 ### Default memory still appears active
 
-Confirm that `libravdb-memory` is assigned to `plugins.slots.memory`.
-Without that slot entry, OpenClaw's default memory path can continue to run in
-parallel.
+Confirm that `libravdb-memory` is assigned to both `plugins.slots.memory` and
+`plugins.slots.contextEngine`. Without the memory slot, OpenClaw's default
+memory path can continue to run in parallel. Without the context-engine slot,
+automatic session ingest and recall may not run.
 
 ### Lifecycle journal looks empty
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.6.20",
+  "version": "1.6.21",
   "kind": [
     "memory",
     "context-engine"
@@ -19,21 +19,43 @@
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "if": {
-      "properties": {
-        "embeddingBackend": {
-          "const": "remote"
+    "allOf": [
+      {
+        "if": {
+          "properties": {
+            "embeddingBackend": {
+              "const": "remote"
+            }
+          },
+          "required": [
+            "embeddingBackend"
+          ]
+        },
+        "then": {
+          "required": [
+            "embeddingEndpoint"
+          ]
         }
       },
-      "required": [
-        "embeddingBackend"
-      ]
-    },
-    "then": {
-      "required": [
-        "embeddingEndpoint"
-      ]
-    },
+      {
+        "if": {
+          "properties": {
+            "embeddingBackend": {
+              "const": "onnx-local"
+            }
+          },
+          "required": [
+            "embeddingBackend"
+          ]
+        },
+        "then": {
+          "required": [
+            "embeddingRuntimePath",
+            "embeddingModelPath"
+          ]
+        }
+      }
+    ],
     "properties": {
       "dbPath": {
         "type": "string"
@@ -137,7 +159,8 @@
         "type": "number"
       },
       "embeddingRuntimePath": {
-        "type": "string"
+        "type": "string",
+        "description": "Path to the ONNX Runtime library visible to the daemon, for example /opt/homebrew/opt/libravdbd/models/onnxruntime/lib/libonnxruntime.dylib or /home/node/.openclaw/libravdbd/models/onnxruntime/lib/libonnxruntime.so."
       },
       "onnxDevice": {
         "type": "string",
@@ -171,7 +194,8 @@
         "default": "bge-small-en-v1.5"
       },
       "embeddingModelPath": {
-        "type": "string"
+        "type": "string",
+        "description": "Directory visible to the daemon containing embedding.json, model.onnx, and tokenizer.json for the selected embeddingProfile."
       },
       "embeddingTokenizerPath": {
         "type": "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.6.20",
+  "version": "1.6.21",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",