@xdarkicex/openclaw-memory-libravdb 1.4.14 → 1.4.17

package/dist/context-engine.js

@@ -30,15 +30,6 @@ function normalizeCompactResult(response) {
         },
     };
 }
-function describeUnexpectedContent(value) {
-    try {
-        const serialized = JSON.stringify(value);
-        return serialized === undefined ? String(value) : serialized;
-    }
-    catch {
-        return String(value);
-    }
-}
 function stringifyKernelBlock(block) {
     if (!block || typeof block !== "object") {
         return "";
@@ -69,10 +60,6 @@ function stringifyKernelBlock(block) {
         case "image":
             return "[image omitted]";
         default:
-            console.warn("[libravdb] unsupported kernel content block", {
-                type: record.type,
-                block: describeUnexpectedContent(record),
-            });
             return typeof record.text === "string" ? record.text : "";
     }
 }
@@ -81,10 +68,6 @@ function normalizeKernelContent(content) {
         return content;
     }
     if (!Array.isArray(content)) {
-        console.warn("[libravdb] unexpected kernel content shape", {
-            kind: typeof content,
-            value: describeUnexpectedContent(content),
-        });
         return "";
     }
     return content.map(stringifyKernelBlock).filter((part) => part.length > 0).join("\n");
@@ -101,6 +84,14 @@ function approximateMessageTokens(message) {
 function approximateMessagesTokens(messages) {
     return messages.reduce((sum, message) => sum + approximateMessageTokens(message), 0);
 }
+function normalizeCurrentTokenCount(currentTokenCount) {
+    if (typeof currentTokenCount !== "number" ||
+        !Number.isFinite(currentTokenCount) ||
+        currentTokenCount <= 0) {
+        return undefined;
+    }
+    return Math.max(1, Math.floor(currentTokenCount));
+}
 function normalizeTokenBudget(tokenBudget) {
     if (typeof tokenBudget !== "number" || !Number.isFinite(tokenBudget) || tokenBudget <= 0) {
         return undefined;
@@ -128,6 +119,33 @@ function resolveDynamicCompactThreshold(tokenBudget, compactThreshold, compactio
     const fraction = normalizeThresholdFraction(compactionThresholdFraction);
     return Math.max(1, Math.floor(normalizedBudget * fraction));
 }
+function resolvePredictiveCompactionTarget(params) {
+    const currentTokenCount = normalizeCurrentTokenCount(params.currentTokenCount);
+    const threshold = normalizeTokenBudget(params.threshold);
+    if (currentTokenCount == null || threshold == null || currentTokenCount < threshold) {
+        return undefined;
+    }
+    const belowThresholdTarget = Math.max(1, threshold - 1);
+    return belowThresholdTarget < currentTokenCount
+        ? belowThresholdTarget
+        : Math.max(1, currentTokenCount - 1);
+}
+function logPredictiveCompactionAttempt(params) {
+    params.logger.info?.(`LibraVDB predictive compaction trigger phase=${params.phase} sessionId=${params.sessionId} ` +
+        `currentTokenCount=${params.currentTokenCount} threshold=${params.threshold} ` +
+        `targetSize=${params.targetSize} tokenBudget=${params.tokenBudget ?? "unknown"}`);
+}
+function logPredictiveCompactionOutcome(params) {
+    const message = `LibraVDB predictive compaction ${params.compacted ? "completed" : "did not compact"} ` +
+        `phase=${params.phase} sessionId=${params.sessionId} currentTokenCount=${params.currentTokenCount} ` +
+        `threshold=${params.threshold} targetSize=${params.targetSize} tokenBudget=${params.tokenBudget ?? "unknown"}` +
+        (params.reason ? ` reason=${params.reason}` : "");
+    if (params.compacted) {
+        params.logger.info?.(message);
+        return;
+    }
+    params.logger.warn?.(message);
+}
 function truncateContentToTokenBudget(content, tokenBudget) {
     if (tokenBudget <= 0)
         return "";
@@ -191,6 +209,10 @@ function buildBudgetFallbackContext(messages, tokenBudget) {
         systemPromptAddition: "",
     };
 }
+function resolvePredictiveCompactionTokenCount(args) {
+    return (normalizeCurrentTokenCount(args.currentTokenCount) ??
+        approximateMessagesTokens(args.messages) + approximateTokenCount(args.prompt ?? ""));
+}
 export function normalizeKernelMessage(message) {
     return {
         role: message.role,
@@ -263,7 +285,12 @@ export function buildContextEngineFactory(runtime, cfg, recallCache, logger = co
             sessionId: requireSessionId(args.sessionId, "compact"),
             force: args.force,
             ...(typeof targetSize === "number" ? { targetSize } : {}),
-            ...(typeof args.currentTokenCount === "number" ? { currentTokenCount: args.currentTokenCount } : {}),
+            ...(() => {
+                const normalizedCurrentTokenCount = normalizeCurrentTokenCount(args.currentTokenCount);
+                return normalizedCurrentTokenCount != null
+                    ? { currentTokenCount: normalizedCurrentTokenCount }
+                    : {};
+            })(),
             ...(typeof cfg.continuityMinTurns === "number"
                 ? { continuityMinTurns: cfg.continuityMinTurns }
                 : {}),
@@ -293,6 +320,45 @@ export function buildContextEngineFactory(runtime, cfg, recallCache, logger = co
             };
         }
     }
+    async function performAfterTurnPredictiveCompaction(args) {
+        const dynamicCompactThreshold = getDynamicCompactThreshold(args.tokenBudget);
+        const predictiveTargetSize = resolvePredictiveCompactionTarget({
+            currentTokenCount: args.currentTokenCount,
+            threshold: dynamicCompactThreshold,
+        });
+        if (args.currentTokenCount == null ||
+            dynamicCompactThreshold == null ||
+            predictiveTargetSize == null) {
+            return;
+        }
+        logPredictiveCompactionAttempt({
+            logger,
+            phase: "afterTurn",
+            sessionId: args.sessionId,
+            currentTokenCount: args.currentTokenCount,
+            threshold: dynamicCompactThreshold,
+            targetSize: predictiveTargetSize,
+            tokenBudget: args.tokenBudget,
+        });
+        const compactionResult = await runCompaction({
+            sessionId: args.sessionId,
+            targetSize: predictiveTargetSize,
+            tokenBudget: args.tokenBudget,
+            force: true,
+            currentTokenCount: args.currentTokenCount,
+        });
+        logPredictiveCompactionOutcome({
+            logger,
+            phase: "afterTurn",
+            sessionId: args.sessionId,
+            currentTokenCount: args.currentTokenCount,
+            threshold: dynamicCompactThreshold,
+            targetSize: predictiveTargetSize,
+            tokenBudget: args.tokenBudget,
+            compacted: compactionResult.compacted,
+            reason: compactionResult.reason,
+        });
+    }
     return {
         info: { id: "libravdb-memory", name: "LibraVDB Memory", ownsCompaction: true },
         ownsCompaction: true,
@@ -337,18 +403,47 @@ export function buildContextEngineFactory(runtime, cfg, recallCache, logger = co
         },
         async assemble(args) {
             const messages = normalizeKernelMessages(args.messages);
-            const currentContextTokens = approximateMessagesTokens(messages) + approximateTokenCount(args.prompt ?? "");
+            const currentContextTokens = resolvePredictiveCompactionTokenCount({
+                currentTokenCount: args.currentTokenCount,
+                messages,
+                prompt: args.prompt,
+            });
             const dynamicCompactThreshold = getDynamicCompactThreshold(args.tokenBudget);
-            if (dynamicCompactThreshold != null &&
-                currentContextTokens >= dynamicCompactThreshold) {
+            const predictiveTargetSize = resolvePredictiveCompactionTarget({
+                currentTokenCount: currentContextTokens,
+                threshold: dynamicCompactThreshold,
+            });
+            if (dynamicCompactThreshold != null && predictiveTargetSize != null) {
+                logPredictiveCompactionAttempt({
+                    logger,
+                    phase: "assemble",
+                    sessionId: args.sessionId,
+                    currentTokenCount: currentContextTokens,
+                    threshold: dynamicCompactThreshold,
+                    targetSize: predictiveTargetSize,
+                    tokenBudget: args.tokenBudget,
+                });
                 const compactionResult = await runCompaction({
                     sessionId: args.sessionId,
+                    targetSize: predictiveTargetSize,
                     tokenBudget: args.tokenBudget,
                     force: true,
                     currentTokenCount: currentContextTokens,
                 });
-                if (!compactionResult.ok || !compactionResult.compacted) {
-                    logger.warn?.(`LibraVDB predictive compaction blocked assemble path at ${currentContextTokens} tokens (threshold=${dynamicCompactThreshold}): ${compactionResult.reason ?? "compaction declined"}`);
+                logPredictiveCompactionOutcome({
+                    logger,
+                    phase: "assemble",
+                    sessionId: args.sessionId,
+                    currentTokenCount: currentContextTokens,
+                    threshold: dynamicCompactThreshold,
+                    targetSize: predictiveTargetSize,
+                    tokenBudget: args.tokenBudget,
+                    compacted: compactionResult.compacted,
+                    reason: compactionResult.reason,
+                });
+                if (!compactionResult.ok) {
+                    logger.warn?.(`LibraVDB predictive compaction blocked assemble path at ${currentContextTokens} tokens ` +
+                        `(threshold=${dynamicCompactThreshold}): ${compactionResult.reason ?? "compaction failed"}`);
                     return buildBudgetFallbackContext(messages, args.tokenBudget);
                 }
             }
@@ -396,8 +491,11 @@ export function buildContextEngineFactory(runtime, cfg, recallCache, logger = co
         async afterTurn(args) {
             const messages = normalizeKernelMessages(args.messages);
             const kernel = runtime.getKernel();
+            const currentTokenCount = normalizeCurrentTokenCount(typeof args.runtimeContext?.currentTokenCount === "number"
+                ? args.runtimeContext.currentTokenCount
+                : undefined);
             if (kernel) {
-                return await kernel.afterTurn({
+                const result = await kernel.afterTurn({
                     sessionId: args.sessionId,
                     sessionKey: args.sessionKey,
                     userId: args.userId,
@@ -405,12 +503,24 @@ export function buildContextEngineFactory(runtime, cfg, recallCache, logger = co
                     prePromptMessageCount: args.prePromptMessageCount,
                     isHeartbeat: args.isHeartbeat,
                 });
+                await performAfterTurnPredictiveCompaction({
+                    sessionId: args.sessionId,
+                    tokenBudget: args.tokenBudget,
+                    currentTokenCount,
+                });
+                return result;
             }
             const rpc = await runtime.getRpc();
-            return await rpc.call("after_turn_kernel", {
+            const result = await rpc.call("after_turn_kernel", {
                 ...args,
                 messages,
             });
+            await performAfterTurnPredictiveCompaction({
+                sessionId: args.sessionId,
+                tokenBudget: args.tokenBudget,
+                currentTokenCount,
+            });
+            return result;
         }
     };
 }

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

@@ -8,33 +8,57 @@ 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) {
+    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/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.

package/docs/development.md

@@ -0,0 +1,98 @@
+# Development
+
+This document covers source setup and repository maintenance tasks. For user
+installation, use [Install](./install.md).
+
+## Prerequisites
+
+- Node.js `>= 22`
+- `pnpm`
+- OpenClaw CLI for end-to-end plugin testing
+- a published or locally built `libravdbd` daemon for integration tests
+
+Go is only required when building the daemon from a local daemon checkout or
+regenerating Go gRPC stubs.
+
+## Source Setup
+
+```bash
+pnpm install
+pnpm check
+```
+
+`pnpm check` runs TypeScript validation and unit tests:
+
+```bash
+tsc --noEmit
+tsc -p tsconfig.tests.json && node --test .ts-build/test/unit/*.test.js
+```
+
+## Local Daemon Build
+
+Prepare `.daemon-bin/libravdbd` for local plugin testing:
+
+```bash
+bash scripts/build-daemon.sh
+```
+
+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 a local daemon repo
+
+For daemon-internal Go development and release work, use the separate
+`libravdbd` repository.
+
+## Validation Commands
+
+```bash
+pnpm check
+npm run test:integration
+```
+
+Benchmark and tuning commands are documented in
+[Performance and tuning](./performance-and-tuning.md).
+
+## Generated IPC Files
+
+The plugin imports generated IPC envelope and RPC payload classes from
+`src/generated/libravdb/ipc/v1/rpc_pb.js`.
+
+Those generated files are checked in and copied into `dist/generated/` during
+`npm run build`:
+
+```bash
+npm run build
+```
+
+Do not replace those imports with the older external
+`@xdarkicex/libravdb-contracts` path. The current package resolves generated
+types from this repository.
+
+## Proto Generation
+
+The repo also contains `api/proto/intelligence_kernel/v1/kernel.proto` and a
+small `Makefile` target for Go gRPC stub generation:
+
+```bash
+make proto
+```
+
+That target assumes Homebrew-style locations for `go`, `protoc`, and the Go
+plugins. Adjust the Makefile locally if your toolchain lives elsewhere.
+
+## Release Shape
+
+The npm package contains:
+
+- `README.md`
+- `HOOK.md`
+- `index.js`
+- `openclaw.plugin.json`
+- `package.json`
+- `docs/`
+- `dist/`
+
+The package is connect-only. It does not compile Go code, download models, or
+manage the daemon process during plugin installation.