@xdarkicex/openclaw-memory-libravdb 1.4.17 → 1.4.19

package/README.md

@@ -118,6 +118,8 @@ Before exposing OpenClaw over remote channels, read [Security](./docs/security.m
 
 ```bash
 openclaw memory status
+openclaw memory index --force
+openclaw memory search "prior context"
 openclaw memory export --user-id <userId>
 openclaw memory flush --user-id <userId>
 openclaw memory journal --limit 50

package/cli-metadata.js

@@ -0,0 +1 @@
+export { default } from "./dist/cli-metadata.js";

package/dist/cli-descriptors.d.ts

@@ -0,0 +1,9 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+export declare const PLUGIN_ID = "libravdb-memory";
+export declare const MEMORY_CLI_DESCRIPTOR: {
+    readonly name: "memory";
+    readonly description: "Manage LibraVDB memory";
+    readonly hasSubcommands: true;
+};
+export declare function isMemorySlotSelected(api: Pick<OpenClawPluginApi, "config">): boolean;
+export declare function registerMemoryCliMetadata(api: Pick<OpenClawPluginApi, "config" | "registerCli">): void;

package/dist/cli-descriptors.js

@@ -0,0 +1,18 @@
+export const PLUGIN_ID = "libravdb-memory";
+export const MEMORY_CLI_DESCRIPTOR = {
+    name: "memory",
+    description: "Manage LibraVDB memory",
+    hasSubcommands: true,
+};
+export function isMemorySlotSelected(api) {
+    const slots = api.config?.plugins?.slots;
+    return slots?.memory === PLUGIN_ID;
+}
+export function registerMemoryCliMetadata(api) {
+    if (!isMemorySlotSelected(api)) {
+        return;
+    }
+    api.registerCli?.(() => { }, {
+        descriptors: [MEMORY_CLI_DESCRIPTOR],
+    });
+}

package/dist/cli-metadata.d.ts

@@ -0,0 +1,9 @@
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    kind?: "memory" | "context-engine" | Array<"memory" | "context-engine">;
+    configSchema?: unknown;
+    register(api: import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginApi): void | Promise<void>;
+};
+export default _default;

package/dist/cli-metadata.js

@@ -0,0 +1,11 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { PLUGIN_ID, registerMemoryCliMetadata } from "./cli-descriptors.js";
+export default definePluginEntry({
+    id: PLUGIN_ID,
+    name: "LibraVDB Memory",
+    description: "Persistent vector memory with three-tier hybrid scoring",
+    kind: ["memory", "context-engine"],
+    register(api) {
+        registerMemoryCliMetadata(api);
+    },
+});

package/dist/cli.d.ts

@@ -1,21 +1,14 @@
 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;
+    argument?(name: string, description: string): CliCommand;
     option(flags: string, description: string): CliCommand;
     requiredOption?(flags: string, description: string): CliCommand;
-    action(handler: (opts?: CliOptionBag) => unknown): CliCommand;
+    action(handler: (...args: unknown[]) => unknown): CliCommand;
     name?(): string;
 };
 type CliProgram = CliCommand;

package/dist/cli.js

@@ -1,19 +1,26 @@
 import { createInterface } from "node:readline/promises";
 import { stdin, stdout } from "node:process";
+import { MEMORY_CLI_DESCRIPTOR, isMemorySlotSelected } from "./cli-descriptors.js";
 import { resolveDurableNamespace } from "./durable-namespace.js";
 import { promoteDreamDiaryFile } from "./dream-promotion.js";
+import { buildMemoryRuntimeBridge } from "./memory-runtime.js";
 export function registerMemoryCli(api, runtime, cfg, logger = console) {
     if (!api.registerCli) {
         return;
     }
+    if (!isMemorySlotSelected(api)) {
+        return;
+    }
     const isFullMode = runtime !== null;
     api.registerCli(({ program }) => {
         const root = ensureCommand(program, "memory")
             .description("Manage LibraVDB memory");
         if (!isFullMode) {
-            // cli-metadata mode: register structure only so `openclaw memory --help` works.
+            // Non-full modes register structure only so `openclaw memory --help` works.
             // No runtime available — do not attach action handlers.
             ensureCommand(root, "status").description("Show sidecar health, record counts, and active thresholds");
+            ensureCommand(root, "index").description("Refresh delegated LibraVDB memory index state");
+            ensureCommand(root, "search").description("Search LibraVDB memory");
             ensureCommand(root, "flush").description("Wipe a durable memory namespace after confirmation");
             ensureCommand(root, "export").description("Stream stored memories as newline-delimited JSON");
             ensureCommand(root, "journal").description("Inspect internal lifecycle journal hints");
@@ -22,7 +29,40 @@ export function registerMemoryCli(api, runtime, cfg, logger = console) {
         }
         ensureCommand(root, "status")
             .description("Show sidecar health, record counts, and active thresholds")
-            .action(() => void runStatus(runtime, cfg, logger));
+            .option("--agent <id>", "Agent id")
+            .option("--json", "Print JSON")
+            .option("--deep", "Probe daemon readiness")
+            .option("--index", "Refresh delegated index state before printing status")
+            .option("--fix", "Accepted for OpenClaw memory CLI compatibility")
+            .option("--verbose", "Verbose logging")
+            .action(async (opts) => {
+            await runCliCommand(runtime, logger, async () => {
+                await runStatus(runtime, cfg, logger, normalizeOptionBag(opts));
+            });
+        });
+        ensureCommand(root, "index")
+            .description("Refresh delegated LibraVDB memory index state")
+            .option("--agent <id>", "Agent id")
+            .option("--force", "Force refresh where supported")
+            .option("--verbose", "Verbose logging")
+            .action(async (opts) => {
+            await runCliCommand(runtime, logger, async () => {
+                await runIndex(runtime, cfg, normalizeOptionBag(opts), logger);
+            });
+        });
+        const search = ensureCommand(root, "search")
+            .description("Search LibraVDB memory")
+            .option("--query <text>", "Search query (alternative to positional argument)")
+            .option("--agent <id>", "Agent id")
+            .option("--max-results <n>", "Max results")
+            .option("--min-score <n>", "Minimum score")
+            .option("--json", "Print JSON");
+        search.argument?.("[query]", "Search query");
+        search.action(async (queryOrOpts, maybeOpts) => {
+            await runCliCommand(runtime, logger, async () => {
+                await runSearch(runtime, cfg, normalizeQueryArg(queryOrOpts), normalizeActionOptions(queryOrOpts, maybeOpts), logger);
+            });
+        });
         const flush = ensureCommand(root, "flush")
             .description("Wipe a durable memory namespace after confirmation");
         if (flush.requiredOption) {
@@ -34,17 +74,29 @@ export function registerMemoryCli(api, runtime, cfg, logger = console) {
         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));
+            .action(async (opts) => {
+            await runCliCommand(runtime, logger, async () => {
+                await runFlush(runtime, normalizeOptionBag(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));
+        exportCmd.action(async (opts) => {
+            await runCliCommand(runtime, logger, async () => {
+                await runExport(runtime, normalizeOptionBag(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));
+        journal.action(async (opts) => {
+            await runCliCommand(runtime, logger, async () => {
+                await runJournal(runtime, normalizeOptionBag(opts), logger);
+            });
+        });
         const dreamPromote = ensureCommand(root, "dream-promote")
             .description("Promote vetted dream diary entries into the dedicated dream collection");
         if (dreamPromote.requiredOption) {
@@ -55,15 +107,13 @@ export function registerMemoryCli(api, runtime, cfg, logger = console) {
             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));
+        dreamPromote.action(async (opts) => {
+            await runCliCommand(runtime, logger, async () => {
+                await runDreamPromote(runtime, normalizeOptionBag(opts), logger);
+            });
+        });
     }, {
-        descriptors: [
-            {
-                name: "memory",
-                description: "Manage LibraVDB memory",
-                hasSubcommands: true,
-            },
-        ],
+        descriptors: [MEMORY_CLI_DESCRIPTOR],
     });
 }
 function ensureCommand(parent, name) {
@@ -78,10 +128,30 @@ function ensureCommand(parent, name) {
     }
     return parent.command(name);
 }
-async function runStatus(runtime, cfg, logger) {
+async function runCliCommand(runtime, logger, action) {
+    try {
+        await action();
+    }
+    finally {
+        try {
+            await runtime.shutdown();
+        }
+        catch (error) {
+            logger.warn?.(`LibraVDB CLI shutdown failed: ${formatError(error)}`);
+        }
+    }
+}
+async function runStatus(runtime, cfg, logger, opts = {}) {
+    if (opts.index) {
+        await runIndex(runtime, cfg, { ...opts, verbose: false }, logger, { quiet: true });
+    }
     try {
         const rpc = await runtime.getRpc();
         const status = await rpc.call("status", {});
+        if (opts.json) {
+            console.log(JSON.stringify({ status }, null, 2));
+            return;
+        }
         console.table({
             Sidecar: status.ok ? "running" : "down",
             "Turns stored": status.turnCount ?? 0,
@@ -95,6 +165,17 @@ async function runStatus(runtime, cfg, logger) {
     }
     catch (error) {
         logger.error(`LibraVDB status unavailable: ${formatError(error)}`);
+        if (opts.json) {
+            console.log(JSON.stringify({
+                status: {
+                    ok: false,
+                    message: formatError(error),
+                    gatingThreshold: cfg.ingestionGateThreshold ?? 0.35,
+                },
+            }, null, 2));
+            process.exitCode = 1;
+            return;
+        }
         console.table({
             Sidecar: "down",
             "Turns stored": "n/a",
@@ -108,6 +189,79 @@ async function runStatus(runtime, cfg, logger) {
         process.exitCode = 1;
     }
 }
+async function runIndex(runtime, cfg, opts, logger, params = {}) {
+    try {
+        const bridge = buildMemoryRuntimeBridge(runtime.getRpc, cfg);
+        const { manager } = await bridge.getMemorySearchManager({
+            agentId: opts?.agent,
+            purpose: "status",
+        });
+        await manager.sync?.({
+            reason: "cli",
+            force: Boolean(opts?.force),
+        });
+        const status = manager.status();
+        if (status.ok === false) {
+            logger.error(`LibraVDB index refresh unavailable: ${status.message ?? "sidecar unavailable"}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (opts?.verbose && !params.quiet) {
+            console.table({
+                Provider: status.provider ?? "libravdb",
+                Model: status.model ?? status.embeddingProfile ?? "unknown",
+                "Turns stored": status.turnCount ?? 0,
+                "Memories stored": status.memoryCount ?? 0,
+                Message: status.message ?? "ok",
+            });
+        }
+        if (!params.quiet) {
+            console.log("LibraVDB memory index refresh delegated to the sidecar.");
+        }
+    }
+    catch (error) {
+        logger.error(`LibraVDB index refresh failed: ${formatError(error)}`);
+        process.exitCode = 1;
+    }
+}
+async function runSearch(runtime, cfg, queryArg, opts, logger) {
+    const query = opts?.query?.trim() || queryArg?.trim();
+    if (!query) {
+        logger.error("LibraVDB search requires a query. Provide a positional query or --query <text>.");
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const bridge = buildMemoryRuntimeBridge(runtime.getRpc, cfg);
+        const { manager } = await bridge.getMemorySearchManager({
+            agentId: opts?.agent,
+        });
+        const maxResults = normalizeLimit(opts?.maxResults ?? opts?.limit);
+        const minScore = normalizeNumber(opts?.minScore);
+        const results = (await manager.search({
+            query,
+            ...(maxResults ? { maxResults } : {}),
+            ...(minScore !== undefined ? { minScore } : {}),
+        }));
+        if (opts?.json) {
+            console.log(JSON.stringify({ results }, null, 2));
+            return;
+        }
+        if (results.length === 0) {
+            console.log("No matches.");
+            return;
+        }
+        for (const result of results) {
+            console.log(`${result.score.toFixed(3)} ${result.path}:${result.startLine}-${result.endLine}`);
+            console.log(result.snippet);
+            console.log("");
+        }
+    }
+    catch (error) {
+        logger.error(`LibraVDB search failed: ${formatError(error)}`);
+        process.exitCode = 1;
+    }
+}
 async function runFlush(runtime, opts, logger) {
     const namespace = resolveCliNamespace(opts);
     if (!namespace) {
@@ -209,6 +363,30 @@ function normalizeLimit(limit) {
     }
     return undefined;
 }
+function normalizeNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const parsed = Number.parseFloat(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+function normalizeOptionBag(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function normalizeActionOptions(queryOrOpts, maybeOpts) {
+    if (maybeOpts && typeof maybeOpts === "object") {
+        return maybeOpts;
+    }
+    return normalizeOptionBag(queryOrOpts);
+}
+function normalizeQueryArg(value) {
+    return typeof value === "string" ? value : undefined;
+}
 function resolveCliNamespace(opts) {
     const userId = opts?.userId?.trim();
     const sessionKey = opts?.sessionKey?.trim();

package/dist/index.js

@@ -1,5 +1,6 @@
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { registerMemoryCli } from "./cli.js";
+import { registerMemoryCliMetadata } from "./cli-descriptors.js";
 import { buildContextEngineFactory } from "./context-engine.js";
 import { createBeforeResetHook, createSessionEndHook } from "./lifecycle-hooks.js";
 import { createDreamPromotionHandle } from "./dream-promotion.js";
@@ -10,10 +11,17 @@ import { createRecallCache } from "./recall-cache.js";
 import { createPluginRuntime } from "./plugin-runtime.js";
 export const MEMORY_ID = "libravdb-memory";
 export function register(api) {
-    const isFullMode = api.registrationMode === "full";
+    if (api.registrationMode === "cli-metadata") {
+        registerMemoryCliMetadata(api);
+        return;
+    }
+    const mode = api.registrationMode;
+    const isFullMode = mode === "full";
     const cfg = api.pluginConfig;
-    // Null in non-full mode — cli.ts skips action handlers when runtime is null.
-    const runtimeOrNull = isFullMode
+    // OpenClaw lazy-loads plugin-owned CLI commands through discovery mode.
+    // Provide a runtime there so subcommands attach real handlers, but keep the
+    // long-lived memory/context-engine registrations gated to full mode only.
+    const runtimeOrNull = (isFullMode || mode === "discovery")
         ? createPluginRuntime(cfg, api.logger ?? console)
         : null;
     registerMemoryCli(api, runtimeOrNull, cfg, api.logger ?? console);
@@ -27,7 +35,7 @@ export function register(api) {
     // Exclusive slot check: refuse to register if another plugin owns the memory slot.
     // plugins.slots.memory is the only configurable slot; context engine exclusivity
     // is enforced by the registry at runtime (no config surface for it).
-    // "none" means memory is disabled — not a conflict, allow registration.
+    // "none" means memory is disabled, not a conflict, allow registration.
     const memSlot = api.config?.plugins?.slots?.memory;
     if (memSlot && memSlot !== MEMORY_ID && memSlot !== "none") {
         throw new Error(`[libravdb-memory] plugins.slots.memory is "${memSlot}". ` +

package/dist/memory-runtime.d.ts

@@ -7,6 +7,8 @@ type MemorySearchParams = {
     q?: string;
     k?: number;
     limit?: number;
+    maxResults?: number;
+    minScore?: number;
     topK?: number;
     userId?: string;
     agentId?: string;
@@ -97,7 +99,10 @@ export declare function buildMemoryRuntimeBridge(getRpc: RpcGetter, cfg: PluginC
                 ingested: boolean;
                 delegatedToContextEngine: boolean;
             }>;
-            sync(): Promise<{
+            sync(_params?: {
+                reason?: string;
+                force?: boolean;
+            }): Promise<{
                 synced: boolean;
                 delegatedToContextEngine: boolean;
             }>;

package/dist/memory-runtime.js

@@ -26,7 +26,8 @@ function createMemorySearchManager(getRpc, cfg, defaults, initialStatus) {
             const params = legacyCall
                 ? {
                     query: queryOrParams,
-                    limit: opts.limit ?? opts.k ?? opts.topK,
+                    limit: opts.limit ?? opts.k ?? opts.maxResults ?? opts.topK,
+                    minScore: opts.minScore,
                     sessionId: opts.sessionId,
                     sessionKey: opts.sessionKey,
                     userId: opts.userId,
@@ -46,7 +47,8 @@ function createMemorySearchManager(getRpc, cfg, defaults, initialStatus) {
                 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 k = normalizePositiveInteger(params.k, params.limit, params.maxResults, params.topK, cfg.topK, 8);
+            const minScore = normalizeNumber(params.minScore);
             const rpc = await getRpc();
             const result = dreamQuery.active
                 ? await rpc.call("search_text", {
@@ -55,14 +57,17 @@ function createMemorySearchManager(getRpc, cfg, defaults, initialStatus) {
                     k,
                 })
                 : await searchResolvedCollections(rpc, cfg, userId, sessionId, queryText, k);
-            const legacyResults = result.results.map((item) => ({
+            const filteredResults = minScore === undefined
+                ? result.results
+                : result.results.filter((item) => item.score >= minScore);
+            const legacyResults = filteredResults.map((item) => ({
                 ...item,
                 content: item.text,
             }));
             if (legacyCall) {
                 return { results: legacyResults };
             }
-            return result.results.map(toMemorySearchResult);
+            return filteredResults.map(toMemorySearchResult);
         },
         async readFile(params) {
             const located = await loadSearchResultText(getRpc, params.relPath);
@@ -79,7 +84,7 @@ function createMemorySearchManager(getRpc, cfg, defaults, initialStatus) {
             // The plugin already owns per-turn ingest through the context engine.
             return { ingested: false, delegatedToContextEngine: true };
         },
-        async sync() {
+        async sync(_params) {
             cachedStatus = await readStatus(getRpc, defaults.purpose);
             return { synced: true, delegatedToContextEngine: true };
         },
@@ -215,3 +220,6 @@ function normalizePositiveInteger(...values) {
     }
     return 8;
 }
+function normalizeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}

package/docs/features.md

@@ -114,6 +114,8 @@ CLI API.
 | Command | Purpose |
 |---|---|
 | `openclaw memory status` | Show sidecar health, counts, active thresholds, and model readiness. |
+| `openclaw memory index --force` | Refresh delegated sidecar index state for OpenClaw memory CLI compatibility. |
+| `openclaw memory search "query"` | Search LibraVDB memory through the active memory runtime bridge. |
 | `openclaw memory export --user-id <userId>` | Stream stored memories as newline-delimited JSON for one durable namespace. |
 | `openclaw memory export --session-key <sessionKey>` | Export a namespace derived from a session key. |
 | `openclaw memory flush --user-id <userId>` | Delete one durable user namespace after confirmation. |

package/openclaw.plugin.json

@@ -2,11 +2,16 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.4.17",
+  "version": "1.4.19",
   "kind": [
     "memory",
     "context-engine"
   ],
+  "activation": {
+    "onCommands": [
+      "memory"
+    ]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.4.17",
+  "version": "1.4.19",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,6 +20,7 @@
     "README.md",
     "HOOK.md",
     "index.js",
+    "cli-metadata.js",
     "openclaw.plugin.json",
     "package.json",
     "docs/",