@xdarkicex/openclaw-memory-libravdb 1.4.80 → 1.5.0

package/README.md

@@ -187,7 +187,7 @@ All keys are optional. For the full reference, see [Configuration](./docs/config
 
 - New install: [Install](./docs/install.md), [Installation reference](./docs/installation.md)
 - Understand the design: [Problem](./docs/problem.md), [Architecture](./docs/architecture.md), [ADRs](./docs/architecture-decisions/README.md)
-- Configure: [Configuration](./docs/configuration.md), [Features](./docs/features.md), [Embedding profiles](./docs/embedding-profiles.md), [Models](./docs/models.md)
+- Configure: [Configuration](./docs/configuration.md), [TLS configuration](./docs/TLS_configuration.md), [Features](./docs/features.md), [Embedding profiles](./docs/embedding-profiles.md), [Models](./docs/models.md)
 - Operate safely: [Security](./docs/security.md), [Uninstall](./docs/uninstall.md)
 - Advanced operations: [Performance and tuning](./docs/performance-and-tuning.md)
 - Work from source: [Development](./docs/development.md), [Contributing](./docs/contributing.md)

package/dist/grpc-client.d.ts

@@ -1,10 +1,27 @@
+import * as grpc from "@grpc/grpc-js";
 export interface GrpcClientOptions {
     endpoint: string;
     secret?: string;
     timeoutMs?: number;
+    tlsCaPath?: string;
+    tlsMode?: "auto" | "tls" | "insecure";
 }
 export declare function resolveGrpcTarget(endpoint: string): string;
-export declare function resolveGrpcCredentialMode(endpoint: string): "insecure" | "tls";
+/**
+ * Selects gRPC credential mode based on endpoint address class.
+ *
+ * - Unix socket endpoints → plaintext (local-only transport)
+ * - Loopback addresses (localhost, 127.0.0.1, ::1) → plaintext
+ * - All other TCP and DNS targets → TLS
+ *
+ * resolveGrpcCredentials uses this classification to return the
+ * appropriate grpc.ChannelCredentials. Pass tlsCaPath to load a
+ * custom CA certificate PEM file for self-signed or private CA
+ * deployments. Omit tlsCaPath for publicly trusted certificates
+ * (Let's Encrypt, cert-manager) — the system CA pool is used.
+ */
+export declare function resolveGrpcCredentialMode(endpoint: string, tlsMode?: "auto" | "tls" | "insecure"): "insecure" | "tls";
+export declare function resolveGrpcCredentials(endpoint: string, tlsCaPath?: string, tlsMode?: "auto" | "tls" | "insecure"): grpc.ChannelCredentials;
 export declare class GrpcKernelClient {
     private client;
     private readonly secret;

package/dist/grpc-client.js

@@ -1,6 +1,7 @@
 import { createHmac } from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import * as fs from "fs";
 import * as grpc from "@grpc/grpc-js";
 import * as protoLoader from "@grpc/proto-loader";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -10,18 +11,47 @@ const PROTO_PATH = path.resolve(__dirname, "./proto/intelligence_kernel/v1/kerne
 export function resolveGrpcTarget(endpoint) {
     return endpoint.startsWith("tcp:") ? endpoint.substring(4) : endpoint;
 }
-export function resolveGrpcCredentialMode(endpoint) {
+/**
+ * Selects gRPC credential mode based on endpoint address class.
+ *
+ * - Unix socket endpoints → plaintext (local-only transport)
+ * - Loopback addresses (localhost, 127.0.0.1, ::1) → plaintext
+ * - All other TCP and DNS targets → TLS
+ *
+ * resolveGrpcCredentials uses this classification to return the
+ * appropriate grpc.ChannelCredentials. Pass tlsCaPath to load a
+ * custom CA certificate PEM file for self-signed or private CA
+ * deployments. Omit tlsCaPath for publicly trusted certificates
+ * (Let's Encrypt, cert-manager) — the system CA pool is used.
+ */
+export function resolveGrpcCredentialMode(endpoint, tlsMode) {
+    if (tlsMode === "tls")
+        return "tls";
+    if (tlsMode === "insecure")
+        return "insecure";
+    // "auto" or undefined — address-based heuristic
     const target = resolveGrpcTarget(endpoint).trim();
-    if (target.startsWith("unix:")) {
+    if (target.startsWith("unix:"))
         return "insecure";
-    }
     const host = extractGrpcHost(target);
     return isLoopbackHost(host) ? "insecure" : "tls";
 }
-function resolveGrpcCredentials(endpoint) {
-    return resolveGrpcCredentialMode(endpoint) === "insecure"
-        ? grpc.credentials.createInsecure()
-        : grpc.credentials.createSsl();
+export function resolveGrpcCredentials(endpoint, tlsCaPath, tlsMode) {
+    if (resolveGrpcCredentialMode(endpoint, tlsMode) === "insecure") {
+        return grpc.credentials.createInsecure();
+    }
+    if (tlsCaPath) {
+        let rootCerts;
+        try {
+            rootCerts = fs.readFileSync(tlsCaPath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`LibraVDB: failed to load TLS CA certificate from "${tlsCaPath}": ${msg}`);
+        }
+        return grpc.credentials.createSsl(rootCerts, null, null);
+    }
+    return grpc.credentials.createSsl();
 }
 function extractGrpcHost(target) {
     const withoutDnsPrefix = target.startsWith("dns:///") ? target.slice("dns:///".length) : target;
@@ -54,7 +84,7 @@ export class GrpcKernelClient {
         const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
         const kernelService = protoDescriptor.intelligence_kernel.v1.IntelligenceKernel;
         const target = resolveGrpcTarget(options.endpoint);
-        this.client = new kernelService(target, resolveGrpcCredentials(options.endpoint));
+        this.client = new kernelService(target, resolveGrpcCredentials(options.endpoint, options.tlsCaPath, options.tlsMode));
     }
     getMetadata(signed = true) {
         const md = new grpc.Metadata();

package/dist/index.js

@@ -8810,14 +8810,14 @@ var require_tls_helpers = __commonJS({
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.CIPHER_SUITES = void 0;
     exports2.getDefaultRootsData = getDefaultRootsData;
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     exports2.CIPHER_SUITES = process.env.GRPC_SSL_CIPHER_SUITES;
     var DEFAULT_ROOTS_FILE_PATH = process.env.GRPC_DEFAULT_SSL_ROOTS_FILE_PATH;
     var defaultRootsData = null;
     function getDefaultRootsData() {
       if (DEFAULT_ROOTS_FILE_PATH) {
         if (defaultRootsData === null) {
-          defaultRootsData = fs4.readFileSync(DEFAULT_ROOTS_FILE_PATH);
+          defaultRootsData = fs5.readFileSync(DEFAULT_ROOTS_FILE_PATH);
         }
         return defaultRootsData;
       }
@@ -14324,7 +14324,7 @@ var require_fetch = __commonJS({
     module2.exports = fetch;
     var asPromise = require_aspromise();
     var inquire2 = require_inquire();
-    var fs4 = inquire2("fs");
+    var fs5 = inquire2("fs");
     function fetch(filename, options, callback) {
       if (typeof options === "function") {
         callback = options;
@@ -14333,8 +14333,8 @@ var require_fetch = __commonJS({
         options = {};
       if (!callback)
         return asPromise(fetch, this, filename, options);
-      if (!options.xhr && fs4 && fs4.readFile)
-        return fs4.readFile(filename, function fetchReadFileCallback(err, contents) {
+      if (!options.xhr && fs5 && fs5.readFile)
+        return fs5.readFile(filename, function fetchReadFileCallback(err, contents) {
           return err && typeof XMLHttpRequest !== "undefined" ? fetch.xhr(filename, options, callback) : err ? callback(err) : callback(null, options.binary ? contents : contents.toString("utf8"));
         });
       return fetch.xhr(filename, options, callback);
@@ -20608,7 +20608,7 @@ var require_util2 = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.addCommonProtos = exports2.loadProtosWithOptionsSync = exports2.loadProtosWithOptions = void 0;
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     var path5 = __require("path");
     var Protobuf = require_protobufjs();
     function addIncludePathResolver(root, includePaths) {
@@ -20620,7 +20620,7 @@ var require_util2 = __commonJS({
         for (const directory of includePaths) {
           const fullPath = path5.join(directory, target);
           try {
-            fs4.accessSync(fullPath, fs4.constants.R_OK);
+            fs5.accessSync(fullPath, fs5.constants.R_OK);
             return fullPath;
           } catch (err) {
             continue;
@@ -30442,7 +30442,7 @@ var require_certificate_provider = __commonJS({
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.FileWatcherCertificateProvider = void 0;
-    var fs4 = __require("fs");
+    var fs5 = __require("fs");
     var logging = require_logging();
     var constants_1 = require_constants();
     var util_1 = __require("util");
@@ -30450,7 +30450,7 @@ var require_certificate_provider = __commonJS({
     function trace(text) {
       logging.trace(constants_1.LogVerbosity.DEBUG, TRACER_NAME, text);
     }
-    var readFilePromise = (0, util_1.promisify)(fs4.readFile);
+    var readFilePromise = (0, util_1.promisify)(fs5.readFile);
     var FileWatcherCertificateProvider = class {
       constructor(config) {
         this.config = config;
@@ -39661,21 +39661,37 @@ var protoLoader = __toESM(require_src2(), 1);
 import { createHmac } from "node:crypto";
 import path3 from "node:path";
 import { fileURLToPath } from "node:url";
+import * as fs3 from "fs";
 var __dirname2 = path3.dirname(fileURLToPath(import.meta.url));
 var PROTO_PATH = path3.resolve(__dirname2, "./proto/intelligence_kernel/v1/kernel.proto");
 function resolveGrpcTarget(endpoint) {
   return endpoint.startsWith("tcp:") ? endpoint.substring(4) : endpoint;
 }
-function resolveGrpcCredentialMode(endpoint) {
+function resolveGrpcCredentialMode(endpoint, tlsMode) {
+  if (tlsMode === "tls") return "tls";
+  if (tlsMode === "insecure") return "insecure";
   const target = resolveGrpcTarget(endpoint).trim();
-  if (target.startsWith("unix:")) {
-    return "insecure";
-  }
+  if (target.startsWith("unix:")) return "insecure";
   const host = extractGrpcHost(target);
   return isLoopbackHost(host) ? "insecure" : "tls";
 }
-function resolveGrpcCredentials(endpoint) {
-  return resolveGrpcCredentialMode(endpoint) === "insecure" ? grpc.credentials.createInsecure() : grpc.credentials.createSsl();
+function resolveGrpcCredentials(endpoint, tlsCaPath, tlsMode) {
+  if (resolveGrpcCredentialMode(endpoint, tlsMode) === "insecure") {
+    return grpc.credentials.createInsecure();
+  }
+  if (tlsCaPath) {
+    let rootCerts;
+    try {
+      rootCerts = fs3.readFileSync(tlsCaPath);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `LibraVDB: failed to load TLS CA certificate from "${tlsCaPath}": ${msg}`
+      );
+    }
+    return grpc.credentials.createSsl(rootCerts, null, null);
+  }
+  return grpc.credentials.createSsl();
 }
 function extractGrpcHost(target) {
   const withoutDnsPrefix = target.startsWith("dns:///") ? target.slice("dns:///".length) : target;
@@ -39708,7 +39724,7 @@ var GrpcKernelClient = class {
     const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
     const kernelService = protoDescriptor.intelligence_kernel.v1.IntelligenceKernel;
     const target = resolveGrpcTarget(options.endpoint);
-    this.client = new kernelService(target, resolveGrpcCredentials(options.endpoint));
+    this.client = new kernelService(target, resolveGrpcCredentials(options.endpoint, options.tlsCaPath, options.tlsMode));
   }
   getMetadata(signed = true) {
     const md = new grpc.Metadata();
@@ -39782,7 +39798,7 @@ var GrpcKernelClient = class {
 };
 
 // src/sidecar.ts
-import fs3 from "node:fs";
+import fs4 from "node:fs";
 import net from "node:net";
 import os3 from "node:os";
 import path4 from "node:path";
@@ -40077,7 +40093,7 @@ function resolveConfiguredEndpoint(cfg) {
 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 defaultEndpoint(platform = process.platform, homeDir = os3.homedir(), pathExists = fs3.existsSync) {
+function defaultEndpoint(platform = process.platform, homeDir = os3.homedir(), pathExists = fs4.existsSync) {
   const envEndpoint = normalizeConfiguredEndpoint(process.env.LIBRAVDB_RPC_ENDPOINT);
   if (envEndpoint) {
     return envEndpoint;
@@ -40175,9 +40191,11 @@ function sleep2(delayMs) {
 }
 
 // src/plugin-runtime.ts
-import { readFileSync as readFileSync2 } from "node:fs";
+import { readFileSync as readFileSync3 } from "node:fs";
 var DEFAULT_RPC_TIMEOUT_MS = 3e4;
 var STARTUP_HEALTH_TIMEOUT_MS = 2e3;
+var VALID_TLS_MODES = ["auto", "tls", "insecure"];
+var isTlsModeValid = (m) => VALID_TLS_MODES.includes(m);
 function resolveStartupHealthTimeoutMs(cfg) {
   return Math.max(STARTUP_HEALTH_TIMEOUT_MS, cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS);
 }
@@ -40210,10 +40228,22 @@ function createPluginRuntime(cfg, logger = console) {
         if (cfg.grpcEndpoint) {
           try {
             const secret = loadSecretFromEnv();
+            if (cfg.grpcEndpointTlsMode !== void 0 && !isTlsModeValid(cfg.grpcEndpointTlsMode)) {
+              throw new Error(
+                `LibraVDB: invalid grpcEndpointTlsMode "${cfg.grpcEndpointTlsMode}" \u2014 must be "auto", "tls", or "insecure"`
+              );
+            }
+            if (cfg.grpcEndpointTlsMode === "insecure" && cfg.grpcEndpointTlsCa) {
+              logger.warn?.(
+                `LibraVDB: grpcEndpointTlsCa is set but grpcEndpointTlsMode is "insecure" \u2014 the CA file will not be used`
+              );
+            }
             kernel = new GrpcKernelClient({
               endpoint: cfg.grpcEndpoint,
               secret,
-              timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS
+              timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+              tlsCaPath: cfg.grpcEndpointTlsCa,
+              tlsMode: cfg.grpcEndpointTlsMode
             });
           } catch (error) {
             logger.warn?.(`LibraVDB: failed to initialize gRPC kernel client: ${formatError(error)}`);
@@ -40282,7 +40312,7 @@ function loadSecretFromEnv() {
   const path5 = process.env.LIBRAVDB_AUTH_SECRET_FILE;
   if (path5) {
     try {
-      return readFileSync2(path5, "utf8").trim();
+      return readFileSync3(path5, "utf8").trim();
     } catch {
       return void 0;
     }

package/dist/plugin-runtime.d.ts

@@ -4,6 +4,8 @@ import type { LoggerLike, PluginConfig } from "./types.js";
 export type RpcGetter = () => Promise<RpcClient>;
 export declare const DEFAULT_RPC_TIMEOUT_MS = 30000;
 export declare const STARTUP_HEALTH_TIMEOUT_MS = 2000;
+export declare const VALID_TLS_MODES: readonly ["auto", "tls", "insecure"];
+export type ValidTlsMode = typeof VALID_TLS_MODES[number];
 export declare function resolveStartupHealthTimeoutMs(cfg: PluginConfig): number;
 export interface LifecycleHint {
     hook: "before_reset" | "session_end";

package/dist/plugin-runtime.js

@@ -5,6 +5,8 @@ import { formatError } from "./format-error.js";
 import { readFileSync } from "node:fs";
 export const DEFAULT_RPC_TIMEOUT_MS = 30000;
 export const STARTUP_HEALTH_TIMEOUT_MS = 2000;
+export const VALID_TLS_MODES = ["auto", "tls", "insecure"];
+const isTlsModeValid = (m) => VALID_TLS_MODES.includes(m);
 export function resolveStartupHealthTimeoutMs(cfg) {
     return Math.max(STARTUP_HEALTH_TIMEOUT_MS, cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS);
 }
@@ -39,10 +41,23 @@ export function createPluginRuntime(cfg, logger = console) {
                 if (cfg.grpcEndpoint) {
                     try {
                         const secret = loadSecretFromEnv();
+                        if (cfg.grpcEndpointTlsMode !== undefined &&
+                            !isTlsModeValid(cfg.grpcEndpointTlsMode)) {
+                            throw new Error(`LibraVDB: invalid grpcEndpointTlsMode "${cfg.grpcEndpointTlsMode}" — ` +
+                                `must be "auto", "tls", or "insecure"`);
+                        }
+                        if (cfg.grpcEndpointTlsMode === "insecure" &&
+                            cfg.grpcEndpointTlsCa) {
+                            // logger is provided by the host and may not have all methods
+                            logger.warn?.(`LibraVDB: grpcEndpointTlsCa is set but grpcEndpointTlsMode ` +
+                                `is "insecure" — the CA file will not be used`);
+                        }
                         kernel = new GrpcKernelClient({
                             endpoint: cfg.grpcEndpoint,
                             secret,
                             timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+                            tlsCaPath: cfg.grpcEndpointTlsCa,
+                            tlsMode: cfg.grpcEndpointTlsMode,
                         });
                     }
                     catch (error) {

package/dist/types.d.ts

@@ -90,6 +90,12 @@ export interface PluginConfig {
     maxRetries?: number;
     logLevel?: "debug" | "info" | "warn" | "error";
     grpcEndpoint?: string;
+    grpcEndpointTlsCa?: string;
+    /** Controls gRPC credential mode.
+     * "auto" (default) — loopback and unix → plaintext, remote → TLS.
+     * "tls"            — always use TLS regardless of address.
+     * "insecure"       — always use plaintext (service mesh, tunnel). */
+    grpcEndpointTlsMode?: "auto" | "tls" | "insecure";
 }
 export interface SearchResult {
     id: string;

package/docs/TLS_configuration.md

@@ -0,0 +1,112 @@
+# TLS Configuration
+
+The plugin selects the right credentials automatically based on which address it connects to. Unix sockets and loopback addresses (localhost, 127.0.0.1, ::1) always use plaintext. All other addresses use TLS. In most deployments no TLS configuration is needed at all. The only time manual configuration is required is when the daemon serves TLS on a loopback address, when the daemon uses a self-signed or private-CA certificate, or when infrastructure such as a service mesh handles TLS outside the plugin.
+
+## Default behavior
+
+The plugin applies the following rules automatically:
+
+| Endpoint type | Credential mode |
+|---|---|
+| Unix socket (`unix:/path/to/socket`) | Plaintext |
+| Loopback (`tcp:127.0.0.1:port`, `tcp:localhost:port`, `[::1]:port`) | Plaintext |
+| Any other TCP or DNS address | TLS |
+
+Because these rules are automatic, most users do not set any TLS-related fields. Plaintext is used where it is safe (local transport) and TLS is used where it is needed (network transport).
+
+## Configuration fields
+
+| Field | Type | Default | When to use |
+|---|---|---|---|
+| `grpcEndpoint` | string | — | The daemon address. Set to a unix socket path, a loopback address, or a remote host. |
+| `grpcEndpointTlsCa` | string | — | Path to a CA certificate PEM file. Required only when the daemon certificate is self-signed or signed by a private CA not in the system certificate store. |
+| `grpcEndpointTlsMode` | `"auto"` \| `"tls"` \| `"insecure"` | `"auto"` | Override the automatic selection. `"auto"` applies the default rules above. `"tls"` forces TLS regardless of address. `"insecure"` forces plaintext regardless of address. |
+
+`grpcEndpointTlsMode` values explained:
+
+- **`"auto"`** (default) — apply the automatic rules. Unix sockets and loopback use plaintext; all other addresses use TLS.
+- **`"tls"`** — always use TLS, even for loopback addresses. Use this when the daemon has TLS enabled on a loopback address.
+- **`"insecure"`** — always use plaintext, even for remote addresses. Use this only when a service mesh or TLS-terminating tunnel handles encryption externally.
+
+## Deployment scenarios
+
+### Local daemon (default)
+
+The daemon runs on the same machine, listening on a unix socket or a loopback address.
+
+```json
+{
+  "grpcEndpoint": "unix:/home/user/.libravdbd/run/libravdb.sock"
+}
+```
+
+or:
+
+```json
+{
+  "grpcEndpoint": "tcp:127.0.0.1:9090"
+}
+```
+
+The plugin automatically uses plaintext. No TLS fields are needed.
+
+### Remote daemon with a trusted certificate
+
+The daemon runs on a remote host and presents a certificate issued by a public CA such as Let's Encrypt or cert-manager.
+
+```json
+{
+  "grpcEndpoint": "tcp:libravdb.k8s.internal:9090"
+}
+```
+
+TLS is automatic. The plugin uses the system certificate store to verify the daemon's certificate, so no additional configuration is needed.
+
+### Remote daemon with a self-signed or private CA certificate
+
+The daemon runs on a remote host and uses a self-signed certificate or a certificate signed by a private/internal CA not in the system certificate store.
+
+```json
+{
+  "grpcEndpoint": "tcp:libravdb.internal:9090",
+  "grpcEndpointTlsCa": "/etc/certs/company-ca.pem"
+}
+```
+
+The CA certificate must be the certificate of the CA that signed the daemon's server certificate — not the server certificate itself. The plugin uses this CA to verify the daemon's certificate during the TLS handshake. Without it, the plugin will reject the daemon's certificate as untrusted.
+
+### TLS on a loopback address
+
+The daemon has TLS enabled on a loopback address. This is uncommon. The automatic rules would select plaintext for a loopback address, so an explicit override is required.
+
+```json
+{
+  "grpcEndpoint": "tcp:127.0.0.1:9090",
+  "grpcEndpointTlsMode": "tls"
+}
+```
+
+Set `grpcEndpointTlsMode` to `"tls"` to force the plugin to use TLS even on the loopback address. The plugin will use the system certificate store for verification. If the daemon uses a self-signed certificate, add `grpcEndpointTlsCa` as well.
+
+## Service mesh and tunnels
+
+When the daemon runs behind Istio, Envoy, or any other infrastructure that terminates TLS at the mesh or tunnel layer, the plugin should not attempt its own TLS. Set `grpcEndpointTlsMode` to `"insecure"` so the plugin uses plaintext and lets the mesh handle encryption:
+
+```json
+{
+  "grpcEndpoint": "tcp:libravdb.mesh.svc:9090",
+  "grpcEndpointTlsMode": "insecure"
+}
+```
+
+This applies even for remote addresses. The mesh terminates TLS at the boundary, and the plugin communicates with the mesh over plaintext on the inside.
+
+## Error reference
+
+| Error | Likely cause | Fix |
+|---|---|---|
+| `UNAVAILABLE / connection closed / TLS handshake failed` when connecting to a loopback address | The daemon has TLS enabled on a loopback address but the plugin is using plaintext (the default for loopback). | Add `"grpcEndpointTlsMode": "tls"` to the plugin config. |
+| `x509: certificate signed by unknown authority` | The daemon uses a self-signed certificate or a certificate from a private CA not trusted by the system. | Set `grpcEndpointTlsCa` to the path of the CA certificate PEM file that signed the daemon's server certificate. |
+| `failed to load TLS CA certificate from "...": ENOENT: no such file or directory` | The file path given in `grpcEndpointTlsCa` does not exist on the machine. | Verify the file path is correct and the CA certificate file exists. |
+| `LibraVDB: invalid grpcEndpointTlsMode "..."` | The value set in `grpcEndpointTlsMode` is not one of the accepted values. | Change the value to `"auto"`, `"tls"`, or `"insecure"`. |
+| `LIBRAVDB: grpcEndpointTlsCa is set but grpcEndpointTlsMode is "insecure"` (warning) | Both `grpcEndpointTlsCa` and `grpcEndpointTlsMode: "insecure"` are set. The CA file will not be used. | Remove `grpcEndpointTlsCa` if plaintext is intended, or change `grpcEndpointTlsMode` to `"auto"` or `"tls"` to use the CA file. |

package/docs/configuration.md

@@ -12,10 +12,60 @@ CPU when a provider is unavailable.
 | Key | Type | Default | Notes |
 |---|---|---|---|
 | `sidecarPath` | string | `auto` | `"auto"` probes standard socket paths; set `unix:/path` or `tcp:host:port` to override |
-| `grpcEndpoint` | string | — | Optional gRPC kernel endpoint for hosts using the gRPC kernel transport |
+| `grpcEndpoint` | string | — | gRPC kernel endpoint. See `grpcEndpointTlsMode` for credential control. |
+| `grpcEndpointTlsCa` | string | — | Path to CA certificate PEM file. Only needed for self-signed or private CA certs. Omit when using Let's Encrypt or cert-manager. |
+| `grpcEndpointTlsMode` | string | `"auto"` | gRPC credential mode. `"auto"`: loopback/unix → plaintext, remote → TLS. `"tls"`: always TLS. `"insecure"`: always plaintext. |
 | `rpcTimeoutMs` | number | `30000` | Per-call timeout for service RPC (ms) |
 | `dbPath` | string | auto-named | Explicit DB path; when set bypasses model-specific naming |
 
+### gRPC TLS behavior
+
+The plugin selects credentials automatically based on the endpoint:
+
+| Endpoint format | Credential mode |
+|---|---|
+| `unix:/path/to/sock` | Plaintext (local) |
+| `tcp:127.0.0.1:port` / `tcp:localhost:port` / `[::1]:port` | Plaintext (loopback) |
+| Any other TCP or DNS target | TLS |
+
+Use `grpcEndpointTlsMode` to override the default behavior:
+
+| Value | When to use |
+|---|---|
+| `"auto"` (default) | Standard operation — plugin heuristic matches daemon TLS setting automatically. |
+| `"tls"` | Daemon has TLS enabled on loopback or unix socket (rare; use when the daemon's `LIBRAVDB_GRPC_TLS_*` env vars are set on a local address). |
+| `"insecure"` | Service mesh or TLS-terminating tunnel handles encryption externally; both sides are plaintext. |
+
+**Default (local daemon):** No TLS configuration needed.
+Unix socket and loopback endpoints are always plaintext regardless
+of any TLS settings.
+
+**K8 / remote daemon with CA-issued cert:**
+No extra configuration needed. The plugin uses the system CA pool,
+which trusts certs issued by Let's Encrypt, cert-manager, and
+other public CAs automatically.
+
+**Remote daemon with self-signed or private CA cert:**
+Set `grpcEndpointTlsCa` to the path of the CA certificate PEM file:
+```json
+{
+  "grpcEndpoint": "tcp:yourdaemon.internal:50051",
+  "grpcEndpointTlsCa": "/etc/certs/ca.pem"
+}
+```
+The daemon must be configured with matching TLS cert and key via
+`LIBRAVDB_GRPC_TLS_CERT` and `LIBRAVDB_GRPC_TLS_KEY`.
+
+**Local daemon with TLS enabled:**
+If the daemon has `LIBRAVDB_GRPC_TLS_CERT`/`LIBRAVDB_GRPC_TLS_KEY` set on a loopback
+address, explicitly set `grpcEndpointTlsMode: "tls"` to match:
+```json
+{
+  "grpcEndpoint": "tcp:127.0.0.1:9090",
+  "grpcEndpointTlsMode": "tls"
+}
+```
+
 ## Embedding
 
 | Key | Type | Default | Notes |

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.4.80",
+  "version": "1.5.0",
   "kind": [
     "memory",
     "context-engine"
@@ -46,6 +46,19 @@
         "type": "string",
         "description": "Optional gRPC kernel endpoint for hosts using the daemon kernel transport."
       },
+      "grpcEndpointTlsCa": {
+        "type": "string",
+        "description": "Path to a CA certificate PEM file for verifying the daemon's TLS certificate. Only needed for self-signed or private CA certificates. Not required when using a publicly trusted certificate (Let's Encrypt, cert-manager, etc)."
+      },
+      "grpcEndpointTlsMode": {
+        "type": "string",
+        "enum": [
+          "auto",
+          "tls",
+          "insecure"
+        ],
+        "description": "gRPC credential mode. auto (default): loopback and unix socket use plaintext, remote addresses use TLS. tls: always use TLS regardless of address. insecure: always use plaintext (use with service mesh or tunnel that handles TLS externally)."
+      },
       "authoredHardBudgetFraction": {
         "type": "number",
         "minimum": 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.4.80",
+  "version": "1.5.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -43,7 +43,7 @@
       "pluginSdkVersion": "2026.4.11"
     },
     "install": {
-      "minHostVersion": ">=2026.3.22"
+      "minHostVersion": ">=2026.4.11"
     }
   },
   "scripts": {