@psiclawops/hypermem 0.9.3 → 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
 
@@ -58,7 +58,9 @@ 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
 ```
 
 ---
@@ -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

@@ -386,7 +386,7 @@ Slot-level budget allocation is shown in the [hypercompositor diagram](#what-the
 
 ## Requirements
 
-**Current release: hypermem 0.9.2.** 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.2'
+  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
+  }
+}

package/bin/hypermem-doctor.mjs

@@ -123,6 +123,10 @@ function setCommand(pathKey, value, strictJson = false) {
   return `openclaw config set ${pathKey} ${shellQuote(rendered)}${strictJson ? ' --strict-json' : ''}`;
 }
 
+function unsetCommand(pathKey) {
+  return `openclaw config unset ${pathKey}`;
+}
+
 function shellQuote(value) {
   if (/^[A-Za-z0-9_./:@=-]+$/.test(value)) return value;
   return `'${String(value).replaceAll("'", "'\\''")}'`;
@@ -165,7 +169,7 @@ function checkConfigReadable() {
   } else if (hypermemRead.exists) {
     required('ok', 'hypermem-config-json', `HyperMem config readable: ${flags.hypermemConfig}`);
   } else {
-    recommended('warn', 'hypermem-config-present', `No legacy HyperMem config found at ${flags.hypermemConfig}; ok if config lives in openclaw.json`);
+    recommended('warn', 'hypermem-config-present', `HyperMem config missing at ${flags.hypermemConfig}; run hypermem-install to create the 0.9.4 default config, or declare equivalent plugin config in openclaw.json`);
   }
 }
 
@@ -212,6 +216,15 @@ function checkRuntimePlugins() {
     recommended('ok', 'runtime-plugin-list', 'Runtime plugin load check skipped');
     return;
   }
+  const registryRefresh = spawnSync('openclaw', ['plugins', 'registry', '--refresh'], { encoding: 'utf8', timeout: 15000 });
+  if (registryRefresh.error) {
+    recommended('warn', 'plugin-registry-refresh', `Could not refresh OpenClaw plugin registry: ${registryRefresh.error.message}`);
+  } else if (registryRefresh.status === 0) {
+    recommended('ok', 'plugin-registry-refresh', 'OpenClaw plugin registry refresh command completed');
+  } else {
+    recommended('warn', 'plugin-registry-refresh', `OpenClaw plugin registry refresh exited ${registryRefresh.status}; run openclaw plugins registry --refresh after staging HyperMem`);
+  }
+
   const result = spawnSync('openclaw', ['plugins', 'list'], { encoding: 'utf8', timeout: 8000 });
   if (result.error) {
     recommended('warn', 'runtime-plugin-list', `Could not run openclaw plugins list: ${result.error.message}`);
@@ -224,7 +237,51 @@ function checkRuntimePlugins() {
     'runtime-plugin-list',
     hasComposer && hasMemory
       ? 'Runtime plugin list mentions hypercompositor and hypermem'
-      : 'Runtime plugin list did not clearly show both hypercompositor and hypermem; restart gateway after config changes');
+      : 'Runtime plugin list did not clearly show both hypercompositor and hypermem; run openclaw plugins registry --refresh, openclaw doctor --fix --yes, then restart gateway after config changes');
+}
+
+
+function effectiveHyperMemConfig() {
+  return {
+    ...hypermem,
+    ...pluginConfig,
+    compositor: { ...(hypermem.compositor ?? {}), ...(pluginConfig.compositor ?? {}) },
+    embedding: { ...(hypermem.embedding ?? {}), ...(pluginConfig.embedding ?? {}) },
+  };
+}
+
+function checkRecallSurfaceRecommendations() {
+  const config = effectiveHyperMemConfig();
+  const compositor = config.compositor ?? {};
+  const expected = [
+    ['compositor.turnBudget.budgetFraction', 0.6],
+    ['compositor.turnBudget.minContextFraction', 0.18],
+    ['compositor.warming.protectedFloorEnabled', true],
+    ['compositor.warming.shapedWarmupDecay', true],
+    ['compositor.adjacency.enabled', true],
+    ['compositor.adjacency.boostMultiplier', 1.3],
+    ['compositor.adjacency.maxLookback', 5],
+    ['compositor.adjacency.maxClockDeltaMin', 10],
+    ['compositor.adjacency.evictionGuardMessages', 3],
+    ['compositor.adjacency.evictionGuardTokenCap', 4000],
+  ];
+
+  for (const [pathKey, value] of expected) {
+    const actual = get({ compositor }, pathKey);
+    const ok = actual === value;
+    recommended(ok ? 'ok' : 'warn', pathKey,
+      ok
+        ? `${pathKey} is recommended 0.9.4 value ${JSON.stringify(value)}`
+        : `${pathKey} is ${JSON.stringify(actual)}; recommended ${JSON.stringify(value)} for 0.9.4 recall-surface protection`);
+  }
+
+  const dims = config.embedding?.dims;
+  const dimensions = config.embedding?.dimensions;
+  if (dims != null && dimensions != null && dims !== dimensions) {
+    recommended('warn', 'embedding.dims-consistency', `embedding.dims (${dims}) and embedding.dimensions (${dimensions}) differ; keep them aligned while both aliases are supported`);
+  } else {
+    recommended('ok', 'embedding.dims-consistency', 'Embedding dimension aliases are absent or aligned');
+  }
 }
 
 function checkOpenClawRecommendations() {
@@ -254,6 +311,22 @@ function checkOpenClawRecommendations() {
     else recommended(ok ? 'ok' : 'warn', pathKey, message, details);
   }
 
+  const legacyMemorySearch = get(openclaw, 'agents.defaults.memorySearch');
+  recommended(legacyMemorySearch == null ? 'ok' : 'warn',
+    'agents.defaults.memorySearch',
+    legacyMemorySearch == null
+      ? 'Legacy agents.defaults.memorySearch is unset'
+      : `Legacy agents.defaults.memorySearch is ${JSON.stringify(legacyMemorySearch)}; HyperMem supersedes this path and it should be unset to avoid stale operator assumptions`,
+    legacyMemorySearch == null ? {} : { command: unsetCommand('agents.defaults.memorySearch') });
+
+  const maxActiveTranscriptBytes = get(openclaw, 'agents.defaults.compaction.maxActiveTranscriptBytes');
+  recommended(maxActiveTranscriptBytes == null ? 'ok' : 'warn',
+    'agents.defaults.compaction.maxActiveTranscriptBytes',
+    maxActiveTranscriptBytes == null
+      ? 'agents.defaults.compaction.maxActiveTranscriptBytes is unset, as recommended for HyperMem-managed compaction'
+      : `agents.defaults.compaction.maxActiveTranscriptBytes is ${JSON.stringify(maxActiveTranscriptBytes)}; recommended unset so OpenClaw transcript rotation does not fight HyperMem fences`,
+    maxActiveTranscriptBytes == null ? {} : { command: unsetCommand('agents.defaults.compaction.maxActiveTranscriptBytes') });
+
   const injection = get(openclaw, 'agents.defaults.contextInjection');
   if (injection == null || injection === 'always' || injection === 'continuation-skip') {
     recommended('ok', 'agents.defaults.contextInjection', `Context injection mode is ${JSON.stringify(injection ?? 'default')}`);
@@ -367,6 +440,7 @@ if (openclawRead.value) {
   checkOpenClawRecommendations();
   checkModels();
 }
+checkRecallSurfaceRecommendations();
 checkDataDir();
 checkRuntimePlugins();