@xdarkicex/openclaw-memory-libravdb 1.4.6 → 1.4.7

package/HOOK.md

@@ -0,0 +1,14 @@
+---
+name: libravdb-memory
+description: Compatibility metadata for OpenClaw production installation.
+---
+
+# LibraVDB Memory Hook Metadata
+
+This package ships a native OpenClaw plugin with a compiled JavaScript runtime
+under `dist/`.
+
+`HOOK.md` is included so OpenClaw installation flows that validate hook-pack
+metadata do not reject the published package for missing compatibility files.
+It does not bootstrap the daemon or change the plugin's connect-only install
+model.

package/README.md

@@ -1,6 +1,6 @@
 # LibraVDB Memory for OpenClaw
 
-[![Go](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go&logoColor=white)](./sidecar/go.mod)
+[![Go](https://img.shields.io/badge/Go-1.25%2B-00ADD8?logo=go&logoColor=white)](https://github.com/xDarkicex/libravdbd)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](./package.json)
 [![OpenClaw](https://img.shields.io/badge/OpenClaw-memory%20plugin-111827)](./openclaw.plugin.json)
 
@@ -22,6 +22,9 @@ the daemon handles embeddings, retrieval, storage, and compaction.
 On newer OpenClaw builds, it also bridges the built-in `memory_search` runtime
 to the same libraVDB sidecar instead of leaving that tool inert.
 
+For local development, this repo can target a running daemon or a manual local
+daemon binary.
+
 ## Why This Exists
 
 The stock "single memory bucket" pattern is good for simple persistence, but it
@@ -65,7 +68,7 @@ These are the core differentiators the project is built around:
 The supported install flow is:
 
 ```bash
-brew tap xDarkicex/openclaw-libravdb-memory
+brew tap xDarkicex/homebrew-openclaw-libravdb-memory
 brew install libravdbd
 brew services start libravdbd
 openclaw plugins install @xdarkicex/openclaw-memory-libravdb
@@ -394,3 +397,30 @@ supported user path today is:
 
 That tradeoff is intentional. It keeps the plugin installation surface simple
 and auditable while preserving the full local memory engine at runtime.
+
+## Generated Contract Types
+
+TypeScript code in this plugin imports generated LibraVDB IPC types via the
+`@xdarkicex/libravdb-contracts` package:
+
+```typescript
+import { RpcRequest, RpcResponse } from "@xdarkicex/libravdb-contracts";
+```
+
+The generated types live in `libravdb-contracts/gen/ts/` and are produced by
+`buf generate` in that repository. A local `paths` alias in `tsconfig.json`
+wires the package name to that directory, so imports resolve without a
+`node_modules` install in the contracts repo.
+
+To regenerate after a proto change:
+
+```bash
+cd ../libravdb-contracts && buf generate
+# or from this repo:
+pnpm run generate:contracts
+```
+
+The alias is configured in both `tsconfig.json` (type-checking) and
+`tsconfig.build.json` (declaration emission). The generated `.ts` files use
+`@bufbuild/protobuf` at runtime, which must be available in the plugin's
+`node_modules`.

package/dist/cli.d.ts

@@ -0,0 +1,39 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+import type { PluginRuntime } from "./plugin-runtime.js";
+import type { LoggerLike, PluginConfig } from "./types.js";
+type CliOptionBag = {
+    dreamFile?: string;
+    userId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    limit?: string | number;
+    yes?: boolean;
+};
+type CliCommand = {
+    commands?: CliCommand[];
+    command(name: string): CliCommand;
+    description(text: string): CliCommand;
+    option(flags: string, description: string): CliCommand;
+    requiredOption?(flags: string, description: string): CliCommand;
+    action(handler: (opts?: CliOptionBag) => unknown): CliCommand;
+    name?(): string;
+};
+type CliProgram = CliCommand;
+export declare function registerMemoryCli(api: OpenClawPluginApi, runtime: PluginRuntime, cfg: PluginConfig, logger?: LoggerLike): void;
+type CliRegistrar = {
+    registerCli?(builder: (ctx: {
+        program: CliProgram;
+    }) => void, opts?: {
+        commands?: string[];
+        descriptors?: Array<{
+            name: string;
+            description: string;
+            hasSubcommands: boolean;
+        }>;
+    }): void;
+};
+declare module "openclaw/plugin-sdk/plugin-entry" {
+    interface OpenClawPluginApi extends CliRegistrar {
+    }
+}
+export {};

package/dist/cli.js

@@ -0,0 +1,208 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { resolveDurableNamespace } from "./durable-namespace.js";
+import { promoteDreamDiaryFile } from "./dream-promotion.js";
+export function registerMemoryCli(api, runtime, cfg, logger = console) {
+    if (!api.registerCli) {
+        return;
+    }
+    api.registerCli(({ program }) => {
+        const root = ensureCommand(program, "memory")
+            .description("Manage LibraVDB memory");
+        ensureCommand(root, "status")
+            .description("Show sidecar health, record counts, and active thresholds")
+            .action(() => void runStatus(runtime, cfg, logger));
+        const flush = ensureCommand(root, "flush")
+            .description("Wipe a durable memory namespace after confirmation");
+        if (flush.requiredOption) {
+            flush.requiredOption("--user-id <userId>", "User id whose durable memory should be deleted");
+        }
+        else {
+            flush.option("--user-id <userId>", "User id whose durable memory should be deleted");
+        }
+        flush.option("--session-key <sessionKey>", "Session key whose derived durable namespace should be deleted");
+        flush
+            .option("--yes", "Skip the confirmation prompt")
+            .action((opts) => void runFlush(runtime, opts, logger));
+        const exportCmd = ensureCommand(root, "export")
+            .description("Stream stored memories as newline-delimited JSON");
+        exportCmd.option("--user-id <userId>", "Restrict export to a single user namespace");
+        exportCmd.option("--session-key <sessionKey>", "Restrict export to a derived session-key namespace");
+        exportCmd.action((opts) => void runExport(runtime, opts, logger));
+        const journal = ensureCommand(root, "journal")
+            .description("Inspect internal lifecycle journal hints");
+        journal.option("--session-id <sessionId>", "Restrict journal entries to one session id");
+        journal.option("--limit <limit>", "Maximum journal entries to show");
+        journal.action((opts) => void runJournal(runtime, opts, logger));
+        const dreamPromote = ensureCommand(root, "dream-promote")
+            .description("Promote vetted dream diary entries into the dedicated dream collection");
+        if (dreamPromote.requiredOption) {
+            dreamPromote.requiredOption("--user-id <userId>", "User id whose dream collection should receive the promotion");
+            dreamPromote.requiredOption("--dream-file <path>", "Dream diary markdown file to promote from");
+        }
+        else {
+            dreamPromote.option("--user-id <userId>", "User id whose dream collection should receive the promotion");
+            dreamPromote.option("--dream-file <path>", "Dream diary markdown file to promote from");
+        }
+        dreamPromote.action((opts) => void runDreamPromote(runtime, opts, logger));
+    }, {
+        descriptors: [
+            {
+                name: "memory",
+                description: "Manage LibraVDB memory",
+                hasSubcommands: true,
+            },
+        ],
+    });
+}
+function ensureCommand(parent, name) {
+    const existing = parent.commands?.find((command) => {
+        if (typeof command.name === "function") {
+            return command.name() === name;
+        }
+        return false;
+    });
+    if (existing) {
+        return existing;
+    }
+    return parent.command(name);
+}
+async function runStatus(runtime, cfg, logger) {
+    try {
+        const rpc = await runtime.getRpc();
+        const status = await rpc.call("status", {});
+        console.table({
+            Sidecar: status.ok ? "running" : "down",
+            "Turns stored": status.turnCount ?? 0,
+            "Memories stored": status.memoryCount ?? 0,
+            "Lifecycle hints": status.lifecycleHintCount ?? 0,
+            "Gate threshold": status.gatingThreshold ?? cfg.ingestionGateThreshold ?? 0.35,
+            "Abstractive model": status.abstractiveReady ? "ready" : "not provisioned",
+            "Embedding profile": status.embeddingProfile ?? "unknown",
+            Message: status.message ?? (status.ok ? "ok" : "unavailable"),
+        });
+    }
+    catch (error) {
+        logger.error(`LibraVDB status unavailable: ${formatError(error)}`);
+        console.table({
+            Sidecar: "down",
+            "Turns stored": "n/a",
+            "Memories stored": "n/a",
+            "Lifecycle hints": "n/a",
+            "Gate threshold": cfg.ingestionGateThreshold ?? 0.35,
+            "Abstractive model": "unknown",
+            "Embedding profile": "unknown",
+            Message: formatError(error),
+        });
+        process.exitCode = 1;
+    }
+}
+async function runFlush(runtime, opts, logger) {
+    const namespace = resolveCliNamespace(opts);
+    if (!namespace) {
+        logger.error("LibraVDB flush requires --user-id <userId> or --session-key <sessionKey>.");
+        process.exitCode = 1;
+        return;
+    }
+    if (!opts?.yes) {
+        const confirmed = await confirm(`Delete durable memory namespace ${namespace}? [y/N] `);
+        if (!confirmed) {
+            console.log("Aborted.");
+            return;
+        }
+    }
+    try {
+        const rpc = await runtime.getRpc();
+        await rpc.call("flush_namespace", { namespace });
+        console.log(`Deleted durable memory namespace ${namespace}.`);
+    }
+    catch (error) {
+        logger.error(`LibraVDB flush failed: ${formatError(error)}`);
+        process.exitCode = 1;
+    }
+}
+async function runExport(runtime, opts, logger) {
+    try {
+        const rpc = await runtime.getRpc();
+        const result = await rpc.call("export_memory", {
+            namespace: resolveCliNamespace(opts),
+        });
+        for (const record of result.records ?? []) {
+            stdout.write(`${JSON.stringify(record)}\n`);
+        }
+    }
+    catch (error) {
+        logger.error(`LibraVDB export failed: ${formatError(error)}`);
+        process.exitCode = 1;
+    }
+}
+async function runJournal(runtime, opts, logger) {
+    try {
+        const rpc = await runtime.getRpc();
+        const result = await rpc.call("list_lifecycle_journal", {
+            sessionId: opts?.sessionId?.trim() || undefined,
+            limit: normalizeLimit(opts?.limit),
+        });
+        for (const record of result.results ?? []) {
+            stdout.write(`${JSON.stringify(record)}\n`);
+        }
+    }
+    catch (error) {
+        logger.error(`LibraVDB journal lookup failed: ${formatError(error)}`);
+        process.exitCode = 1;
+    }
+}
+async function runDreamPromote(runtime, opts, logger) {
+    const userId = opts?.userId?.trim();
+    const dreamFile = opts?.dreamFile?.trim();
+    if (!userId || !dreamFile) {
+        logger.error("LibraVDB dream-promote requires --user-id <userId> and --dream-file <path>.");
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const rpc = await runtime.getRpc();
+        const result = await promoteDreamDiaryFile(rpc, { userId, diaryPath: dreamFile });
+        console.log(`Promoted ${result.promoted ?? 0} dream entr${(result.promoted ?? 0) === 1 ? "y" : "ies"}; rejected ${result.rejected ?? 0}.`);
+    }
+    catch (error) {
+        logger.error(`LibraVDB dream promotion failed: ${formatError(error)}`);
+        process.exitCode = 1;
+    }
+}
+async function confirm(prompt) {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        const answer = await rl.question(prompt);
+        return answer.trim().toLowerCase() === "y";
+    }
+    finally {
+        rl.close();
+    }
+}
+function formatError(error) {
+    if (error instanceof Error && error.message.trim()) {
+        return error.message;
+    }
+    return String(error);
+}
+function normalizeLimit(limit) {
+    if (typeof limit === "number" && Number.isFinite(limit) && limit > 0) {
+        return Math.floor(limit);
+    }
+    if (typeof limit === "string") {
+        const parsed = Number.parseInt(limit, 10);
+        if (Number.isFinite(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function resolveCliNamespace(opts) {
+    const userId = opts?.userId?.trim();
+    const sessionKey = opts?.sessionKey?.trim();
+    if (!userId && !sessionKey) {
+        return undefined;
+    }
+    return resolveDurableNamespace({ userId, sessionKey });
+}

package/dist/context-engine.d.ts

@@ -0,0 +1,56 @@
+import type { PluginRuntime } from "./plugin-runtime.js";
+import type { LoggerLike, PluginConfig, RecallCache, SearchResult } from "./types.js";
+import { AssembleContextInternalResponse } from "@xdarkicex/libravdb-contracts";
+export declare function buildContextEngineFactory(runtime: PluginRuntime, cfg: PluginConfig, recallCache: RecallCache<SearchResult>, logger?: LoggerLike): {
+    info: {
+        id: string;
+        name: string;
+        ownsCompaction: boolean;
+    };
+    ownsCompaction: boolean;
+    bootstrap(args: {
+        sessionId: string;
+        sessionKey?: string;
+        userId?: string;
+    }): Promise<any>;
+    ingest(args: {
+        sessionId: string;
+        sessionKey?: string;
+        userId?: string;
+        message: {
+            role: string;
+            content: string;
+            id?: string;
+        };
+        isHeartbeat?: boolean;
+    }): Promise<any>;
+    assemble(args: {
+        sessionId: string;
+        sessionKey?: string;
+        userId?: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            id?: string;
+        }>;
+        tokenBudget: number;
+        prompt?: string;
+    }): Promise<AssembleContextInternalResponse>;
+    compact(args: {
+        sessionId: string;
+        force?: boolean;
+        targetSize?: number;
+    }): Promise<any>;
+    afterTurn(args: {
+        sessionId: string;
+        sessionKey?: string;
+        userId?: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            id?: string;
+        }>;
+        prePromptMessageCount?: number;
+        isHeartbeat?: boolean;
+    }): Promise<any>;
+};

package/dist/context-engine.js

@@ -0,0 +1,125 @@
+export function buildContextEngineFactory(runtime, cfg, recallCache, logger = console) {
+    return {
+        info: { id: "libravdb-memory", name: "LibraVDB Memory", ownsCompaction: true },
+        ownsCompaction: true,
+        async bootstrap(args) {
+            const kernel = runtime.getKernel();
+            if (kernel) {
+                try {
+                    await kernel.initializeSession({
+                        clientId: "openclaw-ts-wrapper",
+                        clientCapabilities: [{ name: "grpc", version: "1.0" }]
+                    });
+                }
+                catch (error) {
+                    // Proceed even if initialize session fails or doesn't return nonce if secret optional
+                }
+                return await kernel.bootstrapSession({
+                    sessionId: args.sessionId,
+                    sessionKey: args.sessionKey,
+                    userId: args.userId,
+                });
+            }
+            const rpc = await runtime.getRpc();
+            return await rpc.call("bootstrap_session_kernel", args);
+        },
+        async ingest(args) {
+            const kernel = runtime.getKernel();
+            if (kernel) {
+                return await kernel.ingestMessage({
+                    sessionId: args.sessionId,
+                    sessionKey: args.sessionKey,
+                    userId: args.userId,
+                    message: args.message,
+                    isHeartbeat: args.isHeartbeat,
+                });
+            }
+            const rpc = await runtime.getRpc();
+            return await rpc.call("ingest_message_kernel", args);
+        },
+        async assemble(args) {
+            const kernel = runtime.getKernel();
+            if (kernel) {
+                return await kernel.assembleContext({
+                    sessionId: args.sessionId,
+                    sessionKey: args.sessionKey,
+                    userId: args.userId,
+                    queryText: args.prompt ?? "",
+                    visibleMessages: args.messages,
+                    tokenBudget: args.tokenBudget,
+                    config: {},
+                    emitDebug: true
+                });
+            }
+            const rpc = await runtime.getRpc();
+            const resp = await rpc.call("assemble_context_internal", {
+                sessionId: args.sessionId,
+                sessionKey: args.sessionKey,
+                userId: args.userId,
+                messages: args.messages,
+                tokenBudget: args.tokenBudget,
+                prompt: args.prompt,
+                emitDebug: true,
+                config: {
+                    useSessionRecallProjection: cfg.useSessionRecallProjection,
+                    useSessionSummarySearchExperiment: cfg.useSessionSummarySearchExperiment,
+                    tokenBudgetFraction: cfg.tokenBudgetFraction,
+                    authoredHardBudgetFraction: cfg.authoredHardBudgetFraction,
+                    authoredSoftBudgetFraction: cfg.authoredSoftBudgetFraction,
+                    elevatedGuidanceBudgetFraction: cfg.elevatedGuidanceBudgetFraction,
+                    topK: cfg.topK,
+                    continuityMinTurns: cfg.continuityMinTurns,
+                    continuityTailBudgetTokens: cfg.continuityTailBudgetTokens,
+                    continuityPriorContextTokens: cfg.continuityPriorContextTokens,
+                    compactThreshold: cfg.compactThreshold,
+                    compactSessionTokenBudget: cfg.compactSessionTokenBudget,
+                    section7Theta1: cfg.section7Theta1,
+                    section7Kappa: cfg.section7Kappa,
+                    section7HopEta: cfg.section7HopEta,
+                    section7HopThreshold: cfg.section7HopThreshold,
+                    section7CoarseTopK: cfg.section7CoarseTopK,
+                    section7SecondPassTopK: cfg.section7SecondPassTopK,
+                    section7AuthorityRecencyLambda: cfg.section7AuthorityRecencyLambda,
+                    section7AuthorityRecencyWeight: cfg.section7AuthorityRecencyWeight,
+                    section7AuthorityFrequencyWeight: cfg.section7AuthorityFrequencyWeight,
+                    section7AuthorityAuthoredWeight: cfg.section7AuthorityAuthoredWeight,
+                    recoveryFloorScore: cfg.recoveryFloorScore,
+                    recoveryMinTopK: cfg.recoveryMinTopK,
+                    recoveryMinConfidenceMean: cfg.recoveryMinConfidenceMean,
+                    recencyLambdaSession: cfg.recencyLambdaSession,
+                    recencyLambdaUser: cfg.recencyLambdaUser,
+                    recencyLambdaGlobal: cfg.recencyLambdaGlobal,
+                    ingestionGateThreshold: cfg.ingestionGateThreshold,
+                },
+            });
+            return resp;
+        },
+        async compact(args) {
+            const kernel = runtime.getKernel();
+            if (kernel) {
+                return await kernel.compactSession({
+                    sessionId: args.sessionId,
+                    force: args.force,
+                    targetSize: args.targetSize,
+                });
+            }
+            const rpc = await runtime.getRpc();
+            return await rpc.call("compact_session", args);
+        },
+        async afterTurn(args) {
+            const kernel = runtime.getKernel();
+            if (kernel) {
+                return await kernel.afterTurn({
+                    sessionId: args.sessionId,
+                    sessionKey: args.sessionKey,
+                    userId: args.userId,
+                    messages: args.messages,
+                    prePromptMessageCount: args.prePromptMessageCount,
+                    isHeartbeat: args.isHeartbeat,
+                });
+            }
+            const rpc = await runtime.getRpc();
+            return await rpc.call("after_turn_kernel", args);
+        }
+    };
+}

package/dist/dream-promotion.d.ts

@@ -0,0 +1,47 @@
+import type { LoggerLike, PluginConfig } from "./types.js";
+type Disposable = {
+    close(): void;
+};
+interface RpcLike {
+    call<T>(method: string, params: unknown): Promise<T>;
+}
+type RpcGetterLike = () => Promise<RpcLike>;
+interface FsWatcherLike extends Disposable {
+    on(event: "error", handler: (error: Error) => void): void;
+}
+interface FsApi {
+    readFile(file: string): Promise<Uint8Array>;
+    stat(file: string): Promise<{
+        size: number;
+        mtimeMs: number;
+    }>;
+    watch(dir: string, onChange: (event: string, filename: string | Buffer | null) => void): FsWatcherLike;
+}
+export interface DreamPromotionHandle {
+    start(): Promise<void>;
+    refresh(): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface DreamPromotionCandidate {
+    text: string;
+    score: number;
+    recallCount: number;
+    uniqueQueries: number;
+    section: string;
+    line: number;
+}
+interface DreamPromotionResult {
+    promoted?: number;
+    rejected?: number;
+}
+export declare function createDreamPromotionHandle(cfg: PluginConfig, getRpc: RpcGetterLike, logger?: LoggerLike, fsApi?: FsApi): DreamPromotionHandle;
+export declare function promoteDreamDiaryFile(rpc: RpcLike, opts: {
+    userId: string;
+    diaryPath: string;
+    text?: string;
+    fileHash?: string;
+    sourceSize?: number;
+    sourceMtimeMs?: number;
+}): Promise<DreamPromotionResult>;
+export declare function parseDreamPromotionCandidates(text: string): DreamPromotionCandidate[];
+export {};