@psiclawops/hypermem 0.9.3 → 0.9.5

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to hypermem are documented here.
 
+## 0.9.5 - 2026-04-29
+
+- **Install-readiness defaults hardened.** Fresh installs now stage `embedding.provider: "none"` by default, making the first-install path FTS5-only and free of Ollama or hosted-provider dependencies.
+- **Install states documented.** README, INSTALL, and TUNING now classify fresh installs as GREEN/YELLOW/RED, with FTS5/no-embedding installs explicitly YELLOW rather than failed.
+- **Semantic recall is opt-in after baseline install.** Ollama and hosted embedding setup moved behind the verified baseline path so operators can bring HyperMem online before adding vector recall.
+- **OpenClaw command guidance updated.** Install docs now use the current `openclaw gateway` command surface instead of stale daemon commands.
+- **Public package payload tightened.** npm package files now include operator-facing docs only; internal architecture and release-process docs are excluded from the published artifact.
+- **Fresh-install smoke covers the FTS5 default.** The release gate now validates the no-embedding default path directly.
+
+## 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.
@@ -16,7 +41,7 @@ All notable changes to hypermem are documented here.
 - **Vector store init log shows actual provider/model/dims.** Diagnostic log line at startup now reflects the resolved configuration instead of the static placeholder, so misconfiguration is visible immediately.
 - **Tool artifact API arity + hydration docs aligned.** Doc-only follow-ups; no runtime behavior change.
 
-**Operator action:** upgrade from 0.9.0 is recommended. 0.9.0 in production with a configured non-default embedder may have written mismatched vectors; check `hypermem-status` for vector-store init line after upgrade.
+**operator action:** upgrade from 0.9.0 is recommended. 0.9.0 in production with a configured non-default embedder may have written mismatched vectors; check `hypermem-status` for vector-store init line after upgrade.
 
 ## 0.9.0 - adaptive context lifecycle
 
@@ -49,7 +74,7 @@ All notable changes to hypermem are documented here.
 - **Provider + model identity is now tracked explicitly in HyperCompositor model state.** Mid-session routing changes are detected on the full `provider/model` key, not budget alone, so `github-copilot/claude-sonnet-4-6` and `anthropic/claude-sonnet-4-6` are treated as different operational envelopes.
 - **Downshift detection now keys off provider/model-aware state.** Budget-downshift handling still stays conservative, but verbose logs now surface provider swaps, model swaps, and budget deltas clearly during `context:assemble`.
 - **Install docs now declare the full operator path.** README, INSTALL.md, and TUNING.md now separate staging from activation, document install states explicitly, add merge-safe wiring guidance, and clarify what healthy-but-empty looks like on a first run.
-- **0.8.5 release parity.** Package versions are aligned for the next publish while preserving the npm-first installer and merge-safe config guidance landed from Pylon's install review.
+- **0.8.5 release parity.** Package versions are aligned for the next publish while preserving the npm-first installer and merge-safe config guidance landed from Hank's install review.
 
 ## 0.8.4 — compaction fence fix, install-path fixes, zod runtime packaging
 

package/INSTALL.md

@@ -5,7 +5,7 @@ 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 not 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:**
@@ -15,7 +15,7 @@ openclaw gateway 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 `openclaw 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 onboarded, complete the OpenClaw 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,7 +68,7 @@ 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 FTS5 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).
 
@@ -74,37 +76,15 @@ Release validation details live in [docs/INTEGRATION_VALIDATION.md](./docs/INTEG
 >
 > **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 installation-safe FTS5 mode:
 
-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
+- `embedding.provider: "none"`
+- `warmHistoryBudgetFraction: 0.45`
+- standard fact, keystone, and history caps
 
-```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
-```
+This is intentional. A clean first install should load, compose, and verify without requiring Ollama or an external API key. The result is **YELLOW** install readiness: HyperMem is active with keyword recall, but semantic vector recall is disabled. Upgrade to Ollama, OpenRouter, or Gemini after the baseline install is active.
 
-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.
+Existing config files are preserved unchanged. If an existing config selects `embedding.provider: "ollama"`, `hypermem-install` checks that Ollama and `nomic-embed-text` are available unless you pass `--skip-embedding-check`.
 
 ### Install states
 
@@ -120,6 +100,16 @@ Treat the install as 5 explicit states:
 
 Do not stop at state 2 and call the install done.
 
+Install readiness states:
+
+| State | Meaning | Action |
+|---|---|---|
+| **GREEN** | Runtime active and semantic embeddings/reranker are configured as intended | Ready for normal use |
+| **YELLOW** | Runtime active with FTS5 fallback or model-audit warnings | Usable, but finish provider/model tuning before production claims |
+| **RED** | Runtime not staged, not loaded, not wired, or falling back to `legacy` | Not installed |
+
+A no-embedding FTS5 install is **YELLOW**, not failed. A `legacy` context-engine fallback is **RED**.
+
 Wire both plugins into OpenClaw:
 
 **Step 1: Check your existing config (mandatory — do this before wiring).**
@@ -141,6 +131,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.
@@ -290,7 +282,7 @@ Everything runs in-process on SQLite memory databases. No external database serv
 
 > **Package versions:** the root package (`hypermem`) and the two plugins (`hypercompositor`, `hypermem-memory`) are versioned independently. Plugin versions trail the core by one minor version when no plugin-facing API changes ship in a release — this is expected.
 
-The **embedding layer** (L3 semantic search) requires a configured provider. Without one, hypermem falls back to FTS5 keyword matching. This is functional but degrades recall quality. Fresh installs should start with `provider: "none"` explicitly so the runtime behavior is intentional and easy to verify, then upgrade later. See [Setup Styles](#setup-styles) below.
+The **embedding layer** (L3 semantic search) is optional at install time. The packaged starter config uses `provider: "none"`, so HyperMem starts in FTS5 keyword mode with no external service dependency. This is functional and easy to verify, but recall quality improves when you later enable Ollama, OpenRouter, or Gemini. See [Setup Styles](#setup-styles) below.
 
 ---
 
@@ -321,7 +313,7 @@ Pick a tier based on your hardware:
 
 ### Minimal (no embedder)
 
-No Ollama, no API key. This config must exist **before gateway restart and runtime verification** so the clean install validates the intended lightweight behavior. Set `provider: 'none'` explicitly in `~/.openclaw/hypermem/config.json` to disable embedding entirely:
+No Ollama, no API key. This is the default clean-install posture. `hypermem-install` writes this config when `~/.openclaw/hypermem/config.json` is missing:
 
 ```json
 {
@@ -331,7 +323,7 @@ No Ollama, no API key. This config must exist **before gateway restart and runti
 }
 ```
 
-Without a config file, the default provider is `ollama` — if Ollama isn't running, the vector store initialization fails non-fatally and hypermem falls back to FTS5. Using `provider: 'none'` makes the intent explicit and avoids the init attempt.
+With `provider: 'none'`, HyperMem does not attempt vector initialization. The install should verify cleanly as FTS5 mode, then you can opt into semantic recall later.
 
 You'll see in the logs:
 ```
@@ -561,6 +553,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.
@@ -573,8 +567,8 @@ 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).
+- **Lightweight (no embedder):** keep the starter `{"embedding":{"provider":"none"}}` config. This is the default first-install path and verifies as YELLOW until you intentionally enable semantic recall.
+- **Local:** install Ollama, run `ollama pull nomic-embed-text`, then set `embedding.provider` to `"ollama"` with `model: "nomic-embed-text"`. 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
@@ -593,7 +587,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 gateway status` to confirm the gateway is running and accessible. If the gateway is running but logs fail, check your OpenClaw CLI auth context.
 
 Expected:
 ```
@@ -622,7 +616,7 @@ openclaw status                                     # look for hypermem in plugi
 
 ### Step 5 — Configure your fleet
 
-hypermem works out of the box for both single-agent and multi-agent installs. The source ships with generic placeholder agent names (`agent1`, `agent2`, `director1`, etc.) in two files that define fleet topology:
+hypermem works out of the box for both single-agent and multi-agent installs. The source ships with generic placeholder agent names (`alice`, `bob`, `director1`, etc.) in two files that define fleet topology:
 
 | File | What it defines |
 |---|---|
@@ -649,7 +643,7 @@ Facts, episodes, and topics are all scoped to your agent ID automatically. Cross
 
 #### Multi-agent installs
 
-hypermem ships with generic placeholder agent names (`agent1`, `agent2`, `director1`, etc.) in the two fleet topology files listed above.
+hypermem ships with generic placeholder agent names (`alice`, `bob`, `director1`, etc.) in the two fleet topology files listed above.
 
 Replace the placeholder names with your fleet:
 
@@ -657,7 +651,7 @@ Replace the placeholder names with your fleet:
 
 ```typescript
 // Before (placeholder):
-agent1: { agentId: 'agent1', tier: 'council' },
+alice: { agentId: 'alice', tier: 'council' },
 
 // After (your fleet):
 architect: { agentId: 'architect', tier: 'council' },
@@ -667,7 +661,7 @@ architect: { agentId: 'architect', tier: 'council' },
 
 ```typescript
 // Before (placeholder):
-agent1: 'infrastructure',
+alice: 'infrastructure',
 
 // After (your fleet):
 architect: 'infrastructure',
@@ -775,9 +769,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 +820,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:
 

package/README.md

@@ -332,7 +332,7 @@ Diagnostics expose reranker status, candidate count, and provider, so operators
 | Knowledge / wiki | Domain knowledge and synthesized topic pages with full-text search |
 | Episodes | Significant events, decisions, discoveries, participants, and source links |
 | Topics | Cross-session thread tracking and topic lifecycle state |
-| Preferences | Operator and agent behavior patterns |
+| Preferences | operator and agent behavior patterns |
 | Documents | Chunked workspace/governance docs, doc sources, and trigger retrieval metadata |
 | Knowledge graph | Links between facts, knowledge, topics, episodes, agents, and preferences |
 | Fleet registry | Agents, orgs, tiers, capabilities, and fleet topology |
@@ -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.5.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
 
 | Requirement | Version | Notes |
 |---|---|---|
@@ -398,10 +398,10 @@ 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.5'
   MIN_NODE_VERSION,      // '22.0.0'
   SQLITE_VEC_VERSION,    // '0.1.9'
-  MAIN_SCHEMA_VERSION,   // 10 (messages.db)
+  MAIN_SCHEMA_VERSION,   // 11 (messages.db)
   LIBRARY_SCHEMA_VERSION_EXPORT, // 19 (library.db)
 } from '@psiclawops/hypermem';
 ```
@@ -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 first-install posture is FTS5/no-embedding mode with `{"embedding":{"provider":"none"}}`, so HyperMem can load and compose without Ollama or an API key. That verifies as **YELLOW** install readiness: runtime active, semantic vector recall disabled. Enable Ollama, OpenRouter, or Gemini after the baseline install is active.
 
 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)**.
 
@@ -498,7 +477,7 @@ If you prefer, hand the install to your OpenClaw agent:
 
 > "Install hypermem following INSTALL.md. I'm running a [solo / multi-agent] setup."
 
-### Operator guides
+### operator guides
 
 - **[docs/MEMORY_MD_AUTHORING.md](./docs/MEMORY_MD_AUTHORING.md)**, how to keep `MEMORY.md` compact, durable, and reviewable
 - **[docs/TUNING.md](./docs/TUNING.md)**, context assembly and output shaping profiles
@@ -516,7 +495,7 @@ Two independent surfaces: **context assembly** (what fills the context window) a
 | `standard` | 128k | Normal deployments, small fleets |
 | `full` | 200k+ | Multi-agent fleets, large-context models |
 
-Start with `light`. Use `mergeProfile()` to adjust individual settings:
+Start from the installed baseline. Use `light` for constrained/no-embedding installs, `standard` once semantic recall is enabled, and `full` for large-context fleets. Use `mergeProfile()` to adjust individual settings:
 
 ```typescript
 import { mergeProfile } from '@psiclawops/hypermem';
@@ -567,16 +546,19 @@ README keeps the interface surface short. Use the detailed docs for exact exampl
 
 **Runtime API:** import `HyperMem` from `@psiclawops/hypermem` for direct Node.js use, custom tests, and non-OpenClaw integrations. See **[INSTALL.md § Non-OpenClaw usage](./INSTALL.md#non-openclaw-usage)** and package TypeScript declarations for the current interface.
 
-**Operator CLIs:**
+**operator CLIs:**
 
 ```bash
 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
 
@@ -612,7 +594,7 @@ hypermem composes context fresh on every turn, but a long-running session still
 | Symptom | Cause | Fix |
 |---|---|---|
 | `falling back to default engine "legacy"` in logs | Plugin not loaded or slot misconfigured | Check `openclaw config get plugins.slots.contextEngine` is `hypercompositor`, paths are correct, and both plugins are in `plugins.allow` |
-| `openclaw gateway restart` says disabled/not configured | OpenClaw not fully onboarded | Complete OpenClaw setup first. `gateway restart` requires a running gateway. |
+| `openclaw gateway restart` says disabled/not configured | OpenClaw not fully onboarded | Complete OpenClaw setup first. `openclaw gateway restart` requires an onboarded gateway. |
 | `openclaw logs` fails with auth/token error | Gateway auth not set up for CLI | Run `openclaw gateway status` to confirm the gateway is accessible |
 | `facts=0 semantic=0` every turn | Fresh install, no data yet | Expected. Facts accumulate over real conversations. |
 | Health check says "no sessions ingested" | No agent has run a session yet | Send a test message, then re-run |
@@ -631,7 +613,7 @@ The migration guide includes worked examples showing how to bring data from Open
 
 All examples default to dry-run. Nothing is written until you add `--apply`.
 
-Operator guide: **[docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md)**
+operator guide: **[docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md)**
 
 
 ---

package/assets/default-config.json

@@ -0,0 +1,41 @@
+{
+  "embedding": {
+    "provider": "none"
+  },
+  "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/bench/data-access-bench.mjs

@@ -16,7 +16,7 @@ function argValue(name, fallback = null) {
   return process.argv.find((a, i) => process.argv[i - 1] === name) ?? fallback;
 }
 
-const DATA_DIR = argValue('--data-dir', process.env.HYPERMEM_DATA_DIR ?? path.join(process.env.HOME || '/home/user', '.openclaw', 'hypermem'));
+const DATA_DIR = argValue('--data-dir', process.env.HYPERMEM_DATA_DIR ?? path.join(process.env.HOME || os.homedir(), '.openclaw', 'hypermem'));
 const ITERATIONS = parseInt(argValue('--iterations', '100'), 10);
 const WARMUP = parseInt(argValue('--warmup', '3'), 10);
 const TARGET_AGENT = argValue('--agent', null);