@psiclawops/hypermem 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to hypermem are documented here.
 
+## 0.9.4 - 2026-04-28
+
+- **Recall surface re-enriched.** Bootstrap, warmup, and steady lifecycle bands now carry larger warming fractions, `/new` and topic-shift recall surge harder, and topic-bearing warmup avoids heartbeat/small-talk decay.
+- **Adjacency-aware preservation added.** Hybrid retrieval boosts recent antecedents while filtering heartbeat/system noise, and compose eviction guards the literal antecedent under non-critical pressure.
+- **Install path hardened.** `hypermem-install` ships the doctor, bench, and default config artifacts, writes `~/.openclaw/hypermem/config.json` only when missing, probes the default Ollama embedder, preserves existing config, supports CI-safe flags, and rejects unknown options.
+- **Fresh-install smoke gate added.** `release-gate-internal/fresh-install-smoke.sh` packs the npm artifact, installs it in the PsiClawOps Docker test image without a source mount, verifies graceful no-tools failure, verifies skip-mode staging, and proves existing config is not overwritten.
+- **Installer failure artifacts captured.** Failed smoke runs now preserve logs, generated configs, package metadata, the packed tarball, and container `/tmp` inventories under `.artifacts/fresh-install-smoke/` for postmortem reuse.
+
+## 0.9.3 - OpenClaw 2026.4.26 compatibility hardening
+
+- **Plugin manifests declare runtime config schema.** HyperCompositor and HyperMem memory manifests now expose the supported config surface for OpenClaw 2026.4.26 registry/config validation.
+- **Install and doctor flow aligned with persisted plugin registry.** Operator guidance and `hypermem-doctor` now include registry refresh, doctor repair, and plugin-list verification steps.
+- **Native compaction collision guard added.** `hypermem-doctor` warns when `agents.defaults.compaction.maxActiveTranscriptBytes` is set; HyperMem deployments should leave it unset so HyperMem remains the single trim/compose pressure owner.
+- **Embedding query/document asymmetry supported.** HyperMem config now supports query/document input types and prefixes, with defaults for `nomic-embed-text`, `qwen3-embedding`, and `mxbai-embed-large`.
+- **Forked subagent warm-start repair.** `prepareSubagentSpawn()` falls back to durable runtime history when the hot cache is empty, so forked children inherit parent working context instead of silently starting cold.
+
 ## 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.

package/INSTALL.md

@@ -5,17 +5,17 @@ This is the canonical install procedure. Keep README shorter and point operators
 ## Prerequisites
 
 - **Node.js 22+** (uses built-in `node:sqlite`)
-- **OpenClaw** must already be installed, onboarded, and running. HyperMem is a plugin for an existing OpenClaw deployment -- it does not bootstrap OpenClaw itself. If you have never run `openclaw gateway start` or completed OpenClaw onboarding, do that first. The HyperMem install guide picks up after OpenClaw is operational.
+- **OpenClaw** must already be installed, onboarded, and running. HyperMem is a plugin for an existing OpenClaw deployment -- it does not bootstrap OpenClaw itself. If you have never run `openclaw daemon start` or completed OpenClaw onboarding, do that first. The HyperMem install guide picks up after OpenClaw is operational.
 - **Disk space:** allow at least 2 GB free. Plugin builds pull OpenClaw as a dev dependency.
 
 **Verify before starting:**
 
 ```bash
-openclaw gateway status    # should show "running" or "ready"
+openclaw daemon status    # should show "running" or "ready"
 openclaw config get gateway # should return gateway config, not an error
 ```
 
-If `gateway status` shows "disabled" or "not configured", complete OpenClaw onboarding first. `openclaw gateway restart` only works when the gateway service is already set up. On a brand-new OpenClaw install that has never been started, you need `openclaw gateway start` (or the full onboarding flow) before installing plugins.
+If `gateway status` shows "disabled" or "not configured", complete OpenClaw onboarding first. `openclaw daemon restart` only works when the gateway service is already set up. On a brand-new OpenClaw install that has never been started, you need `openclaw daemon start` (or the full onboarding flow) before installing plugins.
 
 ## Non-OpenClaw usage
 
@@ -51,14 +51,16 @@ 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
 npx hypermem-install
 ```
 
-`hypermem-install` stages the plugin runtime into `~/.openclaw/plugins/hypermem`. It does **not** modify your OpenClaw config and does **not** restart the gateway. That means a successful `npx hypermem-install` is **not** a completed install. It is only a completed staging step.
+`hypermem-install` stages the plugin runtime into `~/.openclaw/plugins/hypermem` and writes `~/.openclaw/hypermem/config.json` only if that file does not already exist. It does **not** modify your OpenClaw config and does **not** restart the gateway. That means a successful `npx hypermem-install` is **not** a completed install. It is only a completed staging step.
+
+For local release validation, use `npm run install:runtime:packed` from the repo. That command builds an npm tarball, installs that tarball into a temporary app, and stages the runtime from the installed package. Do not validate production behavior from a repo symlink or copied working-tree files.
 
 The shell installer is now a thin npm-first wrapper around this same path:
 
@@ -66,44 +68,28 @@ The shell installer is now a thin npm-first wrapper around this same path:
 curl -fsSL https://raw.githubusercontent.com/PsiClawOps/hypermem/main/install.sh | bash
 ```
 
-It installs the npm package into `~/.hypermem`, backs up any existing staged runtime when confirmed, stages the runtime with `hypermem-install`, writes a lightweight starter config only if no config exists, and prints merge-safe OpenClaw activation commands. It does not edit OpenClaw config and does not restart the gateway.
+It installs the npm package into `~/.hypermem`, backs up any existing staged runtime when confirmed, stages the runtime with `hypermem-install`, writes the recall-friendly starter config only if no config exists, and prints merge-safe OpenClaw activation commands. It does not edit OpenClaw config and does not restart the gateway.
 
 Release validation details live in [docs/INTEGRATION_VALIDATION.md](./docs/INTEGRATION_VALIDATION.md). Diagnostic surfaces live in [docs/DIAGNOSTICS.md](./docs/DIAGNOSTICS.md).
 
-> **Prerequisites:** OpenClaw must be installed and onboarded. Run `openclaw gateway status` to confirm. If the gateway is not configured, complete OpenClaw setup first.
+> **Prerequisites:** OpenClaw must be installed and onboarded. Run `openclaw daemon status` to confirm. If the gateway is not configured, complete OpenClaw setup first.
 >
 > **Config merge warning:** if you already have values in `plugins.load.paths` or `plugins.allow`, merge them instead of overwriting blindly.
 
-Create the config directory and write the current recommended fresh-install starter config. This does 2 things:
+`hypermem-install` creates the current recommended starter config automatically when `~/.openclaw/hypermem/config.json` is missing. The shipped starter config is recall-friendly standard mode:
+
+- `embedding.provider: "ollama"` with `nomic-embed-text`
+- `warmHistoryBudgetFraction: 0.45`
+- standard fact, keystone, and history caps
 
-1. sets `embedding.provider` to `none` so a clean install does not try to use Ollama by default
-2. applies the current recommended lean compositor settings so fresh installs start from the same OpenClaw and HyperMem guidance we want operators to use
+If Ollama is not running or `nomic-embed-text` is not installed, `hypermem-install` fails with a remediation block instead of silently staging a degraded semantic-recall install. For CI, container practice, or intentional FTS-only installs, either run:
 
 ```bash
-mkdir -p ~/.openclaw/hypermem
-cat > ~/.openclaw/hypermem/config.json <<'JSON'
-{
-  "embedding": {
-    "provider": "none"
-  },
-  "compositor": {
-    "budgetFraction": 0.55,
-    "contextWindowReserve": 0.25,
-    "targetBudgetFraction": 0.50,
-    "warmHistoryBudgetFraction": 0.27,
-    "maxFacts": 25,
-    "maxHistoryMessages": 500,
-    "maxCrossSessionContext": 4000,
-    "maxRecentToolPairs": 3,
-    "maxProseToolPairs": 10,
-    "keystoneHistoryFraction": 0.15,
-    "keystoneMaxMessages": 12,
-    "wikiTokenCap": 500
-  }
-}
-JSON
+npx hypermem-install --skip-embedding-check
 ```
 
+or pre-create `~/.openclaw/hypermem/config.json` with `{"embedding":{"provider":"none"}}` before running the installer. Existing config files are preserved unchanged.
+
 If you want a lighter or richer memory profile later, adjust from this baseline using the tuning guidance below instead of starting from the older code defaults.
 
 ### Install states
@@ -141,6 +127,8 @@ openclaw config set plugins.load.paths "$HYPERMEM_PATHS" --strict-json
 # Set the context engine and memory slots:
 openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
+openclaw plugins registry --refresh
+openclaw doctor --fix --yes
 
 # Only set plugins.allow if your OpenClaw config already uses an allowlist.
 # If `openclaw config get plugins.allow` returns null, empty, or unset, skip this step.
@@ -153,7 +141,7 @@ openclaw config set plugins.allow '["existing-plugin","hypercompositor","hyperme
 **Step 3: Restart.**
 
 ```bash
-openclaw gateway restart
+openclaw daemon restart
 ```
 
 OpenClaw loads the plugin runtime from `~/.openclaw/plugins/hypermem/`.
@@ -231,7 +219,7 @@ Upgrades preserve the HyperMem data directory and existing config. The runtime s
 cp -a ~/.openclaw/plugins/hypermem ~/.openclaw/plugins/hypermem.backup.$(date +%Y%m%d-%H%M%S) 2>/dev/null || true
 npm install @psiclawops/hypermem@latest
 npx hypermem-install
-openclaw gateway restart
+openclaw daemon restart
 ```
 
 Then validate:
@@ -256,7 +244,7 @@ Rollback disables HyperMem without deleting data:
 ```bash
 openclaw config set plugins.slots.contextEngine legacy
 openclaw config set plugins.slots.memory none
-openclaw gateway restart
+openclaw daemon restart
 ```
 
 ---
@@ -529,7 +517,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
@@ -561,6 +549,8 @@ openclaw config set plugins.load.paths "$HYPERMEM_PATHS" --strict-json
 # Set the context engine and memory slots:
 openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
+openclaw plugins registry --refresh
+openclaw doctor --fix --yes
 
 # Only set plugins.allow if your OpenClaw config already uses an allowlist.
 # If it returns an array, append the HyperMem plugin ids to that existing array.
@@ -574,7 +564,7 @@ openclaw config set plugins.allow '["existing-plugin","hypercompositor","hyperme
 See [Embedding Providers](#embedding-providers) above.
 
 - **Lightweight (no embedder):** create `~/.openclaw/hypermem/config.json` with `{"embedding":{"provider":"none"}}`. The Quick Start block above already does this. Without this file, the default provider is `ollama` and you'll see a non-fatal init warning if Ollama isn't running.
-- **Local:** `ollama pull nomic-embed-text`. No config file needed (Ollama is the default).
+- **Local:** `ollama pull nomic-embed-text`. No config file needed (Ollama is the default). HyperMem applies retrieval query/document prefixes for supported Ollama embedders (`nomic-embed-text`, `qwen3-embedding`, `mxbai-embed-large`) unless `queryPrefix` / `documentPrefix` are set explicitly.
 - **Hosted/Gemini:** create `~/.openclaw/hypermem/config.json` with the provider config block from the relevant section above.
 
 ### Step 4 — Restart and verify
@@ -582,7 +572,7 @@ See [Embedding Providers](#embedding-providers) above.
 Do not start tuning before this section passes. If HyperMem is not loaded and composing, the next problem is installation, not tuning.
 
 ```bash
-openclaw gateway restart
+openclaw daemon restart
 ```
 
 > **If restart reports the gateway is disabled or not configured:** you need to complete OpenClaw onboarding before this step. See [Prerequisites](#prerequisites). `gateway restart` only works on an already-running gateway.
@@ -593,7 +583,7 @@ Send a message to any agent, then check:
 openclaw logs --limit 50 | grep hypermem
 ```
 
-> **If `openclaw logs` fails with an auth or token error:** the gateway API requires authentication. Run `openclaw gateway status` to confirm the gateway is running and accessible. If the gateway is running but logs fail, check `openclaw config get gateway.token` and ensure your shell session has the correct auth context.
+> **If `openclaw logs` fails with an auth or token error:** the gateway API requires authentication. Run `openclaw daemon status` to confirm the gateway is running and accessible. If the gateway is running but logs fail, check `openclaw config get gateway.token` and ensure your shell session has the correct auth context.
 
 Expected:
 ```
@@ -678,7 +668,7 @@ architect: 'infrastructure',
 ```bash
 npm run build
 npm --prefix plugin run build
-openclaw gateway restart
+openclaw daemon restart
 ```
 
 Agents not listed in `AGENT_DOMAIN_MAP` default to domain `'general'`, which is fine for most setups. The org registry only matters if you use cross-agent memory visibility (org-scoped or council-scoped facts). If all your facts are agent-private or fleet-wide, you can skip the org structure entirely.
@@ -696,7 +686,7 @@ npm install
 npm run build
 npm --prefix plugin install && npm --prefix plugin run build
 npm --prefix memory-plugin install && npm --prefix memory-plugin run build
-openclaw gateway restart
+openclaw daemon restart
 ```
 
 What changed on the path from 0.5.x to current:
@@ -775,9 +765,11 @@ openclaw config set agents.defaults.compaction.reserveTokens 16384 --strict-json
 openclaw config set agents.defaults.compaction.keepRecentTokens 6000 --strict-json
 openclaw config set agents.defaults.compaction.reserveTokensFloor 15000 --strict-json
 openclaw config set agents.defaults.compaction.maxHistoryShare 0.65 --strict-json
+# Recommended for HyperMem: leave OpenClaw transcript byte rotation unset.
+openclaw config unset agents.defaults.compaction.maxActiveTranscriptBytes
 ```
 
-This reserves 16k tokens for reply generation. HyperMem's own pressure system (afterTurn at 80%, nuclear at 85%) fires first in normal operation. OpenClaw's safeguard catches edge cases.
+This reserves 16k tokens for reply generation. HyperMem's own pressure system (afterTurn at 80%, nuclear at 85%) fires first in normal operation. OpenClaw's safeguard catches edge cases. Leave `agents.defaults.compaction.maxActiveTranscriptBytes` unset while HyperMem owns context pressure; native transcript byte rotation can evict transcript spans before HyperMem's fences and repair gates see them.
 
 ### LLM idle timeout
 
@@ -824,41 +816,52 @@ Resolution order is: (1) `plugins.entries.hypercompositor.config` in `openclaw.j
 
 These settings live in `~/.openclaw/hypermem/config.json` under the `compositor` key. All fields are optional — omit any knob to get the code-level default. Gateway restart required after changes.
 
-The recommended starting config for a standard single-agent deployment is intentionally lean on turn-1 warming. Semantic recall and fact triggers fire against each incoming message, so topic-relevant context surfaces as the conversation takes shape. This produces a steadier pressure profile than aggressive pre-loading and avoids the warm→trim→compact cycling you see when every session starts near the top of the budget.
+The recommended starting config for a standard single-agent deployment is the same recall-friendly profile shipped in `assets/default-config.json` and written by `hypermem-install` when no config exists. It keeps semantic recall active, protects topic-bearing warm context, boosts recent antecedents, and guards the literal antecedent of the current user turn under non-critical pressure.
+
+Key 0.9.4 defaults:
 
 ```json
 {
+  "embedding": {
+    "provider": "ollama",
+    "model": "nomic-embed-text",
+    "dims": 768,
+    "dimensions": 768
+  },
   "compositor": {
-    "budgetFraction": 0.55,
+    "turnBudget": {
+      "budgetFraction": 0.6,
+      "minContextFraction": 0.18
+    },
+    "warming": {
+      "protectedFloorEnabled": true,
+      "shapedWarmupDecay": true
+    },
+    "adjacency": {
+      "enabled": true,
+      "boostMultiplier": 1.3,
+      "maxLookback": 5,
+      "maxClockDeltaMin": 10,
+      "evictionGuardMessages": 3,
+      "evictionGuardTokenCap": 4000
+    },
+    "budgetFraction": 0.6,
     "contextWindowReserve": 0.25,
     "targetBudgetFraction": 0.50,
-    "warmHistoryBudgetFraction": 0.27,
-    "maxFacts": 25,
-    "maxHistoryMessages": 500,
-    "maxCrossSessionContext": 4000,
-    "maxRecentToolPairs": 3,
-    "maxProseToolPairs": 10,
-    "keystoneHistoryFraction": 0.15,
-    "keystoneMaxMessages": 12,
-    "wikiTokenCap": 500
+    "warmHistoryBudgetFraction": 0.45,
+    "maxFacts": 28,
+    "maxHistoryMessages": 250,
+    "maxCrossSessionContext": 0,
+    "keystoneHistoryFraction": 0.20,
+    "keystoneMaxMessages": 15,
+    "hyperformProfile": "standard"
   }
 }
 ```
 
-| Knob | Recommended | What it controls | Notes |
-|---|---|---|---|
-| `budgetFraction` | 0.55 | Fraction of the detected context window used as input budget | Raise to 0.65 for agents that aggressively tool-use. Autodetect only handles known model families — see *Context window overrides* below for custom/local/finetuned models |
-| `contextWindowReserve` | 0.25 | Reserve left for output and tool results | Below 0.20 on large-context models invites late-turn overflow |
-| `targetBudgetFraction` | 0.50 | Split between context assembly and history | Higher = richer facts/wiki; lower = more conversation headroom |
-| `warmHistoryBudgetFraction` | 0.27 | History's share of first-turn warming | The key lever against tight trim cycles; don't push below 0.20 |
-| `maxFacts` | 25 | Structured facts injected per turn | Recall surfaces more as topics emerge; 35 is fine for long-memory seats |
-| `maxHistoryMessages` | 500 | Candidate pool for history ranking | Pool size, not load size. 300 is fine for short-session agents |
-| `maxCrossSessionContext` | 4000 | Cross-session context tokens | Solo agents with one session: set to 0 |
-| `maxRecentToolPairs` | 3 | Verbatim tool pairs kept | Raise to 5 for code agents with heavy tool output |
-| `maxProseToolPairs` | 10 | Compressed tool pairs before stubbing | |
-| `keystoneHistoryFraction` | 0.15 | Older significant turns reserved within history slot | |
-| `keystoneMaxMessages` | 12 | Max keystone candidates per turn | Raise to 18 if the agent loses track of older decisions |
-| `wikiTokenCap` | 500 | Cap on wiki/knowledge injection | Raise if your agent uses heavy doc content |
+Run `hypermem-doctor --fix-plan` after upgrades. It flags older preserved configs that are missing the 0.9.4 recall-surface knobs, legacy `agents.defaults.memorySearch`, native compaction collisions, plugin wiring defects, and risky model-window autodetect paths.
+
+`hypermem-status --master` also reports the active recall-surface config as `0.9.4 surface N/10 recommended knobs`, plus history-query health, vector coverage, and bounded maintenance debt. Fleet maintenance scans are bounded by default; use `--fleet-agent-limit`, `--max-candidates-per-conversation`, and `--top-agents` only when you intentionally widen the health check. Referenced-noise repair remains capped by `--repair-limit` with a hard max of 500.
 
 **Lean profile** (~35–45% fewer tokens per turn) — for constrained hosts, small models, or cost-sensitive deployments:
 
@@ -997,7 +1000,7 @@ Expected on fresh installs. Facts and episodes accumulate over real conversation
 
 **Lost bundled plugins after setting `plugins.allow`**
 
-If you set `plugins.allow` to only `["hypercompositor","hypermem"]` without including your pre-existing allowed plugins, OpenClaw can stop loading bundled CLI surfaces and channel plugins. Fix: restore the prior allowlist, append `hypercompositor` and `hypermem`, then `openclaw gateway restart`. If `plugins.allow` was previously unset or empty, remove the HyperMem-only allowlist instead of keeping it.
+If you set `plugins.allow` to only `["hypercompositor","hypermem"]` without including your pre-existing allowed plugins, OpenClaw can stop loading bundled CLI surfaces and channel plugins. Fix: restore the prior allowlist, append `hypercompositor` and `hypermem`, then `openclaw daemon restart`. If `plugins.allow` was previously unset or empty, remove the HyperMem-only allowlist instead of keeping it.
 
 **Plugin not found**
 
@@ -1045,7 +1048,7 @@ To return to OpenClaw's default context engine:
 ```bash
 openclaw config set plugins.slots.contextEngine legacy
 openclaw config set plugins.slots.memory none
-openclaw gateway restart
+openclaw daemon restart
 ```
 
 Data in `~/.openclaw/hypermem/` is untouched. Re-enable by switching back.
@@ -1063,7 +1066,7 @@ Example:
 ```bash
 # Point hypermem at a different data location:
 export HYPERMEM_DATA_DIR=/mnt/data/hypermem
-openclaw gateway restart
+openclaw daemon restart
 ```
 
 > The config file path (`~/.openclaw/hypermem/config.json`) is separate from the data directory. Moving `HYPERMEM_DATA_DIR` does not move the config file.

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.4.** 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.4'
   MIN_NODE_VERSION,      // '22.0.0'
   SQLITE_VEC_VERSION,    // '0.1.9'
   MAIN_SCHEMA_VERSION,   // 10 (messages.db)
@@ -423,7 +423,9 @@ npm install @psiclawops/hypermem
 npx hypermem-install
 ```
 
-`hypermem-install` stages the runtime payload into `~/.openclaw/plugins/hypermem`. It does **not** modify OpenClaw config and does **not** restart the gateway. HyperMem is active only after OpenClaw is wired, restarted, and compose activity appears in logs.
+`hypermem-install` stages the runtime payload into `~/.openclaw/plugins/hypermem` and creates `~/.openclaw/hypermem/config.json` only when it is missing. It does **not** modify OpenClaw config and does **not** restart the gateway. HyperMem is active only after OpenClaw is wired, restarted, and compose activity appears in logs.
+
+For production-shaped local validation, run `npm run install:runtime:packed` from the repo. It packs HyperMem, installs the tarball into a temporary app, and stages OpenClaw from that installed package. Avoid validating live gateway behavior from repo symlinks or copied working-tree files.
 
 Install states:
 
@@ -435,30 +437,7 @@ Install states:
 | Runtime loaded | gateway restarted and both plugins loaded |
 | Runtime active | logs show `hypermem initialized` and compose activity |
 
-Minimal starter config for lightweight FTS-only mode:
-
-```bash
-mkdir -p ~/.openclaw/hypermem
-cat > ~/.openclaw/hypermem/config.json <<'JSON'
-{
-  "embedding": { "provider": "none" },
-  "compositor": {
-    "budgetFraction": 0.55,
-    "contextWindowReserve": 0.25,
-    "targetBudgetFraction": 0.50,
-    "warmHistoryBudgetFraction": 0.27,
-    "maxFacts": 25,
-    "maxHistoryMessages": 500,
-    "maxCrossSessionContext": 4000,
-    "maxRecentToolPairs": 3,
-    "maxProseToolPairs": 10,
-    "keystoneHistoryFraction": 0.15,
-    "keystoneMaxMessages": 12,
-    "wikiTokenCap": 500
-  }
-}
-JSON
-```
+The installer writes the starter config for you when `~/.openclaw/hypermem/config.json` is missing. The default is recall-friendly standard mode with Ollama `nomic-embed-text`; if Ollama is not available, install it or run `npx hypermem-install --skip-embedding-check` for CI/container practice. To force lightweight FTS-only mode, pre-create `~/.openclaw/hypermem/config.json` with `{"embedding":{"provider":"none"}}` before running the installer.
 
 Then merge the staged plugin paths into OpenClaw config and set the slots:
 
@@ -480,7 +459,7 @@ hypermem-status --health
 hypermem-model-audit --strict
 ```
 
-`hypermem-doctor` is the confidence check: it validates plugin wiring, runtime load state, recommended OpenClaw settings such as `contextPruning.mode=off`, GPT-5 personality overlay off, startup/bootstrap injection sizing, compaction safety settings, HyperMem data files, and model context-window overrides for GPT/OpenAI-compatible/local gateways. It is read-only and prints a reviewable fix plan.
+`hypermem-doctor` is the confidence check: it validates plugin wiring, plugin registry refresh readiness, runtime load state, recommended OpenClaw settings such as `contextPruning.mode=off`, GPT-5 personality overlay off, startup/bootstrap injection sizing, compaction safety settings including `maxActiveTranscriptBytes` remaining unset for HyperMem-managed compaction, HyperMem data files, and model context-window overrides for GPT/OpenAI-compatible/local gateways. It is read-only and prints a reviewable fix plan.
 
 Full install, upgrade, source-clone, embedding provider, reranker, fleet config, and rollback guidance lives in **[INSTALL.md](./INSTALL.md)**.
 
@@ -574,9 +553,12 @@ hypermem-status --health
 hypermem-status --master
 hypermem-model-audit --strict
 hypermem-bench --iterations 1000 --warmup 50 --agent main
+# repo release validation:
+npm run release:install-smoke
+npm run validate:history-query
 ```
 
-Diagnostics and validation details: **[docs/DIAGNOSTICS.md](./docs/DIAGNOSTICS.md)** and **[docs/INTEGRATION_VALIDATION.md](./docs/INTEGRATION_VALIDATION.md)**.
+Diagnostics and validation details: **[docs/DIAGNOSTICS.md](./docs/DIAGNOSTICS.md)** and **[docs/INTEGRATION_VALIDATION.md](./docs/INTEGRATION_VALIDATION.md)**. The master health surface reports 0.9.4 recall-surface config completeness, history-query readiness, vector coverage, bounded maintenance debt, and referenced-noise repair status.
 
 ## Pressure management
 

package/assets/default-config.json

@@ -0,0 +1,47 @@
+{
+  "embedding": {
+    "provider": "ollama",
+    "model": "nomic-embed-text",
+    "dims": 768,
+    "dimensions": 768,
+    "ollamaUrl": "http://localhost:11434",
+    "timeout": 10000,
+    "batchSize": 32
+  },
+  "compositor": {
+    "turnBudget": {
+      "budgetFraction": 0.6,
+      "minContextFraction": 0.18
+    },
+    "warming": {
+      "protectedFloorEnabled": true,
+      "shapedWarmupDecay": true
+    },
+    "adjacency": {
+      "enabled": true,
+      "boostMultiplier": 1.3,
+      "maxLookback": 5,
+      "maxClockDeltaMin": 10,
+      "evictionGuardMessages": 3,
+      "evictionGuardTokenCap": 4000
+    },
+    "contextWindowOverrides": {},
+    "budgetFraction": 0.6,
+    "contextWindowReserve": 0.25,
+    "targetBudgetFraction": 0.5,
+    "warmHistoryBudgetFraction": 0.45,
+    "maxFacts": 28,
+    "maxHistoryMessages": 250,
+    "maxCrossSessionContext": 0,
+    "keystoneHistoryFraction": 0.2,
+    "keystoneMaxMessages": 15,
+    "hyperformProfile": "standard"
+  },
+  "indexer": {
+    "enabled": true,
+    "factExtractionMode": "tiered",
+    "periodicInterval": 300000,
+    "batchSize": 128,
+    "maxMessagesPerTick": 500
+  }
+}