@xdarkicex/openclaw-memory-libravdb 1.4.6 → 1.4.8

package/dist/memory-runtime.d.ts

@@ -0,0 +1,118 @@
+import type { RpcGetter } from "./plugin-runtime.js";
+import type { PluginConfig } from "./types.js";
+type MemorySearchParams = {
+    query?: string;
+    text?: string;
+    input?: string;
+    q?: string;
+    k?: number;
+    limit?: number;
+    topK?: number;
+    userId?: string;
+    agentId?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    context?: {
+        userId?: string;
+        agentId?: string;
+        sessionId?: string;
+        sessionKey?: string;
+    };
+};
+type MemoryRuntimeStatus = {
+    ok?: boolean;
+    message?: string;
+    turnCount?: number;
+    memoryCount?: number;
+    gatingThreshold?: number;
+    abstractiveReady?: boolean;
+    embeddingProfile?: string;
+};
+export declare function buildMemoryRuntimeBridge(getRpc: RpcGetter, cfg: PluginConfig): {
+    getMemorySearchManager(params?: {
+        agentId?: string;
+        purpose?: string;
+    }): Promise<{
+        manager: {
+            search(queryOrParams?: string | MemorySearchParams, opts?: MemorySearchParams): Promise<{
+                path: string;
+                startLine: number;
+                endLine: number;
+                score: number;
+                snippet: string;
+                source: string;
+                citation: string;
+            }[] | {
+                results: never[];
+                error: string;
+            } | {
+                results: {
+                    content: string;
+                    id: string;
+                    score: number;
+                    text: string;
+                    metadata: {
+                        ts?: number;
+                        sessionId?: string;
+                        userId?: string;
+                        role?: string;
+                        source_doc?: string;
+                        node_kind?: string;
+                        ordinal?: number;
+                        position?: number;
+                        tier?: number;
+                        authored?: boolean;
+                        authority?: number;
+                        access_count?: number;
+                        collection?: string;
+                        hop_targets?: string[] | string;
+                        token_estimate?: number;
+                        continuity_tail?: boolean;
+                        continuity_base?: boolean;
+                        continuity_bundle_id?: string;
+                        elevated_guidance?: boolean;
+                        source_turn_id?: string;
+                        source_turn_ts?: number;
+                        provenance_class?: string;
+                        stability_weight?: number;
+                        expanded_from_summary?: boolean;
+                        parent_summary_id?: string;
+                        expansion_depth?: number;
+                        cascade_tier?: number;
+                        [key: string]: unknown;
+                    };
+                    finalScore?: number;
+                }[];
+                error?: undefined;
+            }>;
+            readFile(params: {
+                relPath: string;
+                from?: number;
+                lines?: number;
+            }): Promise<{
+                text: string;
+                path: string;
+            }>;
+            ingest(): Promise<{
+                ingested: boolean;
+                delegatedToContextEngine: boolean;
+            }>;
+            sync(): Promise<{
+                synced: boolean;
+                delegatedToContextEngine: boolean;
+            }>;
+            status(): MemoryRuntimeStatus & Record<string, unknown>;
+            probeEmbeddingAvailability(): Promise<{
+                error?: string | undefined;
+                ok: boolean;
+            }>;
+            probeVectorAvailability(): Promise<boolean>;
+            close(): Promise<void>;
+        };
+    }>;
+    resolveMemoryBackendConfig(): {
+        backend: string;
+    };
+    closeAllMemorySearchManagers(): Promise<void>;
+};
+export {};

package/dist/memory-runtime.js

@@ -0,0 +1,217 @@
+import { resolveDurableNamespace } from "./durable-namespace.js";
+import { detectDreamQuerySignal, resolveDreamCollection } from "./dream-routing.js";
+export function buildMemoryRuntimeBridge(getRpc, cfg) {
+    return {
+        async getMemorySearchManager(params = {}) {
+            const status = await readStatus(getRpc, params.purpose);
+            return {
+                manager: createMemorySearchManager(getRpc, cfg, params, status),
+            };
+        },
+        resolveMemoryBackendConfig() {
+            // We keep retrieval inside the plugin-side sidecar rather than delegating to
+            // OpenClaw's external QMD path.
+            return { backend: "builtin" };
+        },
+        async closeAllMemorySearchManagers() {
+            // Context-engine lifecycle cleanup still happens through gateway_stop.
+        },
+    };
+}
+function createMemorySearchManager(getRpc, cfg, defaults, initialStatus) {
+    let cachedStatus = initialStatus;
+    return {
+        async search(queryOrParams = {}, opts = {}) {
+            const legacyCall = typeof queryOrParams === "string";
+            const params = legacyCall
+                ? {
+                    query: queryOrParams,
+                    limit: opts.limit ?? opts.k ?? opts.topK,
+                    sessionId: opts.sessionId,
+                    sessionKey: opts.sessionKey,
+                    userId: opts.userId,
+                    agentId: opts.agentId,
+                    context: opts.context,
+                }
+                : queryOrParams;
+            const queryText = firstString(params.query, params.text, params.input, params.q);
+            if (!queryText) {
+                return legacyCall ? { results: [], error: "Missing query text for LibraVDB memory search" } : [];
+            }
+            const dreamQuery = detectDreamQuerySignal(queryText);
+            const sessionId = firstString(params.sessionId, params.context?.sessionId);
+            const userId = resolveDurableNamespace({
+                userId: firstString(params.userId, params.context?.userId),
+                sessionKey: firstString(params.sessionKey, params.context?.sessionKey),
+                agentId: firstString(params.agentId, params.context?.agentId, defaults.agentId),
+                fallback: sessionId ? `session:${sessionId}` : undefined,
+            });
+            const k = normalizePositiveInteger(params.k, params.limit, params.topK, cfg.topK, 8);
+            const rpc = await getRpc();
+            const result = dreamQuery.active
+                ? await rpc.call("search_text", {
+                    collection: resolveDreamCollection(userId),
+                    text: queryText,
+                    k,
+                })
+                : await searchResolvedCollections(rpc, cfg, userId, sessionId, queryText, k);
+            const legacyResults = result.results.map((item) => ({
+                ...item,
+                content: item.text,
+            }));
+            if (legacyCall) {
+                return { results: legacyResults };
+            }
+            return result.results.map(toMemorySearchResult);
+        },
+        async readFile(params) {
+            const located = await loadSearchResultText(getRpc, params.relPath);
+            const fromLine = Math.max(1, params.from ?? 1);
+            const lineCount = Math.max(1, params.lines ?? 200);
+            const lines = located.text.split("\n");
+            const text = lines.slice(fromLine - 1, fromLine - 1 + lineCount).join("\n");
+            return {
+                text,
+                path: located.path,
+            };
+        },
+        async ingest() {
+            // The plugin already owns per-turn ingest through the context engine.
+            return { ingested: false, delegatedToContextEngine: true };
+        },
+        async sync() {
+            cachedStatus = await readStatus(getRpc, defaults.purpose);
+            return { synced: true, delegatedToContextEngine: true };
+        },
+        status() {
+            return cachedStatus;
+        },
+        async probeEmbeddingAvailability() {
+            return {
+                ok: cachedStatus.ok ?? false,
+                ...(cachedStatus.ok === false && typeof cachedStatus.message === "string"
+                    ? { error: cachedStatus.message }
+                    : {}),
+            };
+        },
+        async probeVectorAvailability() {
+            return cachedStatus.ok ?? false;
+        },
+        async close() {
+            // The sidecar connection is shared by the plugin runtime.
+        },
+    };
+}
+async function searchResolvedCollections(rpc, cfg, userId, sessionId, queryText, k) {
+    const collections = resolveSearchCollections(cfg, userId, sessionId);
+    return collections.length === 1
+        ? await rpc.call("search_text", {
+            collection: collections[0],
+            text: queryText,
+            k,
+        })
+        : await rpc.call("search_text_collections", {
+            collections,
+            text: queryText,
+            k,
+            excludeByCollection: {},
+        });
+}
+function resolveSearchCollections(cfg, userId, sessionId) {
+    const collections = [`user:${userId}`, "global"];
+    if (!sessionId) {
+        return collections;
+    }
+    if (cfg.useSessionSummarySearchExperiment) {
+        collections.unshift(`session_summary:${sessionId}`);
+        return collections;
+    }
+    if (cfg.useSessionRecallProjection) {
+        collections.unshift(`session_recall:${sessionId}`);
+        return collections;
+    }
+    collections.unshift(`session:${sessionId}`);
+    return collections;
+}
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.length > 0);
+}
+function toMemorySearchResult(item) {
+    const collection = typeof item.metadata.collection === "string" ? item.metadata.collection : "memory";
+    return {
+        path: encodeSearchResultPath(collection, item.id),
+        startLine: 1,
+        endLine: Math.max(1, item.text.split("\n").length),
+        score: item.score,
+        snippet: item.text,
+        source: collection.startsWith("session:") || collection.startsWith("session_") ? "sessions" : "memory",
+        citation: `${collection}:${item.id}`,
+    };
+}
+async function loadSearchResultText(getRpc, relPath) {
+    const { collection, id } = decodeSearchResultPath(relPath);
+    const rpc = await getRpc();
+    const result = await rpc.call("list_collection", { collection });
+    const item = result.results.find((entry) => entry.id === id);
+    if (!item) {
+        throw new Error(`LibraVDB memory path not found: ${relPath}`);
+    }
+    return {
+        path: relPath,
+        text: item.text,
+    };
+}
+function encodeSearchResultPath(collection, id) {
+    return `${encodeURIComponent(collection)}::${encodeURIComponent(id)}`;
+}
+function decodeSearchResultPath(relPath) {
+    const separator = relPath.indexOf("::");
+    if (separator <= 0) {
+        throw new Error(`Unsupported LibraVDB memory path: ${relPath}`);
+    }
+    return {
+        collection: decodeURIComponent(relPath.slice(0, separator)),
+        id: decodeURIComponent(relPath.slice(separator + 2)),
+    };
+}
+async function readStatus(getRpc, purpose) {
+    try {
+        const rpc = await getRpc();
+        const status = await rpc.call("status", {});
+        return {
+            ...status,
+            backend: "builtin",
+            provider: "libravdb",
+            model: status.embeddingProfile ?? "unknown",
+            ok: status.ok ?? false,
+            message: status.message ?? "ok",
+            turnCount: status.turnCount ?? 0,
+            memoryCount: status.memoryCount ?? 0,
+            gatingThreshold: status.gatingThreshold,
+            abstractiveReady: status.abstractiveReady ?? false,
+            embeddingProfile: status.embeddingProfile ?? "unknown",
+            purpose,
+        };
+    }
+    catch (error) {
+        return {
+            backend: "builtin",
+            provider: "libravdb",
+            model: "unknown",
+            ok: false,
+            message: error instanceof Error && error.message ? error.message : String(error),
+            turnCount: 0,
+            memoryCount: 0,
+            embeddingProfile: "unknown",
+            purpose,
+        };
+    }
+}
+function normalizePositiveInteger(...values) {
+    for (const value of values) {
+        if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+            return Math.max(1, Math.floor(value));
+        }
+    }
+    return 8;
+}

package/dist/plugin-runtime.d.ts

@@ -0,0 +1,28 @@
+import { RpcClient } from "./rpc.js";
+import { GrpcKernelClient } from "./grpc-client.js";
+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 interface LifecycleHint {
+    hook: "before_reset" | "session_end";
+    reason?: string;
+    sessionFile?: string;
+    sessionId?: string;
+    sessionKey?: string;
+    agentId?: string;
+    workspaceDir?: string;
+    messageCount?: number;
+    durationMs?: number;
+    transcriptArchived?: boolean;
+    nextSessionId?: string;
+    nextSessionKey?: string;
+}
+export interface PluginRuntime {
+    getRpc: RpcGetter;
+    getKernel(): GrpcKernelClient | null;
+    emitLifecycleHint(hint: LifecycleHint): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export declare function createPluginRuntime(cfg: PluginConfig, logger?: LoggerLike): PluginRuntime;
+export declare function enrichStartupError(error: unknown, healthMessage?: string): Error;

package/dist/plugin-runtime.js

@@ -0,0 +1,127 @@
+import { RpcClient } from "./rpc.js";
+import { GrpcKernelClient } from "./grpc-client.js";
+import { daemonProvisioningHint, startSidecar } from "./sidecar.js";
+import { readFileSync } from "node:fs";
+export const DEFAULT_RPC_TIMEOUT_MS = 30000;
+export const STARTUP_HEALTH_TIMEOUT_MS = 2000;
+export function createPluginRuntime(cfg, logger = console) {
+    let started = null;
+    let stopped = false;
+    let resolvedKernel = null;
+    const ensureStarted = async () => {
+        if (stopped) {
+            throw new Error("LibraVDB plugin runtime has been shut down");
+        }
+        if (!started) {
+            started = (async () => {
+                const sidecar = await startSidecar(cfg, logger);
+                const rpc = new RpcClient(sidecar.socket, {
+                    timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+                });
+                const health = await rpc.call("health", {}, {
+                    timeoutMs: STARTUP_HEALTH_TIMEOUT_MS,
+                });
+                if (!health.ok) {
+                    try {
+                        await sidecar.shutdown();
+                    }
+                    catch {
+                        // Ignore cleanup failure on startup rejection.
+                    }
+                    throw enrichStartupError("LibraVDB daemon failed health check", health.message);
+                }
+                let kernel = null;
+                if (cfg.grpcEndpoint) {
+                    try {
+                        const secret = loadSecretFromEnv();
+                        kernel = new GrpcKernelClient({
+                            endpoint: cfg.grpcEndpoint,
+                            secret,
+                            timeoutMs: cfg.rpcTimeoutMs ?? DEFAULT_RPC_TIMEOUT_MS,
+                        });
+                    }
+                    catch (error) {
+                        logger.warn?.(`LibraVDB: failed to initialize gRPC kernel client: ${formatError(error)}`);
+                    }
+                }
+                resolvedKernel = kernel;
+                return { rpc, sidecar, kernel };
+            })().catch((error) => {
+                started = null;
+                throw enrichStartupError(error);
+            });
+        }
+        return await started;
+    };
+    return {
+        async getRpc() {
+            return (await ensureStarted()).rpc;
+        },
+        getKernel() {
+            if (!started)
+                return null;
+            return resolvedKernel;
+        },
+        async emitLifecycleHint(hint) {
+            try {
+                const active = await ensureStarted();
+                await active.rpc.call("session_lifecycle_hint", hint);
+            }
+            catch (error) {
+                logger.warn?.(`LibraVDB lifecycle hint dropped: ${formatError(error)}`);
+            }
+        },
+        async shutdown() {
+            stopped = true;
+            if (!started) {
+                return;
+            }
+            const active = started;
+            started = null;
+            const { rpc, sidecar, kernel } = await active;
+            try {
+                if (kernel)
+                    kernel.close();
+                await rpc.call("flush", {});
+            }
+            finally {
+                await sidecar.shutdown();
+            }
+        },
+    };
+}
+function loadSecretFromEnv() {
+    const secret = process.env.LIBRAVDB_AUTH_SECRET;
+    if (secret)
+        return secret;
+    const path = process.env.LIBRAVDB_AUTH_SECRET_FILE;
+    if (path) {
+        try {
+            return readFileSync(path, "utf8").trim();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function formatError(error) {
+    if (error instanceof Error && error.message.trim()) {
+        return error.message;
+    }
+    return String(error);
+}
+export function enrichStartupError(error, healthMessage) {
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const message = rawMessage.trim() || "LibraVDB daemon startup failed";
+    if (message.includes("install and start libravdbd separately") || message.includes("package does not provision the daemon binary")) {
+        return error instanceof Error ? error : new Error(message);
+    }
+    const shouldHint = /health check|daemon unavailable|connection refused|ECONNREFUSED|ENOENT|fallback mode|ONNX Runtime|embedder/i.test(`${message} ${healthMessage ?? ""}`);
+    if (!shouldHint) {
+        return error instanceof Error ? error : new Error(message);
+    }
+    const detail = healthMessage?.trim();
+    const prefix = detail && !message.includes(detail) ? `${message}: ${detail}` : message;
+    return new Error(`${prefix}. ${daemonProvisioningHint()}`);
+}