@psiclawops/hypermem 0.9.0 → 0.9.1

package/ARCHITECTURE.md

@@ -152,7 +152,7 @@ Visibility-tiered access model for cross-agent knowledge queries:
 
 `visibilityFilter()` resolves access levels using an `OrgRegistry` — a mapping of agents to tiers, orgs, and capabilities. Currently loaded from a hardcoded `defaultOrgRegistry()` in `cross-agent.ts`.
 
-**Known limitation:** `defaultOrgRegistry()` duplicates fleet structure that lives authoritatively in `fleet_agents` + `fleet_orgs` in library.db. See [docs/ROADMAP.md](docs/ROADMAP.md) for the planned live-load migration.
+**Known limitation:** `defaultOrgRegistry()` duplicates fleet structure that lives authoritatively in `fleet_agents` + `fleet_orgs` in library.db. The planned migration is to live-load the registry from library.db on startup, with the hardcoded registry retained only as a cold-start fallback.
 
 ### Unknown Agent Fallback (Restrictive Default)
 
@@ -229,7 +229,7 @@ Data Flow (current — P0 stabilized, window/cursor active):
 6. `compose()` deduplicates history by `id` before budget assembly.
 7. `getHistory()` honors its `limit` parameter on BOTH hot-cache and SQLite paths.
 
-For open and deferred items, see [docs/ROADMAP.md](docs/ROADMAP.md).
+Open and deferred work is tracked outside this public architecture reference.
 
 ### Runtime Contract
 

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to hypermem are documented here.
 
+## 0.9.1 - plugin singleton + memory-plugin config patch
+
+- **HyperMem singleton registry is now backed by `globalThis`.** Multiple module instances loaded from `node_modules` would each construct a private singleton, so HyperCompositor and the memory plugin could end up writing to different SQLite/vector stores. The registry now lives on `globalThis`, guaranteeing one instance per `dataDir` regardless of how many copies of the module are resolved.
+- **Memory plugin loads user config.** The memory plugin entrypoint now reads operator config (provider, embedding model, dimensions) instead of falling back to library defaults, so a 768d nomic embedder in OpenClaw config no longer collides with a 4096d default at write time.
+- **Vector store init log shows actual provider/model/dims.** Diagnostic log line at startup now reflects the resolved configuration instead of the static placeholder, so misconfiguration is visible immediately.
+- **Tool artifact API arity + hydration docs aligned.** Doc-only follow-ups; no runtime behavior change.
+
+**Operator action:** upgrade from 0.9.0 is recommended. 0.9.0 in production with a configured non-default embedder may have written mismatched vectors; check `hypermem-status` for vector-store init line after upgrade.
+
 ## 0.9.0 - adaptive context lifecycle
 
 - **Adaptive lifecycle is now production behavior.** Compose, afterTurn, recall, trim, compaction, and eviction share the same pressure-band policy across bootstrap, warmup, steady, elevated, high, and critical states.
@@ -39,7 +48,7 @@ All notable changes to hypermem are documented here.
 
 - **Compaction fence tail preservation fixed.** The recent-tail preservation fix is included so compaction no longer drops the protected recent tail during fence advancement.
 - **`afterTurn` token count persistence fixed.** Token accounting now persists correctly after turn completion, which keeps follow-on pressure and compaction decisions honest.
-- **Registry install docs corrected and hardened.** Installation guidance now fixes the shipped `ocplatform` typo, clarifies older package behavior around missing `install:runtime`, improves `plugins.load.paths` quoting, and removes the dangerous overwrite-style `plugins.allow` example in favor of merge-safe guidance.
+- **Registry install docs corrected and hardened.** Installation guidance now fixes a shipped legacy command-token typo, clarifies older package behavior around missing `install:runtime`, improves `plugins.load.paths` quoting, and removes the dangerous overwrite-style `plugins.allow` example in favor of merge-safe guidance.
 - **Install tracks clarified.** Docs now distinguish source-clone plugin setup from older npm package behavior so first-run operators do not follow the wrong path.
 - **`zod` now ships for plugin runtime use.** The published package now includes the runtime `zod` dependency required by the HyperCompositor plugin, fixing `Cannot find module 'zod'` on package-based installs.
 

package/docs/ROADMAP.md

@@ -12,7 +12,15 @@ For shipped capabilities, see [CHANGELOG.md](../CHANGELOG.md) and [ARCHITECTURE.
 ## Current state
 
 ### Released
-- Current release: **0.8.6**
+- Current release: **0.9.0** — adaptive context lifecycle. Published 2026-04-25.
+  - Internal `main`: `8f805b8`
+  - Public `main`: `25dd469`
+  - Public tag `v0.9.0`: pushed
+  - Public CI: green (`24942512824`)
+  - GitHub Release: https://github.com/PsiClawOps/hypermem/releases/tag/v0.9.0
+  - npm at 0.9.0: `@psiclawops/hypermem`, `@psiclawops/hypercompositor`, `@psiclawops/hypermem-memory`
+  - New install validator shipped: `hypermem-doctor`
+- Previous release: **0.8.6**
 
 ### Landed on `main` after 0.8.6
 In the order work actually landed:
@@ -84,7 +92,7 @@ Final closeout work now complete:
 Rule going forward: do not reopen warm restore from historical planning notes. New warm-restore work needs a fresh defect, measurement gap, or roadmap item.
 
 ## 2. HyperMem 0.9.0 adaptive context lifecycle
-Status: **OPEN, release-candidate pending tag validation.**
+Status: **CLOSED — shipped 2026-04-25.** Public tag `v0.9.0` (`25dd469`), GitHub Release published, all three npm packages at 0.9.0. `hypermem-doctor` shipped as part of this release.
 
 The core runtime slices have landed: the pure adaptive lifecycle policy kernel, compose diagnostics wiring, afterTurn Redis gradient-cap wiring, adaptive recall breadth, adaptive eviction ordering, lifecycle telemetry, report tooling, forked-context lifecycle integration, and metadata-only topic-signal report classification. The first live telemetry baseline is populated; it shows steady/warmup behavior with zero lifecycle-band divergence, so no threshold tuning is warranted from the current evidence.
 
@@ -168,7 +176,7 @@ Phase 5 stays important, but it is not the next sprint until the higher-priority
 |---|---|---|
 | Runtime diagnostics API allowlist defect | ✅ CLOSED | Verified installed OpenClaw runtime can reach `memory-core/runtime-api.js`; re-open only with a fresh public-surface failure trace. |
 | Topic synthesis bridge defect | ✅ CLOSED | Fixed in `8b9f928`; CI `24917765384` passed. |
-| Adaptive context lifecycle (0.9.0) | 🟡 OPEN | Kernel, compose diagnostics, afterTurn gradient cap, recall breadth, eviction order, lifecycle telemetry, report tooling, forked-context integration, and topic-signal report classification are landed; vector coverage, first live lifecycle baseline, and the 0.9.0 topic-bearing compose evidence gate are closed; threshold tuning remains deferred until future live evidence warrants it. |
+| Adaptive context lifecycle (0.9.0) | ✅ SHIPPED | Released 2026-04-25 as 0.9.0. Threshold tuning remains deferred until future live evidence warrants it. |
 | Vector coverage repair gate | ✅ CLOSED | `embed-existing` now supports knowledge and eligibility-aware coverage reporting; production vectors reached facts 113/113, knowledge 85/85, episodes 30,121/30,121 eligible coverage on 2026-04-24. |
 | Contradiction-aware decay | 🟡 OPEN | Prevents stale-fact poisoning after architectural pivots. |
 | Turn DAG Phase 5 storage/perf | 🟡 OPEN | Important, but later than the items above. |
@@ -189,6 +197,7 @@ Phase 5 stays important, but it is not the next sprint until the higher-priority
 | Strict topic mode legacy NULL backfill | 🟡 DEFERRED | Wait for stable topic coverage before running the migration/backfill. |
 | ACA Step 4 retrieval stubs replace static files | 🔲 PENDING | Still relevant, but downstream of lifecycle/diagnostics stability. Do not start from older ACA notes. |
 | ACA Step 5 governance context assembly | 🔲 PENDING | Still relevant, but depends on Step 4. Do not start until Step 4 has an accepted implementation contract. |
+| Tokenjuice + HyperMem tool-result pipeline integration | 🔲 TRIAGE | OpenClaw 2026.4.24 ships `tokenjuice`, a deterministic rule-based tool-result pre-trim hook (collapses ANSI/build noise/repeated frames). It and HyperMem's size-based `tool_result_trim` both fire on tool results. Three integration concerns before fleet-wide enable: (1) **Hook ordering**: tokenjuice must run before HyperMem trim so HyperMem only collapses what tokenjuice cannot already remove deterministically. Reverse order wastes savings. (2) **Tool-artifact store**: HyperMem's L4 durable artifact store must capture the **untransformed** tool result, not the tokenjuice-trimmed one. The hook chain should pass `{ raw, transformed }` so artifacts get `raw` while message stream gets `transformed`. (3) **Telemetry**: unify `tool_result_trim_event` schema with `source: "tokenjuice" \| "hypermem"` and per-turn rollup so operators see one report. Sequencing: pilot tokenjuice standalone on one heavy-exec agent (HyperBuilder generator candidate) to measure rule-trim savings on our actual workloads before formalizing the contract. Do not write the contract before we have numbers. Surfaced 2026-04-25 by ragesaq. |
 | Codex harness compatibility for HyperMem hooks | 🔲 TRIAGE | OpenClaw is generalizing the embedded executor (PI stays default; Codex is a registered plugin harness via `agents.defaults.embeddedHarness`). When a turn runs through the Codex harness, OpenClaw owns mirror transcript + tool dispatch but Codex owns the agent loop and native compaction. Investigate before any agent moves off PI: (1) whether HyperMem's `before_prompt_build`, `before_compaction`, `after_compaction`, `before_message_write`, `llm_input`, `llm_output`, `agent_end`, `after_tool_call` hooks fire with the same timing on Codex turns; (2) collision between HyperCompositor compaction and Codex native app-server compaction (need an explicit disable on one side or a coordination contract); (3) whether the locally mirrored transcript loses any content the indexer assumes is present; (4) `subagent` `context: "fork"` behavior when parent runs on Codex (parent JSONL is mirror, not source of truth); (5) keep `openai-codex/*` provider routes (PI under the hood) distinct from `codex/*` runtime selection (Codex harness). Pilot on one non-critical agent with `runtime: "codex"`, `fallback: "pi"` once the parity gap closes; do not adopt fleet-wide before then. Surfaced 2026-04-24 by ragesaq. |
 
 ---

package/memory-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@psiclawops/hypermem-memory",
-  "version": "0.9.0",
-  "description": "HyperMem memory plugin for OpenClaw — bridges HyperMem retrieval into the memory slot",
+  "version": "0.9.1",
+  "description": "HyperMem memory plugin for OpenClaw \u2014 bridges HyperMem retrieval into the memory slot",
   "type": "module",
   "main": "dist/index.js",
   "license": "Apache-2.0",
@@ -38,7 +38,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@psiclawops/hypermem": "0.9.0"
+    "@psiclawops/hypermem": "0.9.1"
   },
   "devDependencies": {
     "openclaw": "*",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@psiclawops/hypermem",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Agent-centric memory and context composition engine for OpenClaw",
   "type": "module",
   "main": "dist/index.js",
@@ -40,6 +40,7 @@
     "validate:docs": "node scripts/validate-docs.mjs",
     "validate:config": "node scripts/validate-config-surface.mjs",
     "validate:version-parity": "node scripts/validate-version-parity.mjs",
+    "validate:public-surface": "node scripts/validate-public-surface.mjs",
     "bench:memory": "node bench/data-access-bench.mjs --iterations 1000 --warmup 50",
     "validate:doctor": "node test/doctor-cli.mjs"
   },

package/plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@psiclawops/hypercompositor",
-  "version": "0.9.0",
-  "description": "HyperCompositor — context engine plugin for OpenClaw",
+  "version": "0.9.1",
+  "description": "HyperCompositor \u2014 context engine plugin for OpenClaw",
   "type": "module",
   "main": "dist/index.js",
   "license": "Apache-2.0",
@@ -18,7 +18,7 @@
   "openclaw": {
     "plugin": {
       "id": "hypercompositor",
-      "name": "HyperCompositor — Context Engine",
+      "name": "HyperCompositor \u2014 Context Engine",
       "kind": "context-engine"
     },
     "extensions": [
@@ -38,7 +38,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@psiclawops/hypermem": "0.9.0",
+    "@psiclawops/hypermem": "0.9.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/dist/adaptive-lifecycle.d.ts

@@ -1,81 +0,0 @@
-/**
- * HyperMem 0.9.0 adaptive context lifecycle policy kernel.
- *
- * This module intentionally stays pure: it does not fetch history, mutate
- * stores, or own trimming. Runtime paths can call it to choose warming,
- * recall, trim, compaction, and eviction posture from the same pressure band
- * so 0.9.0 does not grow another independent trim brain.
- */
-export type AdaptiveLifecycleBand = 'bootstrap' | 'warmup' | 'steady' | 'elevated' | 'high' | 'critical';
-export interface AdaptiveLifecycleInput {
-    /** Tokens already resident or projected in the active context. */
-    usedTokens?: number;
-    /** Effective context budget after model-aware reserve handling. */
-    effectiveBudget?: number;
-    /** Optional precomputed pressure fraction. Overrides usedTokens/effectiveBudget. */
-    pressureFraction?: number;
-    /** Number of user turns observed in the session. */
-    userTurnCount?: number;
-    /** True when the incoming user turn explicitly starts with /new. */
-    explicitNewSession?: boolean;
-    /** Topic-shift confidence from the detector, 0..1. */
-    topicShiftConfidence?: number;
-    /** True when this context was forked from a parent OpenClaw session. */
-    forkedContext?: boolean;
-    /** Parent-session pressure observed when the fork was prepared, 0..1+. */
-    forkedParentPressureFraction?: number;
-    /** Parent-session user turns observed when the fork was prepared. */
-    forkedParentUserTurnCount?: number;
-}
-/**
- * Eviction-pipeline step labels. The order in `AdaptiveEvictionPlan.steps`
- * is the order the compose-window cluster-drop path should attempt them.
- *
- * `tool-gradient`, `oversized-artifacts`, and `stale-tool-stubs` are
- * ballast-reduction steps already implemented in the compositor; the plan
- * just records that they precede cluster drop. `topic-aware-cluster-drop`
- * and `oldest-cluster-drop` describe how the compositor's existing
- * cluster-drop pass should be ordered: topic-aware-first when the band
- * elevates, otherwise the historical newest-first/oldest-drop sweep.
- */
-export type AdaptiveEvictionStep = 'tool-gradient' | 'oversized-artifacts' | 'stale-tool-stubs' | 'topic-aware-cluster-drop' | 'oldest-cluster-drop';
-export interface AdaptiveEvictionPlan {
-    band: AdaptiveLifecycleBand;
-    steps: readonly AdaptiveEvictionStep[];
-    /** Drop inactive-topic clusters before falling back to oldest-first. */
-    preferTopicAwareDrop: boolean;
-    /** Ballast-reduction steps run before any cluster drop. Always true today. */
-    preferBallastFirst: boolean;
-}
-export interface AdaptiveLifecyclePolicy {
-    band: AdaptiveLifecycleBand;
-    pressureFraction: number;
-    pressurePct: number;
-    warmHistoryBudgetFraction: number;
-    smartRecallMultiplier: number;
-    trimSoftTarget: number;
-    compactionTargetFraction: number;
-    emitBreadcrumbPackage: boolean;
-    enableTopicCentroidEviction: boolean;
-    triggerProactiveCompaction: boolean;
-    evictionPlan: AdaptiveEvictionPlan;
-    reasons: string[];
-}
-/**
- * Pure helper: derive the eviction plan from band only. No new pressure
- * constants — every band-sensitive decision routes through the existing
- * AdaptiveLifecycleBand classification.
- *
- * - bootstrap/warmup/steady: preserve the historical eviction order.
- * - elevated: prefer topic-aware stale cluster drop before generic
- *   oldest-first cluster drop.
- * - high/critical: same plan shape as elevated. Ballast-first is already
- *   the default order in the compositor; topic-aware drop kicks in to
- *   avoid evicting active-topic recent clusters under saturation.
- */
-export declare function resolveAdaptiveEvictionPlan(band: AdaptiveLifecycleBand): AdaptiveEvictionPlan;
-/**
- * Resolve the adaptive lifecycle posture for one compose/afterTurn cycle.
- */
-export declare function resolveAdaptiveLifecyclePolicy(input?: AdaptiveLifecycleInput): AdaptiveLifecyclePolicy;
-//# sourceMappingURL=adaptive-lifecycle.d.ts.map

package/dist/adaptive-lifecycle.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adaptive-lifecycle.d.ts","sourceRoot":"","sources":["../src/adaptive-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,qBAAqB,GAC7B,WAAW,GACX,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,MAAM,GACN,UAAU,CAAC;AAEf,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,sDAAsD;IACtD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,0EAA0E;IAC1E,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,qEAAqE;IACrE,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,oBAAoB,GAC5B,eAAe,GACf,qBAAqB,GACrB,kBAAkB,GAClB,0BAA0B,GAC1B,qBAAqB,CAAC;AAE1B,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACvC,wEAAwE;IACxE,oBAAoB,EAAE,OAAO,CAAC;IAC9B,8EAA8E;IAC9E,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,yBAAyB,EAAE,MAAM,CAAC;IAClC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,2BAA2B,EAAE,OAAO,CAAC;IACrC,0BAA0B,EAAE,OAAO,CAAC;IACpC,YAAY,EAAE,oBAAoB,CAAC;IACnC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAsB7F;AAyGD;;GAEG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,GAAE,sBAA2B,GACjC,uBAAuB,CAoBzB"}

package/dist/adaptive-lifecycle.js

@@ -1,190 +0,0 @@
-/**
- * HyperMem 0.9.0 adaptive context lifecycle policy kernel.
- *
- * This module intentionally stays pure: it does not fetch history, mutate
- * stores, or own trimming. Runtime paths can call it to choose warming,
- * recall, trim, compaction, and eviction posture from the same pressure band
- * so 0.9.0 does not grow another independent trim brain.
- */
-const BASELINE_EVICTION_STEPS = Object.freeze([
-    'tool-gradient',
-    'oversized-artifacts',
-    'stale-tool-stubs',
-    'oldest-cluster-drop',
-]);
-const TOPIC_AWARE_EVICTION_STEPS = Object.freeze([
-    'tool-gradient',
-    'oversized-artifacts',
-    'stale-tool-stubs',
-    'topic-aware-cluster-drop',
-    'oldest-cluster-drop',
-]);
-/**
- * Pure helper: derive the eviction plan from band only. No new pressure
- * constants — every band-sensitive decision routes through the existing
- * AdaptiveLifecycleBand classification.
- *
- * - bootstrap/warmup/steady: preserve the historical eviction order.
- * - elevated: prefer topic-aware stale cluster drop before generic
- *   oldest-first cluster drop.
- * - high/critical: same plan shape as elevated. Ballast-first is already
- *   the default order in the compositor; topic-aware drop kicks in to
- *   avoid evicting active-topic recent clusters under saturation.
- */
-export function resolveAdaptiveEvictionPlan(band) {
-    switch (band) {
-        case 'bootstrap':
-        case 'warmup':
-        case 'steady':
-            return Object.freeze({
-                band,
-                steps: BASELINE_EVICTION_STEPS,
-                preferTopicAwareDrop: false,
-                preferBallastFirst: true,
-            });
-        case 'elevated':
-        case 'high':
-        case 'critical':
-        default:
-            return Object.freeze({
-                band,
-                steps: TOPIC_AWARE_EVICTION_STEPS,
-                preferTopicAwareDrop: true,
-                preferBallastFirst: true,
-            });
-    }
-}
-const PRESSURE_BANDS = Object.freeze({
-    steadyMax: 0.65,
-    elevatedMax: 0.75,
-    highMax: 0.85,
-});
-const WARMING_BY_BAND = Object.freeze({
-    bootstrap: 0.55,
-    warmup: 0.48,
-    steady: 0.40,
-    elevated: 0.34,
-    high: 0.28,
-    critical: 0.20,
-});
-const TRIM_TARGET_BY_BAND = Object.freeze({
-    bootstrap: 0.72,
-    warmup: 0.68,
-    steady: 0.65,
-    elevated: 0.60,
-    high: 0.54,
-    critical: 0.48,
-});
-const COMPACTION_TARGET_BY_BAND = Object.freeze({
-    bootstrap: 0.70,
-    warmup: 0.66,
-    steady: 0.62,
-    elevated: 0.56,
-    high: 0.50,
-    critical: 0.42,
-});
-function clampPressure(value) {
-    if (!Number.isFinite(value) || value < 0)
-        return 0;
-    return value;
-}
-function pressureFromInput(input) {
-    if (input.pressureFraction != null) {
-        return clampPressure(input.pressureFraction);
-    }
-    const used = Math.max(0, Math.floor(input.usedTokens ?? 0));
-    const budget = Math.max(0, Math.floor(input.effectiveBudget ?? 0));
-    if (budget <= 0)
-        return 0;
-    return clampPressure(used / budget);
-}
-function isTopicShift(input) {
-    return (input.topicShiftConfidence ?? 0) >= 0.75;
-}
-function classifyBand(input, pressure) {
-    const userTurns = Math.max(0, Math.floor(input.userTurnCount ?? 0));
-    if (input.explicitNewSession)
-        return 'bootstrap';
-    if (input.forkedContext) {
-        const parentPressure = clampPressure(input.forkedParentPressureFraction ?? pressure);
-        const parentTurns = Math.max(0, Math.floor(input.forkedParentUserTurnCount ?? 0));
-        // A forked child is not cold: it starts with inherited working context.
-        // Keep initial posture conservative and bounded to warmup/steady so a
-        // saturated parent does not immediately trigger child compaction before the
-        // child has produced its own post-fork turns. Callers should only pass this
-        // seed for the initial forked assemble.
-        if (parentTurns >= 5 || parentPressure >= 0.35)
-            return 'steady';
-        return 'warmup';
-    }
-    if (userTurns === 0)
-        return 'bootstrap';
-    if (userTurns <= 4 && pressure < PRESSURE_BANDS.elevatedMax)
-        return 'warmup';
-    if (pressure < PRESSURE_BANDS.steadyMax)
-        return 'steady';
-    if (pressure < PRESSURE_BANDS.elevatedMax)
-        return 'elevated';
-    if (pressure < PRESSURE_BANDS.highMax)
-        return 'high';
-    return 'critical';
-}
-function smartRecallMultiplier(input, band) {
-    if (input.explicitNewSession || isTopicShift(input))
-        return 1.5;
-    if (band === 'bootstrap' || band === 'warmup')
-        return 1.25;
-    if (band === 'high')
-        return 0.85;
-    if (band === 'critical')
-        return 0.65;
-    return 1.0;
-}
-function reasonsFor(input, band, pressure) {
-    const reasons = [`band:${band}`, `pressure:${Math.round(pressure * 100)}%`];
-    const turns = Math.max(0, Math.floor(input.userTurnCount ?? 0));
-    if (input.explicitNewSession)
-        reasons.push('explicit-new-session');
-    if (input.forkedContext) {
-        reasons.push('forked-context');
-        if (input.forkedParentPressureFraction != null) {
-            reasons.push(`forked-parent-pressure:${Math.round(clampPressure(input.forkedParentPressureFraction) * 100)}%`);
-        }
-        if (input.forkedParentUserTurnCount != null) {
-            reasons.push(`forked-parent-turns:${Math.max(0, Math.floor(input.forkedParentUserTurnCount))}`);
-        }
-    }
-    if (turns === 0)
-        reasons.push('cold-start');
-    if (turns > 0 && turns <= 4)
-        reasons.push(`early-session:${turns}`);
-    if (isTopicShift(input))
-        reasons.push(`topic-shift:${(input.topicShiftConfidence ?? 0).toFixed(2)}`);
-    if (band === 'high' || band === 'critical')
-        reasons.push('pressure-gated-recall');
-    return reasons;
-}
-/**
- * Resolve the adaptive lifecycle posture for one compose/afterTurn cycle.
- */
-export function resolveAdaptiveLifecyclePolicy(input = {}) {
-    const pressureFraction = pressureFromInput(input);
-    const band = classifyBand(input, pressureFraction);
-    const pressurePct = Math.round(pressureFraction * 100);
-    const triggerProactiveCompaction = band === 'high' || band === 'critical';
-    return Object.freeze({
-        band,
-        pressureFraction,
-        pressurePct,
-        warmHistoryBudgetFraction: WARMING_BY_BAND[band],
-        smartRecallMultiplier: smartRecallMultiplier(input, band),
-        trimSoftTarget: TRIM_TARGET_BY_BAND[band],
-        compactionTargetFraction: COMPACTION_TARGET_BY_BAND[band],
-        emitBreadcrumbPackage: Boolean(input.explicitNewSession || band === 'bootstrap'),
-        enableTopicCentroidEviction: band === 'elevated' || triggerProactiveCompaction,
-        triggerProactiveCompaction,
-        evictionPlan: resolveAdaptiveEvictionPlan(band),
-        reasons: reasonsFor(input, band, pressureFraction),
-    });
-}
-//# sourceMappingURL=adaptive-lifecycle.js.map

package/dist/background-indexer.d.ts

@@ -1,161 +0,0 @@
-/**
- * hypermem Background Indexer
- *
- * Processes message history to extract structured knowledge:
- *   - Facts: atomic pieces of learned information
- *   - Episodes: significant events worth remembering
- *   - Topics: conversation threads and their lifecycle
- *   - Knowledge: durable structured entries (domain + key)
- *
- * Runs as a periodic background task, processing unindexed messages
- * in batches. Each batch is scored, classified, and stored in L4 (library.db).
- *
- * Design principles:
- *   - No LLM dependency: extraction uses pattern matching + heuristics
- *   - Idempotent: tracks watermarks per agent to avoid reprocessing
- *   - Bounded: processes N messages per tick to avoid blocking
- *   - Observable: logs extraction stats for monitoring
- */
-import type { DatabaseSync } from 'node:sqlite';
-import type { IndexerConfig, SessionCursor, MaintenanceTickDiagnostics } from './types.js';
-import { type DreamerConfig } from './dreaming-promoter.js';
-import { type ContradictionResolutionPolicy } from './contradiction-resolution-policy.js';
-import type { VectorStore } from './vector-store.js';
-export interface IndexerStats {
-    agentId: string;
-    messagesProcessed: number;
-    factsExtracted: number;
-    episodesRecorded: number;
-    topicsUpdated: number;
-    knowledgeUpserted: number;
-    /** Number of superseded fact vectors tombstoned from the vector index this tick. */
-    tombstoned: number;
-    /** Number of contradiction audits recorded for review this tick. */
-    contradictionAuditsLogged: number;
-    /** Number of old facts auto-superseded via contradiction policy this tick. */
-    contradictionsAutoSuperseded: number;
-    /** Number of old facts auto-invalidated via contradiction policy this tick. */
-    contradictionsAutoInvalidated: number;
-    elapsedMs: number;
-    /** Number of messages that were post-cursor (unseen by model, high-signal priority). */
-    postCursorMessages: number;
-}
-/**
- * Optional callback to fetch the session cursor for an agent+session.
- * When provided, the indexer uses the cursor to prioritize unseen messages.
- * The cursor boundary separates "model has seen this" from "new since last compose".
- */
-export type CursorFetcher = (agentId: string, sessionKey: string) => Promise<SessionCursor | null>;
-export interface WatermarkState {
-    agentId: string;
-    lastMessageId: number;
-    lastRunAt: string;
-}
-export declare class BackgroundIndexer {
-    private getMessageDb?;
-    private getLibraryDb?;
-    private listAgents?;
-    private getCursor?;
-    private readonly config;
-    private readonly dreamerConfig;
-    private readonly globalWritePolicy;
-    private readonly contradictionPolicy;
-    private intervalHandle;
-    private running;
-    private vectorStore;
-    private synthesizer;
-    private tickCount;
-    /** Circuit breaker: consecutive tick failure count. Resets on success. */
-    private consecutiveFailures;
-    /** True when the indexer is running in backoff mode due to repeated failures. */
-    private inBackoff;
-    private readonly _conversationLastProcessed;
-    lastMaintenanceDiagnostics: MaintenanceTickDiagnostics | null;
-    constructor(config?: Partial<IndexerConfig>, getMessageDb?: ((agentId: string) => DatabaseSync) | undefined, getLibraryDb?: (() => DatabaseSync) | undefined, listAgents?: (() => string[]) | undefined, getCursor?: CursorFetcher | undefined, dreamerConfig?: Partial<DreamerConfig>, globalWritePolicy?: import('./types.js').GlobalWritePolicy, contradictionPolicy?: ContradictionResolutionPolicy);
-    /**
-     * Set the vector store for embedding new facts/episodes at index time.
-     * Optional — if not set, indexer runs without embedding (FTS5-only mode).
-     */
-    setVectorStore(vs: VectorStore): void;
-    /**
-     * Start periodic indexing.
-     */
-    start(): void;
-    /**
-     * Circuit breaker for tick failures.
-     *
-     * - Tracks consecutive failures.
-     * - After 3 failures, logs actionable recovery guidance once, then switches
-     *   the indexer to 10× backoff interval so it stops spamming the log.
-     * - On the next successful tick, resets state and restores normal interval.
-     */
-    private _handleTickError;
-    /**
-     * Reset the circuit breaker and restore normal interval after a successful tick.
-     * Called at the end of a successful tick().
-     */
-    private _resetCircuitBreaker;
-    /**
-     * Stop periodic indexing.
-     */
-    stop(): void;
-    /**
-     * Run one indexing pass across all agents.
-     */
-    tick(): Promise<IndexerStats[]>;
-    /**
-     * Process a single agent's unindexed messages.
-     *
-     * When a cursor fetcher is available, messages are split into two tiers:
-     *   - Post-cursor (id > cursor.lastSentId): "unseen" by the model, high-signal priority
-     *   - Pre-cursor (id <= cursor.lastSentId): already in the model's context window, lower priority
-     * Post-cursor messages are processed first. This ensures the indexer prioritizes
-     * content the model hasn't seen yet — decisions, incidents, and discoveries that
-     * happened between context windows.
-     */
-    private processAgent;
-    /**
-     * Fetch unindexed messages for an agent.
-     */
-    private getUnindexedMessages;
-    /**
-     * Get the session key for a conversation ID.
-     */
-    private getSessionKeyForMessage;
-    /**
-     * Get the indexing watermark for an agent.
-     */
-    private getWatermark;
-    /**
-     * Set the indexing watermark for an agent.
-     */
-    private setWatermark;
-    /**
-     * Apply time-based decay to facts.
-     * Increases decay_score for older facts, making them less relevant.
-     */
-    private applyDecay;
-    /**
-     * Parse a duration string like "24h", "7d" into seconds.
-     */
-    private parseDuration;
-    /**
-     * One-time backfill: embed episodes with sig>=0.5 that were missed by the
-     * old >=0.7 vectorization threshold.
-     *
-     * Gated by a system_state flag 'indexer:episode_backfill_v1' so it runs
-     * exactly once even across gateway restarts. Safe to re-run manually
-     * (delete the flag row first) if re-backfill is ever needed.
-     */
-    backfillEpisodeVectors(): Promise<void>;
-    /**
-     * Get current watermarks for all agents.
-     */
-    getWatermarks(libraryDb: DatabaseSync): WatermarkState[];
-}
-/**
- * Create and start a background indexer connected to hypermem databases.
- * Used by the hook or a standalone daemon.
- */
-export declare function createIndexer(getMessageDb: (agentId: string) => DatabaseSync, getLibraryDb: () => DatabaseSync, listAgents: () => string[], config?: Partial<IndexerConfig>, getCursor?: CursorFetcher, vectorStore?: VectorStore, dreamerConfig?: Partial<DreamerConfig>, globalWritePolicy?: import('./types.js').GlobalWritePolicy): BackgroundIndexer;
-//# sourceMappingURL=background-indexer.d.ts.map

package/dist/background-indexer.d.ts.map

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