@xdarkicex/openclaw-memory-libravdb 1.6.25 → 1.6.28

package/dist/libravdb-client.d.ts

@@ -10,6 +10,9 @@ export interface LibravDBClientOptions {
     tlsMode?: "auto" | "tls" | "insecure";
     tlsClientCertPath?: string;
     tlsClientKeyPath?: string;
+    /** Stable tenant key for multi-agent DB routing. Attached as the
+     *  `libravdb-tenant-key` gRPC metadata header on every call. */
+    tenantKey?: string;
 }
 export declare function resolveClientEndpoint(configuredEndpoint?: string): string;
 export declare function isLegacyJsonRpcHealthResponse(payload: string): boolean;

package/dist/libravdb-client.js

@@ -19,6 +19,8 @@ export function resolveClientEndpoint(configuredEndpoint) {
         path.join(os.homedir(), ".libravdbd", "run"),
         "/opt/homebrew/var/libravdbd/run",
         "/usr/local/var/libravdbd/run",
+        "/var/run/libravdbd",
+        "/run/libravdbd",
     ];
     for (const dir of candidateDirs) {
         const fullPath = path.join(dir, sockName);
@@ -178,6 +180,15 @@ export class LibravDBClient {
             bootstrap: () => self.bootstrapHandshake(),
             rpcMutex,
         });
+        const interceptors = [];
+        if (options.tenantKey) {
+            const tenantKey = options.tenantKey;
+            interceptors.push((next) => async (req) => {
+                req.header.set("libravdb-tenant-key", tenantKey);
+                return next(req);
+            });
+        }
+        interceptors.push(authInterceptor);
         const transport = createGrpcTransport({
             baseUrl: targetUrl,
             httpVersion: "2",
@@ -190,7 +201,7 @@ export class LibravDBClient {
                     ...(isInsecure ? { rejectUnauthorized: false } : {}),
                 },
             defaultTimeoutMs: options.timeoutMs ?? 30000,
-            interceptors: [authInterceptor],
+            interceptors,
         });
         this.client = createPromiseClient(LibravDB, transport);
     }

package/dist/manifest.d.ts

@@ -0,0 +1,46 @@
+export interface TurnEntry {
+    index: number;
+    role: string;
+    contentHash: string;
+    turnHash: string;
+    ingestedAt: number;
+}
+export interface TurnManifest {
+    sessionId: string;
+    version: number;
+    turns: TurnEntry[];
+    tailHash: string;
+}
+export interface KernelCompatibleMessage {
+    role: string;
+    content: string;
+    id?: string;
+}
+export declare class TurnManifestStore {
+    private manifestDir;
+    constructor();
+    private getManifestPath;
+    hashString(data: string): string;
+    createEmpty(sessionId: string): TurnManifest;
+    load(sessionId: string, logger?: {
+        warn?: (msg: string) => void;
+        error?: (msg: string, e: unknown) => void;
+    }): TurnManifest;
+    save(manifest: TurnManifest): void;
+    verifyChain(manifest: TurnManifest): boolean;
+    /**
+     * Finds the overlap point between incoming messages and our stored history.
+     * Returns the index into incomingMessages where new (un-ACKed) messages begin.
+     * Returns 0 if no overlap (full re-sync).
+     */
+    findOverlapIndex(manifest: TurnManifest, incomingMessages: KernelCompatibleMessage[]): number;
+    appendACKedMessages(manifest: TurnManifest, newMessages: KernelCompatibleMessage[], startingIndex: number): TurnManifest;
+    /**
+     * Determines the absolute starting index for a set of new messages.
+     * If we have stored turns, the next message's index is last_turn.index + 1.
+     * If the manifest is empty, we infer from OpenClaw's prePromptMessageCount signal
+     * (caller must provide this as a hint when available).
+     */
+    deriveStartingIndex(manifest: TurnManifest, prePromptMessageCountHint?: number): number;
+}
+export declare const manifestStore: TurnManifestStore;

package/dist/manifest.js

@@ -0,0 +1,127 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import * as os from "os";
+export class TurnManifestStore {
+    manifestDir;
+    constructor() {
+        this.manifestDir = path.join(os.homedir(), ".openclaw", "libravdb-manifests");
+        if (!fs.existsSync(this.manifestDir)) {
+            fs.mkdirSync(this.manifestDir, { recursive: true });
+        }
+    }
+    getManifestPath(sessionId) {
+        const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, "_");
+        return path.join(this.manifestDir, `${safe}.manifest.json`);
+    }
+    hashString(data) {
+        return crypto.createHash("sha256").update(data).digest("hex");
+    }
+    createEmpty(sessionId) {
+        return {
+            sessionId,
+            version: 0,
+            turns: [],
+            tailHash: "0000000000000000000000000000000000000000000000000000000000000000",
+        };
+    }
+    load(sessionId, logger) {
+        const filePath = this.getManifestPath(sessionId);
+        if (!fs.existsSync(filePath)) {
+            return this.createEmpty(sessionId);
+        }
+        try {
+            const raw = fs.readFileSync(filePath, "utf8");
+            const manifest = JSON.parse(raw);
+            if (!this.verifyChain(manifest)) {
+                logger?.warn?.(`[LibraVDB] Manifest chain broken for session ${sessionId}. Forcing re-sync.`);
+                return this.createEmpty(sessionId);
+            }
+            return manifest;
+        }
+        catch (e) {
+            logger?.error?.(`[LibraVDB] Failed to read manifest for ${sessionId}:`, e);
+            return this.createEmpty(sessionId);
+        }
+    }
+    save(manifest) {
+        const filePath = this.getManifestPath(manifest.sessionId);
+        const tempPath = `${filePath}.${process.pid}.tmp`;
+        fs.writeFileSync(tempPath, JSON.stringify(manifest, null, 2), "utf8");
+        fs.renameSync(tempPath, filePath);
+    }
+    verifyChain(manifest) {
+        let currentHash = "0000000000000000000000000000000000000000000000000000000000000000";
+        for (const turn of manifest.turns) {
+            const expectedHash = this.hashString(`${turn.index}${turn.role}${turn.contentHash}${currentHash}`);
+            if (turn.turnHash !== expectedHash) {
+                return false;
+            }
+            currentHash = expectedHash;
+        }
+        return manifest.tailHash === currentHash;
+    }
+    /**
+     * Finds the overlap point between incoming messages and our stored history.
+     * Returns the index into incomingMessages where new (un-ACKed) messages begin.
+     * Returns 0 if no overlap (full re-sync).
+     */
+    findOverlapIndex(manifest, incomingMessages) {
+        if (manifest.turns.length === 0) {
+            return 0;
+        }
+        // Build a map of contentHash → index in our manifest
+        const known = new Map();
+        for (const turn of manifest.turns) {
+            known.set(turn.contentHash, turn.index);
+        }
+        // Scan incoming messages from newest to oldest to find the last match
+        for (let i = incomingMessages.length - 1; i >= 0; i--) {
+            const contentHash = this.hashString(incomingMessages[i].content);
+            if (known.has(contentHash)) {
+                return i + 1; // everything at and after this index is new
+            }
+        }
+        // No overlap found — OpenClaw trimmed too much or session diverged
+        return 0;
+    }
+    appendACKedMessages(manifest, newMessages, startingIndex) {
+        let currentHash = manifest.tailHash;
+        const newTurns = [];
+        for (let i = 0; i < newMessages.length; i++) {
+            const msg = newMessages[i];
+            const absoluteIndex = startingIndex + i;
+            const contentHash = this.hashString(msg.content);
+            currentHash = this.hashString(`${absoluteIndex}${msg.role}${contentHash}${currentHash}`);
+            newTurns.push({
+                index: absoluteIndex,
+                role: msg.role,
+                contentHash,
+                turnHash: currentHash,
+                ingestedAt: Date.now(),
+            });
+        }
+        return {
+            sessionId: manifest.sessionId,
+            version: manifest.version + 1,
+            turns: [...manifest.turns, ...newTurns],
+            tailHash: currentHash,
+        };
+    }
+    /**
+     * Determines the absolute starting index for a set of new messages.
+     * If we have stored turns, the next message's index is last_turn.index + 1.
+     * If the manifest is empty, we infer from OpenClaw's prePromptMessageCount signal
+     * (caller must provide this as a hint when available).
+     */
+    deriveStartingIndex(manifest, prePromptMessageCountHint) {
+        if (manifest.turns.length > 0) {
+            return manifest.turns[manifest.turns.length - 1].index + 1;
+        }
+        // Empty manifest — use OpenClaw's signal if provided, else assume 0
+        return typeof prePromptMessageCountHint === "number" && prePromptMessageCountHint >= 0
+            ? prePromptMessageCountHint
+            : 0;
+    }
+}
+export const manifestStore = new TurnManifestStore();

package/dist/memory-runtime.js

@@ -74,18 +74,22 @@ function createMemorySearchManager(getClient, cfg, defaults, initialStatus) {
             const filteredResults = minScore === undefined
                 ? result.results
                 : result.results.filter((item) => item.score >= minScore);
-            const legacyResults = filteredResults.map((item) => ({
-                ...item,
-                content: item.text,
-            }));
+            const legacyResults = filteredResults.map((item) => {
+                const meta = parseMetadataJson(item);
+                return {
+                    ...item,
+                    content: item.text || (typeof meta.text === "string" ? meta.text : ""),
+                };
+            });
             if (legacyCall) {
                 return { results: legacyResults };
             }
             const memoryResults = filteredResults.map((item) => {
                 const meta = parseMetadataJson(item);
                 const collection = typeof meta.collection === "string" ? meta.collection : "memory";
+                const effectiveText = item.text || (typeof meta.text === "string" ? meta.text : "") || "";
                 const relPath = encodeSearchResultPath(collection, item.id);
-                returnedSearchPaths.set(relPath, item.text);
+                returnedSearchPaths.set(relPath, effectiveText);
                 return toMemorySearchResult(item);
             });
             return memoryResults;
@@ -194,12 +198,13 @@ function parseMetadataJson(item) {
 function toMemorySearchResult(item) {
     const meta = parseMetadataJson(item);
     const collection = typeof meta.collection === "string" ? meta.collection : "memory";
+    const effectiveText = item.text || (typeof meta.text === "string" ? meta.text : "") || "";
     return {
         path: encodeSearchResultPath(collection, item.id),
         startLine: 1,
-        endLine: Math.max(1, item.text.split("\n").length),
+        endLine: Math.max(1, effectiveText.split("\n").length),
         score: item.score,
-        snippet: item.text,
+        snippet: effectiveText,
         source: collection.startsWith("session:") || collection.startsWith("session_") ? "sessions" : "memory",
         citation: `${collection}:${item.id}`,
     };

package/dist/plugin-runtime.d.ts

@@ -1,7 +1,7 @@
 import { LibravDBClient } from "./libravdb-client.js";
 import type { LoggerLike, PluginConfig } from "./types.js";
 export type ClientGetter = () => Promise<LibravDBClient>;
-export declare const DEFAULT_RPC_TIMEOUT_MS = 30000;
+export declare const DEFAULT_RPC_TIMEOUT_MS = 120000;
 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];

package/dist/plugin-runtime.js

@@ -1,13 +1,19 @@
 import { LibravDBClient, resolveClientEndpoint } from "./libravdb-client.js";
 import { formatError } from "./format-error.js";
+import { resolveTenantKey } from "./identity.js";
 import { existsSync, statSync } from "node:fs";
 import path from "node:path";
-export const DEFAULT_RPC_TIMEOUT_MS = 30000;
+export const DEFAULT_RPC_TIMEOUT_MS = 120_000;
 export const STARTUP_HEALTH_TIMEOUT_MS = 2000;
+const ENV_RPC_TIMEOUT_MS = (() => {
+    const raw = Number(process.env.LIBRAVDB_RPC_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : 0;
+})();
 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);
+    const timeout = cfg.rpcTimeoutMs ?? (ENV_RPC_TIMEOUT_MS || DEFAULT_RPC_TIMEOUT_MS);
+    return Math.max(STARTUP_HEALTH_TIMEOUT_MS, timeout);
 }
 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.";
@@ -48,11 +54,12 @@ export function createPluginRuntime(cfg, logger = console) {
                 validateTlsConfig(cfg, logger);
                 client = new LibravDBClient({
                     endpoint: cfg.grpcEndpoint || cfg.sidecarPath,
-                    timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+                    timeoutMs: cfg.rpcTimeoutMs ?? (ENV_RPC_TIMEOUT_MS || DEFAULT_RPC_TIMEOUT_MS),
                     tlsCaPath: cfg.grpcEndpointTlsCa,
                     tlsMode: cfg.grpcEndpointTlsMode,
                     tlsClientCertPath: cfg.grpcEndpointTlsClientCert,
                     tlsClientKeyPath: cfg.grpcEndpointTlsClientKey,
+                    tenantKey: resolveTenantKey(cfg),
                 });
                 await client.bootstrapHandshake();
                 return client;

package/dist/types.d.ts

@@ -2,6 +2,11 @@ export interface PluginConfig {
     dbPath?: string;
     /** Legacy fallback alias for grpcEndpoint. */
     sidecarPath?: string;
+    /** Stable tenant identifier for multi-agent deployments. When set, the daemon
+     *  routes this plugin instance to an isolated vector database. When unset,
+     *  the plugin falls back to the auto-derived userId. Set different values per
+     *  agent to isolate memory storage. */
+    tenantId?: string;
     /** Stable identity for cross-session durable memory. When set, all sessions
      *  share memories under user:{userId}. When unset, the plugin auto-derives
      *  identity from the OS and persists it to the identity file. */

package/docs/configuration.md

@@ -87,8 +87,8 @@ 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`, `custom-local`, or `remote` |
-| `onnxDevice` | string | `auto` | ONNX execution provider: `auto`, `cpu`, `coreml` (macOS), `cuda` (Linux/Windows), `directml` (Windows), `openvino` (Linux) |
+| `embeddingBackend` | string | — | `gguf` (recommended default), `bundled`, `onnx-local`, `custom-local`, or `remote` |
+| `onnxDevice` | string | `cpu` | ONNX execution provider: `auto`, `cpu`, `coreml` (macOS), `cuda` (Linux/Windows), `directml` (Windows), `openvino` (Linux) |
 | `embeddingRuntimePath` | string | — | Path to ONNX runtime library visible to the vector service (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 |

package/docs/embedding-profiles.md

@@ -9,7 +9,8 @@ Default selection baseline:
 
 Why:
 
-- Nomic is the default because its Matryoshka-trained embeddings deliver significantly higher retrieval accuracy than MiniLM, with principled dimensionality tiering (`64d → 256d → 768d`) that lets the vector service trade memory for precision without re-embedding.
+- GGUF is the recommended default and preferred backend for local embedding. It delivers Matryoshka-trained `nomic-embed-text-v1.5` embeddings with no ONNX Runtime dependency and hardware-native acceleration on Apple Silicon (Metal), NVIDIA (CUDA), and CPU.
+- `bundled` uses the ONNX build of `nomic-embed-text-v1.5` and is the full-featured fallback when GGUF is unavailable.
 - bge-small-en-v1.5 is the fallback for resource-constrained systems and is automatically selected when the primary model's dimensions do not match the active collection.
 - Intel Macs without reliable Metal/MPS support should set `onnxDevice: "cpu"` to force CPU ONNX execution and bypass CoreML.
 
@@ -33,7 +34,7 @@ How it works:
 - `onnx-local` still requires local model assets through `embeddingModelPath`, typically a directory containing `embedding.json`.
 - The manifest may override or refine the profile, but explicit dimension mismatches fail closed.
 - The vector service store persists an embedding fingerprint, so reopening an existing store with a different effective model profile will fail instead of silently mixing vector spaces.
-- `onnxDevice` is passed through as `LIBRAVDB_ONNX_DEVICE` for vector service versions that support execution-provider selection (`auto`, `cpu`, `cuda`, `coreml`, `directml`, `openvino`).
+- `onnxDevice` is passed through as `LIBRAVDB_ONNX_DEVICE` for vector service versions that support execution-provider selection (`auto`, `cpu` (default), `cuda`, `coreml`, `directml`, `openvino`).
 
 ## Store Compatibility and Upgrades
 
@@ -65,6 +66,7 @@ Do not delete the old store until the replacement has been verified.
 
 Recommended usage:
 
-- `bundled` for the shipped default path, which uses `nomic-embed-text-v1.5`.
+- `gguf` for the recommended local embedding path, using `nomic-embed-text-v1.5` with hardware-native acceleration and no ONNX Runtime dependency.
+- `bundled` for the ONNX build of `nomic-embed-text-v1.5` when GGUF is unavailable.
 - `onnx-local` plus `embeddingProfile` when a power user wants a known model family with local assets.
 - treat remote/Ollama providers as future separate backend types, not as overloads of `custom-local`.

package/docs/installation.md

@@ -231,12 +231,20 @@ libravdbd serve
 
 ### Deterministic fallback embeddings
 
-If vector service logs mention deterministic fallback mode, the vector service did not find the
-configured ONNX runtime or model manifest. Stop the vector service, 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.
+If the vector service falls back to deterministic embeddings, it could not locate
+the configured ONNX runtime or model assets. The service will still run but all
+embedding operations will fail until resolved.
+
+To resolve: stop the vector service, then set `LIBRAVDB_ONNX_RUNTIME` to the
+full path of the ONNX runtime library (e.g. `libonnxruntime.so` or
+`libonnxruntime.dylib`) and `LIBRAVDB_EMBEDDING_MODEL` to the model directory
+containing `embedding.json`. Verify the model directory also contains the
+corresponding `.onnx` model file and `tokenizer.json`.
+
+If a database was created while the service was in fallback mode, move that
+`.libravdb` file and its adjacent `.embedding.json` aside before restarting —
+a store initialized with deterministic embeddings is incompatible with ONNX-backed
+operation.
 
 ### Incompatible database or embedding profile
 

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.25",
+  "version": "1.6.28",
   "kind": [
     "memory",
     "context-engine"
@@ -63,6 +63,10 @@
       "sidecarPath": {
         "type": "string"
       },
+      "tenantId": {
+        "type": "string",
+        "description": "Stable tenant identifier for multi-agent deployments. When set, the daemon routes this plugin instance to an isolated vector database. When unset, the plugin falls back to the auto-derived userId. Set different values per agent to isolate memory storage."
+      },
       "userId": {
         "type": "string",
         "description": "Stable identity for cross-session durable memory. When set, sessions share memories under user:{userId}."
@@ -440,7 +444,8 @@
       },
       "rpcTimeoutMs": {
         "type": "number",
-        "default": 30000
+        "default": 120000,
+        "description": "gRPC timeout in milliseconds for daemon calls. Default: 120000 (2 min). Can also be set via LIBRAVDB_RPC_TIMEOUT_MS env var."
       },
       "maxRetries": {
         "type": "number"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.6.25",
+  "version": "1.6.28",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -79,6 +79,6 @@
   "dependencies": {
     "@connectrpc/connect": "^1.7.0",
     "@connectrpc/connect-node": "^1.7.0",
-    "@xdarkicex/libravdb-contracts": "^2.0.8"
+    "@xdarkicex/libravdb-contracts": "^2.0.12"
   }
 }