@xdarkicex/openclaw-memory-libravdb 1.4.16 → 1.4.18

package/dist/cli.js

@@ -1,17 +1,68 @@
 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) {
+            // 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");
+            ensureCommand(root, "dream-promote").description("Promote vetted dream diary entries into the dedicated dream collection");
+            return;
+        }
         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) {
@@ -23,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) {
@@ -44,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) {
@@ -67,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,
@@ -84,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",
@@ -97,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) {
@@ -198,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.d.ts

@@ -1,4 +1,6 @@
 import { type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry";
+export declare const MEMORY_ID = "libravdb-memory";
+export declare function register(api: OpenClawPluginApi): void;
 declare const _default: {
     id: string;
     name: string;

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";
@@ -8,33 +9,61 @@ import { buildMemoryPromptSection } from "./memory-provider.js";
 import { buildMemoryRuntimeBridge } from "./memory-runtime.js";
 import { createRecallCache } from "./recall-cache.js";
 import { createPluginRuntime } from "./plugin-runtime.js";
+export const MEMORY_ID = "libravdb-memory";
+export function register(api) {
+    if (api.registrationMode === "cli-metadata") {
+        registerMemoryCliMetadata(api);
+        return;
+    }
+    const isFullMode = api.registrationMode === "full";
+    const cfg = api.pluginConfig;
+    // Null in non-full mode: cli.ts skips action handlers when runtime is null.
+    const runtimeOrNull = isFullMode
+        ? createPluginRuntime(cfg, api.logger ?? console)
+        : null;
+    registerMemoryCli(api, runtimeOrNull, cfg, api.logger ?? console);
+    if (!isFullMode)
+        return;
+    // TypeScript can't narrow through the ternary, so re-bind and guard.
+    const runtime = runtimeOrNull;
+    if (!runtime)
+        return; // unreachable but satisfies the type checker
+    const recallCache = createRecallCache();
+    // 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.
+    const memSlot = api.config?.plugins?.slots?.memory;
+    if (memSlot && memSlot !== MEMORY_ID && memSlot !== "none") {
+        throw new Error(`[libravdb-memory] plugins.slots.memory is "${memSlot}". ` +
+            `Set it to "libravdb-memory" before enabling this plugin.`);
+    }
+    // Migrated from three legacy calls to a single registerMemoryCapability.
+    api.registerMemoryCapability(MEMORY_ID, {
+        promptBuilder: buildMemoryPromptSection(runtime.getRpc, cfg, recallCache),
+        runtime: buildMemoryRuntimeBridge(runtime.getRpc, cfg),
+    });
+    api.registerContextEngine(MEMORY_ID, () => buildContextEngineFactory(runtime, cfg, recallCache, api.logger ?? console));
+    const markdownIngestion = createMarkdownIngestionHandle(cfg, runtime.getRpc, api.logger ?? console);
+    const dreamPromotion = createDreamPromotionHandle(cfg, runtime.getRpc, api.logger ?? console);
+    void markdownIngestion.start().catch((error) => {
+        api.logger?.warn?.(`LibraVDB markdown ingestion failed to start: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    void dreamPromotion.start().catch((error) => {
+        api.logger?.warn?.(`LibraVDB dream promotion failed to start: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    api.on("before_reset", createBeforeResetHook(runtime, api.logger ?? console));
+    api.on("session_end", createSessionEndHook(runtime, api.logger ?? console));
+    api.on("gateway_stop", async () => {
+        await dreamPromotion.stop();
+        await markdownIngestion.stop();
+        await runtime.shutdown();
+    });
+}
 export default definePluginEntry({
-    id: "libravdb-memory",
+    id: MEMORY_ID,
     name: "LibraVDB Memory",
     description: "Persistent vector memory with three-tier hybrid scoring",
     kind: ["memory", "context-engine"],
-    register(api) {
-        const cfg = api.pluginConfig;
-        const recallCache = createRecallCache();
-        const runtime = createPluginRuntime(cfg, api.logger ?? console);
-        const markdownIngestion = createMarkdownIngestionHandle(cfg, runtime.getRpc, api.logger ?? console);
-        const dreamPromotion = createDreamPromotionHandle(cfg, runtime.getRpc, api.logger ?? console);
-        void markdownIngestion.start().catch((error) => {
-            api.logger?.warn?.(`LibraVDB markdown ingestion failed to start: ${error instanceof Error ? error.message : String(error)}`);
-        });
-        void dreamPromotion.start().catch((error) => {
-            api.logger?.warn?.(`LibraVDB dream promotion failed to start: ${error instanceof Error ? error.message : String(error)}`);
-        });
-        registerMemoryCli(api, runtime, cfg, api.logger ?? console);
-        api.registerContextEngine("libravdb-memory", () => buildContextEngineFactory(runtime, cfg, recallCache, api.logger ?? console));
-        api.registerMemoryPromptSection(buildMemoryPromptSection(runtime.getRpc, cfg, recallCache));
-        api.registerMemoryRuntime?.(buildMemoryRuntimeBridge(runtime.getRpc, cfg));
-        api.on("before_reset", createBeforeResetHook(runtime, api.logger ?? console));
-        api.on("session_end", createSessionEndHook(runtime, api.logger ?? console));
-        api.on("gateway_stop", async () => {
-            await dreamPromotion.stop();
-            await markdownIngestion.stop();
-            await runtime.shutdown();
-        });
-    },
+    register,
 });

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

@@ -1,16 +1,31 @@
-# Documentation Index
-
-This index lists the public docs that remain in the main repo. Detailed math
-and private design notes are kept out of the public index on purpose.
-
-- [installation.md](./installation.md) - Complete install, activation, verification, and troubleshooting reference.
-- [install.md](./install.md) - Practical lifecycle guide for Homebrew, the OpenClaw plugin, and manual daemon management.
-- [uninstall.md](./uninstall.md) - Clean shutdown and removal guide for the plugin, daemon, and optional local data.
-- [architecture.md](./architecture.md) - Public system overview covering the plugin, daemon, storage, retrieval, and compaction flow.
-- [problem.md](./problem.md) - Technical argument for replacing the stock OpenClaw memory lifecycle in this use case.
-- [dependencies.md](./dependencies.md) - Why LibraVDB and slab-based storage were chosen for this plugin.
-- [models.md](./models.md) - ONNX model strategy, latency trade-offs, and shipped model roles.
-- [security.md](./security.md) - Security model, untrusted-memory framing, isolation guarantees, and deletion boundaries.
-- [contributing.md](./contributing.md) - Contributor workflow, prerequisites, and invariant test expectations.
-- [architecture-decisions/README.md](./architecture-decisions/README.md) - Index of the repository ADRs.
-- [embedding-profiles.md](./embedding-profiles.md) - Shipped embedding profile baseline and current profile metadata.
+# LibraVDB Memory Docs
+
+This directory holds the operational and design docs for the LibraVDB Memory
+OpenClaw plugin. The root README is the public entry point; these files go
+deeper by goal.
+
+## Start Here
+
+- [Install](./install.md) - shortest supported install and daemon lifecycle path.
+- [Installation reference](./installation.md) - requirements, activation, verification, and troubleshooting.
+- [Uninstall](./uninstall.md) - safe disable, daemon 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.
+- [Dependency rationale](./dependencies.md) - why LibraVDB and slab-style storage fit this workload.
+- [Architecture decisions](./architecture-decisions/README.md) - accepted ADRs.
+
+## Configure And Operate
+
+- [Features](./features.md) - markdown ingestion, Obsidian ingestion, dream promotion, and memory CLI commands.
+- [Security](./security.md) - trust boundaries, untrusted-memory framing, collection isolation, and deletion limits.
+- [Embedding profiles](./embedding-profiles.md) - shipped embedding profile metadata and defaults.
+- [Models](./models.md) - local ONNX model strategy and summarization roles.
+
+## 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.
+- [Contributing](./contributing.md) - contributor workflow and repository expectations.

package/docs/assets/libravdb-logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="170" viewBox="0 0 1280 170" role="img" aria-labelledby="title desc">
+  <title id="title">LibraVDB</title>
+  <desc id="desc">Dark purple LibraVDB wordmark.</desc>
+  <rect width="1280" height="170" fill="none"/>
+  <text
+    x="640"
+    y="128"
+    text-anchor="middle"
+    fill="#5B21B6"
+    font-family="Inter, Avenir Next, Helvetica Neue, Arial, sans-serif"
+    font-size="150"
+    font-weight="800"
+    letter-spacing="0">LibraVDB</text>
+</svg>

package/docs/contributing.md

@@ -1,88 +1,35 @@
 # Contributing
 
-## Prerequisites
+Use [Development](./development.md) for source setup, local daemon preparation,
+generated IPC files, and validation commands. This document covers contribution
+expectations.
 
-- Node.js `>= 22`
-- `pnpm`
-- OpenClaw CLI for end-to-end plugin testing
+## Baseline Checks
 
-## Core Validation Commands
-
-TypeScript and unit checks:
+Before opening a PR:
 
 ```bash
 pnpm check
-```
-
-Integration tests:
-
-```bash
-npm run test:integration
-```
-
-Plugin integration tests:
-
-```bash
 npm run test:integration
 ```
 
-## Local Daemon Build
+Integration tests require a running daemon or a prepared local daemon binary.
+Use:
 
 ```bash
 bash scripts/build-daemon.sh
 ```
 
-This prepares `.daemon-bin/libravdbd` for local plugin testing and copies locally available bundled assets into `.daemon-bin/`.
-
-Supported inputs:
-
-- installed daemon on `PATH` such as `brew install libravdbd`
-- `LIBRAVDBD_BINARY_PATH=/path/to/libravdbd`
-- `LIBRAVDBD_SOURCE_DIR=/path/to/libravdbd` to build from your private local daemon repo
-
-For daemon-internal Go development and release work, use the separate `libravdbd` repository.
+## Behavioral Changes
 
-## Gating Invariants
-
-Do not weaken the gate invariants casually. The daemon-owned tests in `libravdbd/compact/gate_test.go` check structural properties:
-
-- empty-memory novelty
-- saturation veto
-- convex boundedness
-- conversational collapse at `T = 0`
-- technical collapse at `T = 1`
-- non-overfiring conversational structure on code
-
-If you add a new signal, it must preserve those invariants.
-
-## Calibration Coverage
-
-There is not yet a dedicated `gate_calibration_test.go` golden set in the
-repository. Current gating correctness is enforced by the invariant suite in
-`libravdbd/compact/gate_test.go`.
-
-If you introduce new signals or change weighting behavior, do not only update
-the implementation. Add one of:
-
-- a new invariant if the change alters a structural property of the gate
-- a dedicated calibration/golden test file if the change adds new labeled
-  examples or expected decompositions
-
-Do not rewrite expectations just to make regressions disappear.
+If you change retrieval, compaction, or ranking behavior, add or update the
+matching validation coverage and avoid weakening checks just to hide a
+regression.
 
 ## PR Expectations
 
-Before opening a PR:
-
-- `pnpm check` must pass
-- plugin integration coverage must pass against a running daemon or a prepared local daemon binary
-- any new gating signal must come with calibration or invariant coverage
-- any retrieval math or gating change must be reflected in the private design notes
-
-## Release Versioning
-
-`package.json` is the source of truth for the release version.
-
-The release automation syncs `openclaw.plugin.json` from `package.json` during the
-auto-bump/tag flow, and the publish workflow refuses to publish if the Git tag,
-`package.json`, and `openclaw.plugin.json` versions do not all match.
+- Keep plugin lifecycle and daemon lifecycle separate.
+- Include focused docs updates for user-visible behavior or config changes.
+- Keep internal design changes reflected in the appropriate design notes.
+- Do not add install-time daemon bootstrap to the npm/OpenClaw package without
+  documenting the security and distribution trade-off.