@psiclawops/hypermem 0.8.2 → 0.8.4

package/node_modules/zod/v4/package.json

@@ -0,0 +1,6 @@
+{ 
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.cts" 
+}

package/node_modules/zod/v4-mini/index.cjs

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.z = void 0;
+const z = __importStar(require("../v4/mini/external.cjs"));
+exports.z = z;
+__exportStar(require("../v4/mini/external.cjs"), exports);

package/node_modules/zod/v4-mini/index.d.cts

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.cjs";
+export * from "../v4/mini/external.cjs";
+export { z };

package/node_modules/zod/v4-mini/index.d.ts

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.js";
+export * from "../v4/mini/external.js";
+export { z };

package/node_modules/zod/v4-mini/index.js

@@ -0,0 +1,3 @@
+import * as z from "../v4/mini/external.js";
+export * from "../v4/mini/external.js";
+export { z };

package/node_modules/zod/v4-mini/package.json

@@ -0,0 +1,6 @@
+{ 
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "types": "./index.d.cts" 
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@psiclawops/hypermem",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "description": "Agent-centric memory and context composition engine for OpenClaw",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
-    "hypermem-status": "bin/hypermem-status.mjs"
+    "hypermem-status": "bin/hypermem-status.mjs",
+    "hypermem-install": "scripts/install-runtime.mjs"
   },
   "exports": {
     ".": {
@@ -34,7 +35,8 @@
     "validate:docs": "node scripts/validate-docs.mjs"
   },
   "dependencies": {
-    "sqlite-vec": "^0.1.9"
+    "sqlite-vec": "^0.1.9",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -43,10 +45,24 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "bundledDependencies": [
+    "sqlite-vec",
+    "zod"
+  ],
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
+    "bin/hypermem-status.mjs",
+    "plugin/dist/**",
+    "plugin/package.json",
+    "plugin/openclaw.plugin.json",
+    "memory-plugin/dist/**",
+    "memory-plugin/package.json",
+    "memory-plugin/openclaw.plugin.json",
+    "scripts/install-runtime.mjs",
+    "docs/*.md",
+    "install.sh",
     "README.md",
     "INSTALL.md",
     "CHANGELOG.md",

package/plugin/dist/index.d.ts

@@ -0,0 +1,153 @@
+/**
+ * hypermem Context Engine Plugin
+ *
+ * Implements OpenClaw's ContextEngine interface backed by hypermem's
+ * four-layer memory architecture:
+ *
+ *   L1 Cache    — SQLite `:memory:` hot session working memory
+ *   L2 Messages — per-agent conversation history (SQLite)
+ *   L3 Vectors  — semantic + keyword search (KNN + FTS5)
+ *   L4 Library  — facts, knowledge, episodes, preferences
+ *
+ * Lifecycle mapping:
+ *   ingest()     → record each message into messages.db
+ *   assemble()   → compositor builds context from all four layers
+ *   compact()    → delegate to runtime (ownsCompaction: false)
+ *   afterTurn()  → trigger background indexer (fire-and-forget)
+ *   bootstrap()  → warm hot-cache session, register agent in fleet
+ *   dispose()    → close hypermem connections
+ *
+ * Session key format expected: "agent:<agentId>:<channel>:<name>"
+ */
+import type { NeutralMessage, NeutralToolCall, NeutralToolResult, ComposeRequest, ComposeResult } from '@psiclawops/hypermem';
+import { resolveTrimBudgets } from '@psiclawops/hypermem';
+export type { NeutralMessage, NeutralToolCall, NeutralToolResult, ComposeRequest, ComposeResult };
+type TrimTelemetryPath = 'assemble.normal' | 'assemble.toolLoop' | 'assemble.subagent' | 'reshape' | 'compact.nuclear' | 'compact.history' | 'compact.history2' | 'afterTurn.secondary' | 'warmstart';
+type DegradationTelemetryPath = 'compose' | 'toolLoop';
+interface DegradationTelemetryFields {
+    agentId: string;
+    sessionKey: string;
+    turnId: string;
+    path: DegradationTelemetryPath;
+    toolChainCoEjections?: number;
+    toolChainStubReplacements?: number;
+    artifactDegradations?: number;
+    artifactOversizeThresholdTokens?: number;
+    replayState?: 'entering' | 'stabilizing' | 'exited';
+    replayReason?: string;
+}
+declare function trimTelemetry(fields: {
+    path: TrimTelemetryPath;
+    agentId: string;
+    sessionKey: string;
+    preTokens: number;
+    postTokens: number;
+    removed: number;
+    cacheInvalidated: boolean;
+    reason: string;
+}): void;
+declare function assembleTrace(fields: {
+    agentId: string;
+    sessionKey: string;
+    turnId: string;
+    path: 'cold' | 'replay' | 'subagent';
+    toolLoop: boolean;
+    msgCount: number;
+}): void;
+declare function degradationTelemetry(fields: DegradationTelemetryFields): void;
+declare function nextTurnId(): string;
+declare const GUARD_TELEMETRY_REASONS: readonly ["warmstart-pressure-demoted", "reshape-downshift-demoted", "duplicate-claim-suppressed", "afterturn-secondary-demoted", "window-within-budget-skip", "pressure-accounting-anomaly"];
+type GuardTelemetryReason = typeof GUARD_TELEMETRY_REASONS[number];
+declare function beginTrimOwnerTurn(sessionKey: string, turnId: string): void;
+declare function endTrimOwnerTurn(sessionKey: string, turnId: string): void;
+/**
+ * Claim the steady-state trim owner slot for the current turn.
+ *
+ * Behavior:
+ *   - compact.* paths are exception-only and pass through without claiming.
+ *   - Non-steady paths (warmstart, reshape, afterTurn.secondary) also pass
+ *     through without claiming. Demoted/no-op sites should normally emit
+ *     via guardTelemetry() instead so they stay visible without contending
+ *     for ownership (sub-tasks 2.2 and 2.3 wire this in).
+ *   - Steady-state paths (assemble.normal, assemble.subagent,
+ *     assemble.toolLoop) claim the single owner slot for the current turn.
+ *     The first such claim succeeds. A second steady-state claim against the
+ *     same turn is a duplicate-turn violation: it throws loudly under
+ *     NODE_ENV='development' and warns in other environments (returning
+ *     false so non-dev runtimes keep working).
+ *
+ * Callers should invoke this immediately before the real
+ * trimHistoryToTokenBudget() call. Guard telemetry does NOT route through
+ * this helper — it is explicitly excluded from the steady-state invariant.
+ *
+ * Returns true when the claim succeeds (or is exempt); false on a swallowed
+ * duplicate claim in non-development. In development the duplicate throws
+ * before returning.
+ */
+declare function claimTrimOwner(sessionKey: string, turnId: string, path: TrimTelemetryPath): boolean;
+/**
+ * Non-counting guard / noop telemetry.
+ *
+ * Emits a `trim-guard` record on the same JSONL channel as trimTelemetry()
+ * but with a distinct event name so per-turn reporting (scripts/trim-report.mjs,
+ * future ownership dashboards) can keep it out of `trimCount`. Used by
+ * demoted/no-op call sites in 2.2 and 2.3 so their path labels stay visible
+ * in telemetry without consuming a steady-state owner slot.
+ *
+ * Zero-cost when telemetry is off. Never throws.
+ */
+declare function guardTelemetry(fields: {
+    path: TrimTelemetryPath;
+    agentId: string;
+    sessionKey: string;
+    reason: GuardTelemetryReason;
+}): void;
+export declare const __telemetryForTests: {
+    trimTelemetry: typeof trimTelemetry;
+    assembleTrace: typeof assembleTrace;
+    degradationTelemetry: typeof degradationTelemetry;
+    guardTelemetry: typeof guardTelemetry;
+    nextTurnId: typeof nextTurnId;
+    beginTrimOwnerTurn: typeof beginTrimOwnerTurn;
+    endTrimOwnerTurn: typeof endTrimOwnerTurn;
+    claimTrimOwner: typeof claimTrimOwner;
+    TRIM_SOFT_TARGET: number;
+    TRIM_GROWTH_THRESHOLD: number;
+    TRIM_HEADROOM_FRACTION: number;
+    resolveTrimBudgets: typeof resolveTrimBudgets;
+    reset(): void;
+};
+export declare const CONTEXT_WINDOW_OVERRIDE_KEY_REGEX: RegExp;
+export type ContextWindowOverride = {
+    contextTokens?: number;
+    contextWindow?: number;
+};
+export declare function sanitizeContextWindowOverrides(raw: unknown): {
+    value: Record<string, ContextWindowOverride>;
+    warnings: string[];
+};
+export declare function resolveEffectiveBudget(args: {
+    tokenBudget?: number;
+    model?: string;
+    contextWindowSize: number;
+    contextWindowReserve: number;
+    contextWindowOverrides?: Record<string, ContextWindowOverride>;
+}): {
+    budget: number;
+    source: string;
+};
+/**
+ * Bust the assembly cache for a specific agent+session.
+ * Call this after writing to identity files (SOUL.md, IDENTITY.md, TOOLS.md,
+ * USER.md) to ensure the next assemble() runs full compositor, not a replay.
+ */
+export declare function bustAssemblyCache(agentId: string, sessionKey: string): Promise<void>;
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/plugin/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}