@psiclawops/hypermem 0.9.2 → 0.9.4

package/dist/vector-store.d.ts

@@ -37,6 +37,14 @@ export interface EmbeddingConfig {
     geminiIndexTaskType?: string;
     /** Gemini task type for queries. Default: RETRIEVAL_QUERY */
     geminiQueryTaskType?: string;
+    /** Generic query input type for providers that support asymmetric retrieval embeddings. */
+    queryInputType?: string;
+    /** Generic document input type for providers that support asymmetric retrieval embeddings. */
+    documentInputType?: string;
+    /** Optional explicit query prefix, applied before embedding query text. */
+    queryPrefix?: string;
+    /** Optional explicit document prefix, applied before embedding stored document text. */
+    documentPrefix?: string;
     /** Embedding model name. Default: nomic-embed-text (ollama) or text-embedding-3-small (openai) */
     model: string;
     /** Embedding dimensions. Default: 768 (ollama/nomic) or 1536 (openai/3-small) */
@@ -48,6 +56,7 @@ export interface EmbeddingConfig {
     /** LRU cache max entries. Default: 128 */
     cacheSize?: number;
 }
+export type EmbeddingInputKind = 'query' | 'document';
 export interface VectorSearchResult {
     rowid: number;
     distance: number;
@@ -72,7 +81,7 @@ export declare function clearEmbeddingCache(): void;
  * Supports single and batch embedding.
  * Results are cached per text hash — cache hits skip the Ollama call entirely.
  */
-export declare function generateEmbeddings(texts: string[], config?: EmbeddingConfig): Promise<Float32Array[]>;
+export declare function generateEmbeddings(texts: string[], config?: EmbeddingConfig, inputKind?: EmbeddingInputKind): Promise<Float32Array[]>;
 /**
  * VectorStore — manages vector indexes in an agent's vector database.
  *

package/dist/vector-store.d.ts.map

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

package/dist/vector-store.js

@@ -39,6 +39,35 @@ const GEMINI_DEFAULTS = {
     batchSize: 100, // Gemini batch limit
     timeout: 15000,
 };
+const OLLAMA_RETRIEVAL_PREFIX_DEFAULTS = {
+    'nomic-embed-text': { query: 'search_query: ', document: 'search_document: ' },
+    'qwen3-embedding': { query: 'query: ', document: 'passage: ' },
+    'mxbai-embed-large': { query: 'Represent this sentence for searching relevant passages: ', document: '' },
+};
+function baseModelName(model) {
+    return String(model ?? '').split(':')[0].toLowerCase();
+}
+function defaultInputType(config, kind) {
+    if (kind === 'query')
+        return config.queryInputType ?? config.geminiQueryTaskType;
+    return config.documentInputType ?? config.geminiIndexTaskType;
+}
+function resolveTextPrefix(config, kind) {
+    const explicit = kind === 'query' ? config.queryPrefix : config.documentPrefix;
+    if (explicit != null)
+        return explicit;
+    if (config.provider === 'ollama' || !config.provider) {
+        const defaults = OLLAMA_RETRIEVAL_PREFIX_DEFAULTS[baseModelName(config.model)];
+        return defaults?.[kind] ?? '';
+    }
+    return '';
+}
+function prepareEmbeddingTexts(texts, config, kind) {
+    const prefix = resolveTextPrefix(config, kind);
+    if (!prefix)
+        return texts;
+    return texts.map((text) => text.startsWith(prefix) ? text : `${prefix}${text}`);
+}
 const _embeddingCache = new Map();
 /**
  * Insert an entry into the LRU cache, evicting the oldest if over capacity.
@@ -74,7 +103,7 @@ export function clearEmbeddingCache() {
  * Generate embeddings via OpenAI Embeddings API.
  * Batches up to batchSize inputs per request.
  */
-async function generateOpenAIEmbeddings(texts, config) {
+async function generateOpenAIEmbeddings(texts, config, kind = 'document') {
     // Resolve API key: config > environment
     const apiKey = config.openaiApiKey
         ?? process.env.OPENROUTER_API_KEY
@@ -92,13 +121,17 @@ async function generateOpenAIEmbeddings(texts, config) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), config.timeout);
         try {
+            const body = { model, input: batch };
+            const inputType = defaultInputType(config, kind);
+            if (inputType)
+                body.input_type = inputType;
             const response = await fetch(`${baseUrl}/embeddings`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
                     'Authorization': `Bearer ${apiKey}`,
                 },
-                body: JSON.stringify({ model, input: batch }),
+                body: JSON.stringify(body),
                 signal: controller.signal,
             });
             if (!response.ok) {
@@ -378,7 +411,7 @@ function l2Normalize(vec) {
 async function generateGeminiEmbeddings(texts, config, taskType) {
     const baseUrl = config.geminiBaseUrl ?? 'https://generativelanguage.googleapis.com';
     const model = config.model;
-    const effectiveTaskType = taskType ?? config.geminiIndexTaskType ?? 'RETRIEVAL_DOCUMENT';
+    const effectiveTaskType = taskType ?? defaultInputType(config, 'document') ?? 'RETRIEVAL_DOCUMENT';
     const results = [];
     // Resolve auth: API key takes precedence (simpler), then OAuth
     const apiKey = config.geminiApiKey ?? process.env.GEMINI_EMBEDDING_API_KEY ?? process.env.GEMINI_API_KEY ?? process.env.GOOGLE_API_KEY ?? null;
@@ -459,10 +492,11 @@ async function generateGeminiEmbeddings(texts, config, taskType) {
  * Supports single and batch embedding.
  * Results are cached per text hash — cache hits skip the Ollama call entirely.
  */
-export async function generateEmbeddings(texts, config = DEFAULT_EMBEDDING_CONFIG) {
+export async function generateEmbeddings(texts, config = DEFAULT_EMBEDDING_CONFIG, inputKind = 'document') {
     // 'none' provider: explicit no-op — semantic search disabled, FTS5 fallback only
     if (config.provider === 'none')
         return [];
+    texts = prepareEmbeddingTexts(texts, config, inputKind);
     // Apply provider-specific defaults when provider is 'openai' and fields are at Ollama defaults
     if (config.provider === 'openai') {
         // Merge: OpenAI defaults fill in any unset fields, user-supplied values always win
@@ -475,7 +509,7 @@ export async function generateEmbeddings(texts, config = DEFAULT_EMBEDDING_CONFI
         };
         // OpenAI path — no LRU cache (responses are billed; caching at this layer
         // adds complexity without proportional benefit given async background use).
-        return generateOpenAIEmbeddings(texts, config);
+        return generateOpenAIEmbeddings(texts, config, inputKind);
     }
     if (config.provider === 'gemini') {
         config = {
@@ -487,7 +521,9 @@ export async function generateEmbeddings(texts, config = DEFAULT_EMBEDDING_CONFI
         };
         // Gemini path — no LRU cache (same rationale as OpenAI: billed API calls,
         // background indexing context, minimal benefit from this-layer caching).
-        return generateGeminiEmbeddings(texts, config);
+        return generateGeminiEmbeddings(texts, config, inputKind === 'query'
+            ? (config.geminiQueryTaskType ?? config.queryInputType ?? 'RETRIEVAL_QUERY')
+            : (config.geminiIndexTaskType ?? config.documentInputType ?? 'RETRIEVAL_DOCUMENT'));
     }
     if (texts.length === 0)
         return [];
@@ -635,7 +671,7 @@ export class VectorStore {
             return false; // Already indexed, content unchanged
         }
         // Generate embedding
-        const [embedding] = await generateEmbeddings([content], this.config);
+        const [embedding] = await generateEmbeddings([content], this.config, 'document');
         const bytes = vecToBytes(embedding);
         if (existing) {
             // Update: delete old vector, insert new
@@ -684,7 +720,7 @@ export class VectorStore {
             return { indexed, skipped };
         // Batch generate embeddings
         const texts = toIndex.map(item => item.content);
-        const embeddings = await generateEmbeddings(texts, this.config);
+        const embeddings = await generateEmbeddings(texts, this.config, 'document');
         // Insert in a transaction
         this.db.exec('BEGIN');
         try {
@@ -745,7 +781,7 @@ export class VectorStore {
             cachePut(simpleHash(query), queryEmbedding, maxSize);
         }
         else {
-            [queryEmbedding] = await generateEmbeddings([query], this.config);
+            [queryEmbedding] = await generateEmbeddings([query], this.config, 'query');
         }
         const queryBytes = vecToBytes(queryEmbedding);
         const results = [];

package/docs/DIAGNOSTICS.md

@@ -16,6 +16,8 @@ HyperMem diagnostics are split into operator CLIs, validation scripts, and runti
 | Version parity | `npm run validate:version-parity` | package versions and plugin dependencies are release-aligned |
 | Release path | `npm run validate:release-path` | build plus plugin pipeline gateway path |
 | Docs/config validation | `npm run validate:docs && npm run validate:config` | documented commands and config surfaces match code |
+| History query validation | `npm run validate:history-query` | `MessageStore.queryHistory()`, `history_query` plugin tool, metadata-only telemetry, and health JSON surface are wired |
+| Fresh-install smoke gate | `npm run release:install-smoke` | packed npm artifact installs without source fallback, no-Ollama failure is clear, skip-mode stages, existing config is preserved, and failure artifacts are captured |
 
 ## `hypermem-status`
 
@@ -35,6 +37,8 @@ hypermem-status --agent forge --master
 hypermem-status --json
 ```
 
+`hypermem-status --master --json` includes `querySurfaces.historyQuery`, which proves the built core API, memory-plugin tool registration, telemetry hook, and message-store schema are present. A missing item degrades master health with `history.query surface incomplete`. It also includes `config.recallSurface`, which reports whether the active install has the 0.9.4 recall-surface config: turn budget, protected warming, shaped warmup decay, adjacency boost, and literal antecedent guard. A partial match surfaces as `0.9.4 recall-surface config incomplete`, which usually means an older preserved config needs review after upgrade.
+
 Healthy fresh install behavior may include empty counts or `no sessions ingested`. That is not a failure. A fresh install becomes active only after the gateway loads the plugins and an agent turn runs.
 
 Failure signals:
@@ -71,6 +75,58 @@ It reports min, average, p50, p95, p99, and max latency for the data paths prese
 
 Use this for local validation of README speed claims. Results depend on hardware, database size, selected agent, and which optional surfaces are enabled. Vector embedding generation and hosted reranker latency are not part of these SQLite access timings; they are configured separately and should be measured against the chosen provider.
 
+## Fresh-install smoke artifacts
+
+Release validation uses the packed artifact path, not a repo symlink:
+
+```bash
+npm run release:install-smoke
+```
+
+The smoke gate verifies these installer failure classes before public release:
+
+- install from packed npm artifact with no source checkout mounted
+- no-Ollama/no-tools class fails with actionable remediation instead of silently staging a degraded semantic-recall install
+- `--skip-embedding-check` stages successfully for CI/container practice
+- existing `~/.openclaw/hypermem/config.json` is preserved unchanged
+- executable bins are present in the staged runtime
+
+On failure, artifacts are preserved under `.artifacts/fresh-install-smoke/<run-id>/`. Inspect `metadata.txt`, `fresh-install-smoke.stdout.log`, `fresh-install-smoke.stderr.log`, `npm-pack.log`, `container-tmp-files.txt`, `container-tmp-tree.txt`, installer stdout/stderr captures, generated configs, and package metadata before rerunning. Do not debug installer failures from terminal scrollback alone. That is how the same rake gets stepped on twice.
+
+## Recall-surface diagnostics
+
+0.9.4 added health checks for the recall-preservation surface. Use both tools:
+
+```bash
+hypermem-doctor --fix-plan
+hypermem-status --master --json
+```
+
+Expected active config:
+
+- `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`
+
+The deterministic release tests are:
+
+```bash
+node test/adaptive-recall-breadth.mjs
+node test/afterturn-protected-floor.mjs
+node test/afterturn-stability.mjs
+node test/hybrid-retrieval.mjs
+node test/compositor.mjs
+```
+
+These prove the warmed context floor, shaped warmup, adjacency boost, heartbeat/system suppression, and literal antecedent guard.
+
 ## Runtime logs
 
 After wiring and restart:
@@ -198,8 +254,39 @@ npm run validate:version-parity
 npm run validate:docs
 npm run validate:config
 npm run validate:release-path
+npm run validate:history-query
+npm run release:install-smoke
 npm test
 hypermem-model-audit --strict || true
 ```
 
 The local repo may not be the active OpenClaw runtime, so `hypermem-status` and `hypermem-model-audit` should be interpreted against the configured deployment. For package release proof, the required gates are version parity, docs/config validation, release path, tests, and pack dry runs.
+
+
+### Production-shaped runtime validation
+
+HyperMem development validation must install the packed package into OpenClaw's managed plugin directory before claiming a runtime fix is live. Do not rely on a repo symlink, global npm link, or copied `dist/` files as production evidence.
+
+Required loop:
+
+```bash
+npm run build:all
+npm pack
+node scripts/install-packed-runtime.mjs ./psiclawops-hypermem-<version>.tgz
+systemctl --user restart openclaw-gateway
+node bin/hypermem-status.mjs --master
+```
+
+The health check must verify the managed install at `~/.openclaw/plugins/hypermem`, not the working tree.
+
+### Referenced-noise maintenance debt
+
+`hypermem-status --master` reports referenced-noise debt under `## Maintenance`. This is low-signal message content that cannot be deleted by ordinary noise sweep because it is still a foreign-key target, usually through `messages.parent_id`.
+
+Operators can run the conservative repair path:
+
+```bash
+node bin/hypermem-status.mjs --master --repair-referenced-noise --repair-limit 100
+```
+
+The repair only collapses noise nodes blocked solely by `messages.parent_id`. It reparents children to the deleted node's parent, decrements subtree depth, and rolls back the whole batch if `PRAGMA foreign_key_check` reports any violation. Context and composition snapshot heads are detected but not repaired by this pass.

package/docs/INTEGRATION_VALIDATION.md

@@ -154,10 +154,20 @@ npm pack ./plugin --dry-run
 npm pack ./memory-plugin --dry-run
 ```
 
-Then test the packed artifact from a temp directory:
+Runtime validation must install the packed artifact, not the repo working tree. The production-shaped local install path is:
+
+```bash
+npm run install:runtime:packed
+openclaw gateway restart
+openclaw plugins list
+node ~/.openclaw/plugins/hypermem/bin/hypermem-status.mjs --master
+```
+
+For isolated validation, test the packed artifact from a temp directory:
 
 ```bash
 TMP=$(mktemp -d)
+npm pack
 npm --prefix "$TMP" init -y
 npm --prefix "$TMP" install ./psiclawops-hypermem-*.tgz
 node "$TMP/node_modules/@psiclawops/hypermem/scripts/install-runtime.mjs" "$TMP/runtime"
@@ -184,3 +194,32 @@ The staged runtime must contain:
 | `memory_search` bypasses HyperMem | memory slot not set or memory plugin not loaded | set `plugins.slots.memory hypermem`, restart, verify plugins list |
 | status tool reports missing data dir | gateway has not initialized HyperMem yet | restart after wiring and send one agent message |
 | model audit flags unknown context window | active model needs explicit override | add `contextWindowOverrides` in HyperMem config |
+
+
+### Production-shaped runtime validation
+
+HyperMem development validation must install the packed package into OpenClaw's managed plugin directory before claiming a runtime fix is live. Do not rely on a repo symlink, global npm link, or copied `dist/` files as production evidence.
+
+Required loop:
+
+```bash
+npm run build:all
+npm pack
+node scripts/install-packed-runtime.mjs ./psiclawops-hypermem-<version>.tgz
+systemctl --user restart openclaw-gateway
+node bin/hypermem-status.mjs --master
+```
+
+The health check must verify the managed install at `~/.openclaw/plugins/hypermem`, not the working tree.
+
+### Referenced-noise maintenance debt
+
+`hypermem-status --master` reports referenced-noise debt under `## Maintenance`. This is low-signal message content that cannot be deleted by ordinary noise sweep because it is still a foreign-key target, usually through `messages.parent_id`.
+
+Operators can run the conservative repair path:
+
+```bash
+node bin/hypermem-status.mjs --master --repair-referenced-noise --repair-limit 100
+```
+
+The repair only collapses noise nodes blocked solely by `messages.parent_id`. It reparents children to the deleted node's parent, decrements subtree depth, and rolls back the whole batch if `PRAGMA foreign_key_check` reports any violation. Context and composition snapshot heads are detected but not repaired by this pass.

package/docs/ROADMAP.md

@@ -12,15 +12,15 @@ For shipped capabilities, see [CHANGELOG.md](../CHANGELOG.md) and [ARCHITECTURE.
 ## Current state
 
 ### Released
-- Current release: **0.9.0** — adaptive context lifecycle. Published 2026-04-25.
-  - Internal `main`: `8f805b8`
-  - Public `main`: `25dd469`
-  - Public tag `v0.9.0`: pushed
-  - Public CI: green (`24942512824`)
-  - GitHub Release: https://github.com/PsiClawOps/hypermem/releases/tag/v0.9.0
-  - npm at 0.9.0: `@psiclawops/hypermem`, `@psiclawops/hypercompositor`, `@psiclawops/hypermem-memory`
-  - New install validator shipped: `hypermem-doctor`
-- Previous release: **0.8.6**
+- Current release candidate: **0.9.4** — recall surface and install hardening. Prepared 2026-04-28.
+  - Internal `main`: `09c639d5` plus release-document updates
+  - Public `main`: pending publication sync
+  - Public tag `v0.9.4`: pending publication
+  - Public CI: pending publication
+  - GitHub Release: pending publication
+  - npm at 0.9.4: pending publication for `@psiclawops/hypermem`, `@psiclawops/hypercompositor`, and `@psiclawops/hypermem-memory`
+  - Install validator: `hypermem-doctor` plus packed-artifact fresh-install smoke gate
+- Previous release: **0.9.3**
 
 ### Landed on `main` after 0.8.6
 In the order work actually landed:
@@ -149,7 +149,17 @@ Closed fix summary:
 - repairs long-lived `knowledge.visibility` schema drift;
 - covers UUID topic ids, duplicate same-name session topic fragments, content-detector fallback, no-match skips, legacy direct-id fallback, schema-drift repair, unchanged-content watermark refresh, and idempotent upsert.
 
-## 3. Contradiction-aware decay
+## 3. HyperMem 0.9.4 recall surface hardening
+Status: **READY FOR PUBLICATION GATES.** Internal implementation is complete and release validation is green. Public sync, npm publish, GitHub release, and public CI remain as publication steps.
+
+0.9.4 corrects the 0.8.x → 0.9.0 over-rotation toward budget headroom and hardens the install path that external testers use. One release, four streams:
+
+- **Warming gradient enrichment.** Bootstrap, warmup, and steady lifecycle bands now carry larger warming fractions. Smart recall widens for bootstrap/warmup, `/new`, and topic shift. AfterTurn trim protects warming floors until pressure reaches `elevated`, and warmup uses shaped decay driven by topic-bearing turn count.
+- **Adjacency-aware preservation.** Fused retrieval now boosts recent antecedents while filtering system and heartbeat traffic. Compose eviction protects the literal antecedent of the current user turn under non-critical pressure.
+- **Default install settings refresh.** The runtime installer ships recall-friendly defaults, stages `hypermem-doctor` and `hypermem-bench`, preserves existing config, supports CI-safe flags, surfaces legacy `agents.defaults.memorySearch`, and keeps plugin dependencies compatible with the 0.9.4 line.
+- **Install gap-class prevention.** The fresh-install smoke gate packs the npm artifact, installs without a source checkout, verifies no-Ollama messaging, skip-mode staging, config preservation, and captures durable failure artifacts for postmortem reuse.
+
+## 4. Contradiction-aware decay
 After 0.9.0 lifecycle work:
 - accelerate decay for superseded facts
 - reduce stale architectural facts surviving long after pivots
@@ -157,7 +167,7 @@ After 0.9.0 lifecycle work:
 
 This is a quality and correctness improvement, not a release blocker.
 
-## 4. Turn DAG Phase 5 storage and performance
+## 5. Turn DAG Phase 5 storage and performance
 After the above correctness and continuity work:
 - content-addressed blob store for repeated large payloads
 - zstd compression for large message bodies
@@ -178,7 +188,8 @@ Phase 5 stays important, but it is not the next sprint until the higher-priority
 | Topic synthesis bridge defect | ✅ CLOSED | Fixed in `8b9f928`; CI `24917765384` passed. |
 | Adaptive context lifecycle (0.9.0) | ✅ SHIPPED | Released 2026-04-25 as 0.9.0. Threshold tuning remains deferred until future live evidence warrants it. |
 | Vector coverage repair gate | ✅ CLOSED | `embed-existing` now supports knowledge and eligibility-aware coverage reporting; production vectors reached facts 113/113, knowledge 85/85, episodes 30,121/30,121 eligible coverage on 2026-04-24. |
-| Contradiction-aware decay | 🟡 OPEN | Prevents stale-fact poisoning after architectural pivots. |
+| Recall surface hardening (0.9.4) | ✅ READY | Internal implementation and validation gates are green; public sync, npm publish, release page, and public CI remain. |
+| Contradiction-aware decay | 🟡 OPEN | Prevents stale-fact poisoning after architectural pivots. Sequenced after the 0.9.4 publication closeout. |
 | Turn DAG Phase 5 storage/perf | 🟡 OPEN | Important, but later than the items above. |
 | Warm-restore gate closeout | ✅ DONE | Tracked gate-closeout scope is complete; reopen only for a new concrete defect or measurement gap. |
 
@@ -224,6 +235,8 @@ Their useful content is now represented here.
 
 ---
 
+| OpenClaw 2026.4.26 plugin build metadata refresh | 🔲 TRIAGE | After the 4.26 compatibility patch lands and is tested against the installed runtime, update HyperCompositor and HyperMem package build metadata from OpenClaw 2026.4.9 / SDK 2026.4.12 to the verified 2026.4.26 values. Keep this short-term so persisted plugin registry diagnostics do not report stale package provenance. |
+
 ## Historical triage appendix
 
 This appendix is the cleanup pass for older improvement lists that were still floating around in the repo and workspace.

package/docs/TUNING.md

@@ -1,6 +1,6 @@
 # hypermem Tuning Guide
 
-Configuration reference for operators and agents. All settings are optional. The recommended install path writes a starter `config.json` with an explicit lightweight embedding choice and a declarative baseline compositor profile. Tune from that verified baseline, not from guesswork.
+Configuration reference for operators and agents. All settings are optional. The recommended install path writes a starter `config.json` with the 0.9.4 recall-friendly standard profile: local Ollama embeddings by default, protected warming, adjacency preservation, and conservative turn budgeting. Tune from that verified baseline, not from guesswork.
 
 Config lives in `~/.openclaw/hypermem/config.json` (takes effect on gateway restart) or is passed programmatically via `HyperMem.create()`:
 
@@ -114,13 +114,38 @@ Estimated context per turn: **12–35k tokens** on a 200k model (lower on smalle
 
 ### Standard setup
 
-The default out-of-the-box configuration. All memory layers active with balanced caps. Good for most single-agent deployments.
+The default out-of-the-box configuration. All memory layers are active with 0.9.4 recall preservation turned on. Good for most single-agent deployments and the right baseline for external install testing.
 
 ```json
 {
+  "embedding": {
+    "provider": "ollama",
+    "model": "nomic-embed-text",
+    "dims": 768,
+    "dimensions": 768,
+    "ollamaUrl": "http://localhost:11434"
+  },
   "compositor": {
-    "budgetFraction": 0.703,
+    "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.5,
+    "warmHistoryBudgetFraction": 0.45,
     "maxFacts": 28,
     "maxHistoryMessages": 250,
     "maxCrossSessionContext": 0,
@@ -129,13 +154,29 @@ The default out-of-the-box configuration. All memory layers active with balanced
     "hyperformProfile": "standard"
   },
   "indexer": {
+    "enabled": true,
     "factExtractionMode": "tiered",
     "periodicInterval": 300000
   }
 }
 ```
 
-Estimated context per turn: **35–80k tokens** on a 200k model. This is what ships if you don't touch the config.
+Estimated context per turn: **35–80k tokens** on a 200k model. This is what `hypermem-install` writes when no existing config is present. Existing config files are preserved, so run `hypermem-doctor --fix-plan` after upgrades to see whether older installs are missing the 0.9.4 recall-surface knobs.
+
+### 0.9.4 recall preservation knobs
+
+These settings prevent the regression class that motivated 0.9.4: the direct antecedent or topic-bearing warm context being trimmed away while the system still had enough usable budget.
+
+| Knob | Default | What it protects | Health signal |
+|---|---:|---|---|
+| `compositor.turnBudget.budgetFraction` | `0.6` | Keeps the active turn budget below the old over-warming posture | `hypermem-status --master` recall surface line |
+| `compositor.turnBudget.minContextFraction` | `0.18` | Guarantees a minimum context allocation on constrained windows | `hypermem-doctor --fix-plan` |
+| `compositor.warming.protectedFloorEnabled` | `true` | Prevents afterTurn trim from evicting bootstrap/warmup floor content before elevated pressure | `node test/afterturn-protected-floor.mjs` |
+| `compositor.warming.shapedWarmupDecay` | `true` | Uses topic-bearing turn count instead of blind fixed-turn decay | `node test/adaptive-lifecycle.mjs` |
+| `compositor.adjacency.enabled` | `true` | Boosts recent antecedents during fused retrieval | `node test/hybrid-retrieval.mjs` |
+| `compositor.adjacency.evictionGuardTokenCap` | `4000` | Caps the literal antecedent guard so it cannot consume the whole budget | `node test/compositor.mjs` |
+
+Do not tune these off to save tokens until you have evidence. Lower `maxFacts`, `maxCrossSessionContext`, or wiki caps first. Disabling adjacency or protected warming is a correctness trade, not a cost preset.
 
 ### Full performance setup
 

package/install.sh

@@ -166,7 +166,7 @@ stage_runtime() {
 write_minimal_config_if_missing() {
   echo -e "\n${BOLD}  Config check${NC}"
   if $DRY_RUN; then
-    dryrun "would preserve existing config or write lightweight starter config: $CONFIG_FILE"
+    dryrun "would preserve existing config or write recall-friendly starter config: $CONFIG_FILE"
     return
   fi
 
@@ -175,66 +175,11 @@ write_minimal_config_if_missing() {
     return
   fi
 
+  local default_config="$INSTALL_DIR/node_modules/@psiclawops/hypermem/assets/default-config.json"
+  [[ -f "$default_config" ]] || die "missing packaged default config: $default_config"
   mkdir -p "$(dirname "$CONFIG_FILE")"
-  cat > "$CONFIG_FILE" <<'JSON'
-{
-  "contextWindowSize": 128000,
-  "contextWindowReserve": 0.25,
-  "deferToolPruning": false,
-  "verboseLogging": false,
-  "contextWindowOverrides": {},
-  "warmCacheReplayThresholdMs": 120000,
-  "subagentWarming": "light",
-  "embedding": {
-    "provider": "none"
-  },
-  "compositor": {
-    "budgetFraction": 0.55,
-    "reserveFraction": 0.25,
-    "historyFraction": 0.4,
-    "memoryFraction": 0.4,
-    "defaultTokenBudget": 90000,
-    "maxHistoryMessages": 500,
-    "maxFacts": 25,
-    "maxExpertisePatterns": 6,
-    "maxCrossSessionContext": 4000,
-    "maxTotalTriggerTokens": 4000,
-    "maxRecentToolPairs": 3,
-    "maxProseToolPairs": 10,
-    "warmHistoryBudgetFraction": 0.27,
-    "contextWindowReserve": 0.25,
-    "dynamicReserveTurnHorizon": 5,
-    "dynamicReserveMax": 0.5,
-    "dynamicReserveEnabled": true,
-    "keystoneHistoryFraction": 0.15,
-    "keystoneMaxMessages": 12,
-    "keystoneMinSignificance": 0.5,
-    "targetBudgetFraction": 0.50,
-    "enableFOS": true,
-    "enableMOD": true,
-    "hyperformProfile": "standard",
-    "wikiTokenCap": 500,
-    "zigzagOrdering": true
-  },
-  "eviction": {
-    "enabled": true,
-    "imageAgeTurns": 2,
-    "toolResultAgeTurns": 4,
-    "minTokensToEvict": 200,
-    "keepPreviewChars": 120
-  },
-  "maintenance": {
-    "periodicInterval": 300000,
-    "maxActiveConversations": 5,
-    "recentConversationCooldownMs": 30000,
-    "maxCandidatesPerPass": 200
-  },
-  "vectorStore": {
-    "enabled": false
-  }
-}
-JSON
-  success "lightweight starter config written: $CONFIG_FILE"
+  cp "$default_config" "$CONFIG_FILE"
+  success "recall-friendly starter config written: $CONFIG_FILE"
 }
 
 verify_stage() {

package/memory-plugin/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * HyperMem Memory Plugin
+ *
+ * Thin adapter that bridges HyperMem's retrieval capabilities into
+ * OpenClaw's memory slot contract (`kind: "memory"`).
+ *
+ * The context engine plugin (hypercompositor) owns the full lifecycle:
+ * ingest, assemble, compact, afterTurn, bootstrap, dispose.
+ *
+ * This plugin owns the memory slot contract:
+ * - registerMemoryCapability() with runtime + publicArtifacts
+ * - memory_search tool backing via MemorySearchManager
+ * - Public artifacts for memory-wiki bridge
+ *
+ * Both plugins share the same HyperMem singleton (loaded from repo dist).
+ */
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    configSchema: import("openclaw/plugin-sdk").OpenClawPluginConfigSchema;
+    register: NonNullable<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition["register"]>;
+} & Pick<import("openclaw/plugin-sdk/plugin-entry").OpenClawPluginDefinition, "kind" | "reload" | "nodeHostCommands" | "securityAuditCollectors">;
+export default _default;