@xdarkicex/openclaw-memory-libravdb 1.6.23 → 1.6.27

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/markdown-ingest.js

@@ -147,6 +147,14 @@ class DirectoryMarkdownSourceAdapter {
         if (!this.started || this.stopping) {
             return;
         }
+        // Cancel any pending scheduled scans so they don't race with this refresh
+        for (const state of this.states.values()) {
+            if (state.scanState.timer) {
+                clearTimeout(state.scanState.timer);
+                state.scanState.timer = null;
+            }
+            state.scanState.dirty = false;
+        }
         for (const root of this.roots) {
             await this.scanRoot(root);
         }
@@ -291,11 +299,11 @@ class DirectoryMarkdownSourceAdapter {
                 continue;
             }
             stats.filesIncluded++;
-            currentFiles.add(child);
             const stat = await this.safeStatWithCtime(child);
             if (!stat) {
                 continue;
             }
+            currentFiles.add(child);
             candidates.push({ path: child, size: stat.size, mtimeMs: stat.mtimeMs, ctimeMs: stat.ctimeMs, ordinal: candidates.length });
         }
     }
@@ -310,7 +318,10 @@ class DirectoryMarkdownSourceAdapter {
                 this.lastRetryAfterMs = 0;
             }
             else {
+                // Resume cursor target was deleted — clear it and resume normal processing
                 rootState.scanState.resumeFromPath = null;
+                this.lastAcceptMore = true;
+                this.lastRetryAfterMs = 0;
             }
         }
         for (const candidate of sorted) {
@@ -439,6 +450,8 @@ class DirectoryMarkdownSourceAdapter {
     async syncMarkdownFile(rootState, filePath, initialStat) {
         const sourceDoc = filePath;
         const relativePath = toPosixPath(path.relative(rootState.root, filePath));
+        // Re-check existence when initialStat is provided — the file may have been
+        // deleted between the scan pass and the sync pass.
         const stat = initialStat ?? (await this.safeStatWithCtime(filePath));
         if (!stat) {
             await this.deleteSourceDocument(sourceDoc);

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/README.md

@@ -6,14 +6,14 @@ deeper by goal.
 
 ## Start Here
 
-- [Install](./install.md) - shortest supported install and daemon lifecycle path.
+- [Install](./install.md) - shortest supported install and vector service lifecycle path.
 - [Installation reference](./installation.md) - requirements, activation, verification, and troubleshooting.
-- [Uninstall](./uninstall.md) - safe disable, daemon shutdown, package removal, and optional data cleanup.
+- [Uninstall](./uninstall.md) - safe disable, vector service shutdown, package removal, and optional data cleanup.
 
 ## Understand The System
 
 - [Problem](./problem.md) - why this plugin replaces the stock memory lifecycle.
-- [Architecture](./architecture.md) - plugin, sidecar, storage, retrieval, and compaction overview.
+- [Architecture](./architecture.md) - plugin, vector service, storage, retrieval, and compaction overview.
 - [Dependency rationale](./dependencies.md) - why LibraVDB and slab-style storage fit this workload.
 - [Architecture decisions](./architecture-decisions/README.md) - accepted ADRs.
 
@@ -27,5 +27,5 @@ deeper by goal.
 ## Advanced And Source Docs
 
 - [Performance and tuning](./performance-and-tuning.md) - resource expectations and tuning knobs.
-- [Development](./development.md) - source setup, local daemon builds, generated IPC files, and validation commands.
+- [Development](./development.md) - source setup, local vector service builds, generated IPC files, and validation commands.
 - [Contributing](./contributing.md) - contributor workflow and repository expectations.

package/docs/TLS_configuration.md

@@ -1,6 +1,6 @@
 # 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.
+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 vector service serves TLS on a loopback address, when the vector service uses a self-signed or private-CA certificate, or when infrastructure such as a service mesh handles TLS outside the plugin.
 
 ## Default behavior
 
@@ -18,21 +18,21 @@ Because these rules are automatic, most users do not set any TLS-related 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. |
+| `grpcEndpoint` | string | — | The vector service 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 vector service 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.
+- **`"tls"`** — always use TLS, even for loopback addresses. Use this when the vector service 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)
+### Local vector service (default)
 
-The daemon runs on the same machine, listening on a unix socket or a loopback address.
+The vector service runs on the same machine, listening on a unix socket or a loopback address.
 
 ```json
 {
@@ -50,9 +50,9 @@ or:
 
 The plugin automatically uses plaintext. No TLS fields are needed.
 
-### Remote daemon with a trusted certificate
+### Remote vector service 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.
+The vector service runs on a remote host and presents a certificate issued by a public CA such as Let's Encrypt or cert-manager.
 
 ```json
 {
@@ -60,11 +60,11 @@ The daemon runs on a remote host and presents a certificate issued by a public C
 }
 ```
 
-TLS is automatic. The plugin uses the system certificate store to verify the daemon's certificate, so no additional configuration is needed.
+TLS is automatic. The plugin uses the system certificate store to verify the vector service's certificate, so no additional configuration is needed.
 
-### Remote daemon with a self-signed or private CA certificate
+### Remote vector service 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.
+The vector service 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
 {
@@ -73,11 +73,11 @@ The daemon runs on a remote host and uses a self-signed certificate or a certifi
 }
 ```
 
-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.
+The CA certificate must be the certificate of the CA that signed the vector service's server certificate — not the server certificate itself. The plugin uses this CA to verify the vector service's certificate during the TLS handshake. Without it, the plugin will reject the vector service'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.
+The vector service 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
 {
@@ -86,11 +86,11 @@ The daemon has TLS enabled on a loopback address. This is uncommon. The automati
 }
 ```
 
-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.
+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 vector service 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:
+When the vector service 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
 {
@@ -105,8 +105,8 @@ This applies even for remote addresses. The mesh terminates TLS at the boundary,
 
 | 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. |
+| `UNAVAILABLE / connection closed / TLS handshake failed` when connecting to a loopback address | The vector service 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 vector service 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 vector service'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/architecture-decisions/adr-004-sidecar-over-native-ts.md

@@ -6,7 +6,7 @@ The plugin requires local vector storage, ONNX inference, transport isolation, a
 
 ## Decision
 
-Implement the memory engine as a Go daemon with a narrow JSON-RPC transport boundary.
+Implement the memory engine as a Go vector service with a narrow gRPC transport boundary.
 
 ## Alternatives Considered
 

package/docs/architecture.md

@@ -10,9 +10,9 @@ LibraVDB Memory is split into two cooperating pieces:
 
 - a TypeScript OpenClaw plugin that owns the `memory` slot and registers
   context-engine capability at runtime
-- a Go sidecar daemon that owns storage, retrieval, and compaction
+- a Go vector service that owns storage, retrieval, and compaction
 
-The plugin keeps the host integration light and stable. The daemon keeps the
+The plugin keeps the host integration light and stable. The vector service keeps the
 data path local-first and handles the expensive memory operations outside the
 main chat process.
 
@@ -22,9 +22,9 @@ main chat process.
 flowchart LR
   Host["OpenClaw host"]
   Plugin["TypeScript plugin\nregistration + context engine"]
-  Runtime["Plugin runtime\nlazy daemon connect + RPC"]
+  Runtime["Plugin runtime\nlazy vector service connect + RPC"]
   MPS["memoryPromptSection\ncapability header"]
-  Sidecar["Go daemon"]
+  Sidecar["Go vector service"]
   Store["LibraVDB store"]
   Embed["Embedding engine"]
   Summarizer["Summarizer(s)"]
@@ -47,7 +47,7 @@ main retrieval path.
 
 ### `ingest`
 
-Session messages are written into the sidecar-backed store. User turns may also
+Session messages are written into the vector service-backed store. User turns may also
 be promoted into durable user memory after gating.
 
 ### `assemble`
@@ -72,13 +72,13 @@ thresholds, compaction declines instead of forcing a rewrite.
 - retrieval happens in `assemble`
 - compaction is separate from prompt construction
 - lifecycle hints such as `before_reset` and `session_end` are advisory
-- the sidecar is the source of truth for stored memory state
+- the vector service is the source of truth for stored memory state
 
 ## Failure Handling
 
 The plugin is designed to degrade gracefully:
 
-- if the daemon is unavailable, prompt assembly continues without recall
+- if the vector service is unavailable, prompt assembly continues without recall
 - if compaction fails, the active session is not blocked
 - if summarization is unavailable, the system falls back to the safer path
 
@@ -93,5 +93,5 @@ This architecture keeps the host integration simple while still supporting:
 - explicit compaction
 - local-first storage and retrieval
 
-In short, the plugin owns the lifecycle contract, and the sidecar owns the
+In short, the plugin owns the lifecycle contract, and the vector service owns the
 heavy lifting.

package/docs/configuration.md

@@ -34,45 +34,45 @@ 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). |
+| `"auto"` (default) | Standard operation — plugin heuristic matches vector service TLS setting automatically. |
+| `"tls"` | Daemon has TLS enabled on loopback or unix socket (rare; use when the vector service'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.
+**Default (local vector service):** No TLS configuration needed.
 Unix socket and loopback endpoints are always plaintext regardless
 of any TLS settings.
 
-**K8 / remote daemon with CA-issued cert:**
+**K8 / remote vector service 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:**
+**Remote vector service with self-signed or private CA cert:**
 Set `grpcEndpointTlsCa` to the path of the CA certificate PEM file:
 ```json
 {
-  "grpcEndpoint": "tcp:yourdaemon.internal:50051",
+  "grpcEndpoint": "tcp:yourvector service.internal:50051",
   "grpcEndpointTlsCa": "/etc/certs/ca.pem"
 }
 ```
-The daemon must be configured with matching TLS cert and key via
+The vector service must be configured with matching TLS cert and key via
 `LIBRAVDB_GRPC_TLS_CERT` and `LIBRAVDB_GRPC_TLS_KEY`.
 
-**Remote daemon with mTLS (mutual TLS):**
-When the daemon requires client certificate authentication, set both
+**Remote vector service with mTLS (mutual TLS):**
+When the vector service requires client certificate authentication, set both
 `grpcEndpointTlsClientCert` and `grpcEndpointTlsClientKey` (they must both
 be present or both be omitted):
 ```json
 {
-  "grpcEndpoint": "tcp:yourdaemon.internal:50051",
+  "grpcEndpoint": "tcp:yourvector service.internal:50051",
   "grpcEndpointTlsCa": "/etc/certs/ca.pem",
   "grpcEndpointTlsClientCert": "/etc/certs/client-cert.pem",
   "grpcEndpointTlsClientKey": "/etc/certs/client-key.pem"
 }
 ```
 
-**Local daemon with TLS enabled:**
-If the daemon has `LIBRAVDB_GRPC_TLS_CERT`/`LIBRAVDB_GRPC_TLS_KEY` set on a loopback
+**Local vector service with TLS enabled:**
+If the vector service has `LIBRAVDB_GRPC_TLS_CERT`/`LIBRAVDB_GRPC_TLS_KEY` set on a loopback
 address, explicitly set `grpcEndpointTlsMode: "tls"` to match:
 ```json
 {
@@ -87,9 +87,9 @@ 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) |
-| `embeddingRuntimePath` | string | — | Path to ONNX runtime library visible to the daemon (maps to `LIBRAVDB_ONNX_RUNTIME`; required with `embeddingBackend: "onnx-local"`) |
+| `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 |
 | `embeddingDimensions` | number | — | Embedding dimension override |