@psiclawops/hypermem 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -2,7 +2,14 @@
 
 All notable changes to hypermem are documented here.
 
-## 0.9.1 - plugin singleton + memory-plugin config patch
+## 0.9.2 - 0.9.1 republish + publish-path hardening
+
+- **0.9.1 was a broken publish.** The npm tarballs for `@psiclawops/hypermem@0.9.1`, `@psiclawops/hypercompositor@0.9.1`, and `@psiclawops/hypermem-memory@0.9.1` shipped without `dist/`, so `import` against the registry artifact fails with `ERR_MODULE_NOT_FOUND`. **Skip 0.9.1.** Operators currently on 0.9.1 should upgrade to 0.9.2.
+- **Same code intent as 0.9.1.** Plugin singleton registry on `globalThis`, memory plugin loads user config, vector-store init log shows resolved provider/model/dims, tool artifact API arity + hydration docs aligned. (See 0.9.1 entry below for detail.)
+- **`prepublishOnly` and `prepack` hooks added** to root, plugin/, and memory-plugin/ `package.json`. `npm publish` now refuses to ship without first running `npm run build`. The 0.9.1 packaging defect (gitignored `dist/` + no build hook → empty tarball) cannot recur.
+- **0.9.1 deprecated on the registry** for all three packages, with a pointer to 0.9.2.
+
+## 0.9.1 - plugin singleton + memory-plugin config patch (BROKEN PUBLISH — use 0.9.2)
 
 - **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.

package/INSTALL.md

@@ -51,7 +51,7 @@ No gateway, plugin load path, or OpenClaw config is required in library mode. Op
 
 This guide is deliberately declarative. Follow the steps in order and verify each install state before moving on.
 
-> **Release note:** if the npm package you installed does not contain `hypermem-install`, `install:runtime`, and `hypermem-model-audit`, you are on an older public release. Use the source-clone path in this guide or wait for the next npm release.
+> **Release note:** current releases ship `hypermem-install`, `install:runtime`, and `hypermem-model-audit`. If your installed package does not contain them, upgrade to the latest `@psiclawops/hypermem` before following this guide.
 
 ```bash
 npm install @psiclawops/hypermem
@@ -529,7 +529,7 @@ npm install
 npm run build
 ```
 
-Build both plugins, then install the runtime payload into 's durable plugin directory:
+Build both plugins, then install the runtime payload into OpenClaw's durable plugin directory:
 
 ```bash
 npm --prefix plugin install && npm --prefix plugin run build
@@ -1071,3 +1071,12 @@ openclaw gateway restart
 ---
 
 _Questions or issues: file against [the repo](https://github.com/PsiClawOps/hypermem) or ask in `#hypermem`._
+
+### Preview installer actions
+
+Run the installer with `--dry-run` to print package install, runtime staging, config, activation, and verification steps without installing, staging, or writing config:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/PsiClawOps/hypermem/main/install.sh | bash -s -- --dry-run
+```
+

package/README.md

@@ -20,13 +20,13 @@ Or via the shell installer:
 curl -fsSL https://raw.githubusercontent.com/PsiClawOps/hypermem/main/install.sh | bash
 ```
 
-Or install manually via `npm install @psiclawops/hypermem` - see [Installation](#installation) for the full declarative plugin path, verification checkpoints, and setup variants.
+Or install manually via `npm install @psiclawops/hypermem`: see [Installation](#installation) for the full declarative plugin path, verification checkpoints, and setup variants.
 
 Release operators should also read:
 
-- [INSTALL.md](./INSTALL.md) - canonical fresh install and upgrade guide
-- [docs/INTEGRATION_VALIDATION.md](./docs/INTEGRATION_VALIDATION.md) - end-to-end integration validation contract
-- [docs/DIAGNOSTICS.md](./docs/DIAGNOSTICS.md) - status, model audit, compose, trim, and release diagnostics
+- [INSTALL.md](./INSTALL.md): canonical fresh install and upgrade guide
+- [docs/INTEGRATION_VALIDATION.md](./docs/INTEGRATION_VALIDATION.md): end-to-end integration validation contract
+- [docs/DIAGNOSTICS.md](./docs/DIAGNOSTICS.md): status, model audit, compose, trim, and release diagnostics
 
 A successful `hypermem-install` only stages the runtime. HyperMem is active only after OpenClaw config is wired, the gateway restarts, and logs show compose activity.
 
@@ -57,7 +57,7 @@ The difference is not intelligence. It is prompt access. Three failure modes fol
 
 ## What OpenClaw provides today
 
-OpenClaw already gives agents a stronger baseline than most stacks. It injects structured guidance into every session:
+OpenClaw already gives agents a strong baseline. It injects structured guidance into every session:
 
 | File | What it contributes | Survives session restart? |
 |---|---|---|
@@ -78,16 +78,16 @@ OpenClaw gives agents a strong starting shape: identity files, user guidance, ta
 
 hypermem closes that gap with four SQLite-backed memory layers that stay local, run in-process, and remain queryable across sessions. No external database service. No retrieval stack to babysit.
 
-| Layer | What it holds | Speed |
+| Layer | What it holds | Representative local read |
 |---|---|---|
-| **L1 SQLite `:memory:`** | What the agent needs right now. Identity, recent history, active state. | 0.08ms |
-| **L2 History** | Every conversation, queryable and concurrent-safe. Per-agent. | 0.13ms |
-| **L3 Semantic** | Finds related content even when the words don't match. | 0.29ms |
-| **L4 Knowledge** | Facts, wiki pages, episodes, preferences. Shared across agents. | 0.09ms |
+| **L1 SQLite `:memory:`** | What the agent needs right now. Identity, recent history, active state. | L1 slot GET: 0.08ms avg |
+| **L2 History** | Every conversation, queryable and concurrent-safe. Per-agent. | L2 history window: 0.13ms avg |
+| **L3 Semantic** | Finds related content even when the words don't match. | async/cached; provider-dependent. See [Speed](#speed) and [Diagnostics](./docs/DIAGNOSTICS.md#memory-access-benchmark). |
+| **L4 Knowledge** | Facts, wiki pages, episodes, preferences. Shared across agents. | L4 knowledge query: 0.09ms avg |
 
 Durable context stays in SQLite and remains queryable across session boundaries. The retry logic decision from last week, the deployment preferences from last month, and the architecture choices from day one can be pulled back in when they matter.
 
-That changes OpenClaw in a few concrete ways. Starts are warm instead of blank because recent history, ranked facts, active topics, and cached semantic state are loaded before the first turn. Recall survives wording drift because FTS5, sqlite-vec, RRF fusion, and an optional reranker can recover the same idea through different phrasing. Time-aware facts can answer “last week” and “before the release” as retrieval problems instead of vague prompt guessing. Shared knowledge stops living in one agent’s scratchpad because `library.db` holds facts, docs, episodes, preferences, fleet state, and output standards with visibility controls.
+That changes OpenClaw in a few concrete ways. Starts are warm instead of blank because recent history, ranked facts, active topics, and cached semantic state are loaded before the first turn. Recall survives wording drift because FTS5, sqlite-vec, RRF fusion, and an optional reranker can recover the same idea through different phrasing. Time-aware facts can answer "last week" and "before the release" as retrieval problems instead of vague prompt guessing. Shared knowledge stops living in one agent’s scratchpad because `library.db` holds facts, docs, episodes, preferences, fleet state, and output standards with visibility controls.
 
 ---
 
@@ -189,11 +189,11 @@ Behavior standards define how your agents write. Anti-sycophancy rules prevent f
 
 ### Model adaptation
 
-Different models have different default behaviors. GPT-5.4 tends toward 2x verbosity and long lists. Claude Opus defaults to hedging and preambles. Gemini produces bulleted summaries where prose would be more direct. Model adaptation corrects for these tendencies per model.
+Different providers and model families have different default answer shapes. Model adaptation applies operator-defined output standards per model so those defaults do not leak into every response.
 
 Adaptation entries are stored in the `model_output_directives` table and matched by model ID using exact match, then glob pattern (longest wins), then wildcard fallback. Each entry contains:
 
-- **Calibration:** known model tendencies and specific adjustments (e.g., "2x verbosity: cut first drafts in half")
+- **Calibration:** known model tendencies and specific adjustments (e.g., "prefer concise first drafts")
 - **Corrections:** hard/medium/soft severity rules applied in order (e.g., "No preamble before the answer")
 - **Task overrides:** per-task-type adjustments
 
@@ -208,7 +208,7 @@ The example below shows the intended effect of `hyperformProfile: "light"`. hype
 ```
 Prompt: "How should I size my context window budget for a long-running agent session?"
 
-WITHOUT hyperform shaping (GPT-5.4 default):
+WITHOUT hyperform shaping (generic verbose default):
 Here are the key factors to consider when sizing your context window budget:
 
 **1. Session depth**
@@ -276,7 +276,7 @@ Reference run, production database: 5,104 facts, 28,441 episodes, 847 knowledge
 | Operation | avg | p50 | p95 |
 |---|---|---|---|
 | L1 slot GET (SQLite in-memory) | 0.08ms | 0.07ms | 0.13ms |
-| L1 history window (100 messages) | 0.13ms | 0.11ms | 0.19ms |
+| L2 history window (100 messages) | 0.13ms | 0.11ms | 0.19ms |
 | L4 facts (top-28, confidence × decay) | 0.28ms | 0.26ms | 0.36ms |
 | L4 facts + agentId filter | 0.31ms | 0.29ms | 0.40ms |
 | L4 FTS5 keyword search | 0.06ms | 0.05ms | 0.08ms |
@@ -357,13 +357,13 @@ Facts are ranked by `confidence × recencyDecay`, where decay is exponential wit
        │
   topic detection ──► scope retrieval to active thread
        │
-  ┌────┴───────────────────────────────────────────────┐
-  │              query 4 layers (parallel)             │
-  │                                                    │
-  │  L1 in-memory  L2 History   L3 Vectors  L4 Library │
-  │  hot state    durable       semantic    facts/wiki │
-  │  0.1ms        0.16ms        0.29ms      0.08ms     │
-  └────┬───────────────────────────────────────────────┘
+  ┌────┴────────────────────────────────────────────────────────────────┐
+  │                 query 4 layers (parallel)                          │
+  │                                                                    │
+  │  L1 in-memory  L2 History        L3 Vectors        L4 Library      │
+  │  hot state     durable history   semantic recall   facts/wiki      │
+  │  0.08ms avg    0.13ms avg        async/cached      0.09ms avg      │
+  └────┬────────────────────────────────────────────────────────────────┘
        │
   budget allocator ──► 10 slots, fixed token cap
        │
@@ -386,7 +386,7 @@ Slot-level budget allocation is shown in the [hypercompositor diagram](#what-the
 
 ## Requirements
 
-**Current release: hypermem 0.9.0.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
+**Current release: hypermem 0.9.2.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
 
 | Requirement | Version | Notes |
 |---|---|---|
@@ -398,7 +398,7 @@ SQLite is a library, not a service. All four layers run in-process with no exter
 **Runtime version constants** (importable from the package):
 ```typescript
 import {
-  ENGINE_VERSION,        // '0.9.0'
+  ENGINE_VERSION,        // '0.9.2'
   MIN_NODE_VERSION,      // '22.0.0'
   SQLITE_VEC_VERSION,    // '0.1.9'
   MAIN_SCHEMA_VERSION,   // 10 (messages.db)

package/dist/adaptive-lifecycle.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,190 @@
+/**
+ * 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

@@ -0,0 +1,161 @@
+/**
+ * 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

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