@psiclawops/hypermem 0.8.2 → 0.8.4

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to hypermem are documented here.
 
+## 0.8.4 — compaction fence fix, install-path fixes, zod runtime packaging
+
+- **Compaction fence tail preservation fixed.** The recent-tail preservation fix is included so compaction no longer drops the protected recent tail during fence advancement.
+- **`afterTurn` token count persistence fixed.** Token accounting now persists correctly after turn completion, which keeps follow-on pressure and compaction decisions honest.
+- **Registry install docs corrected and hardened.** Installation guidance now fixes the shipped `ocplatform` typo, clarifies older package behavior around missing `install:runtime`, improves `plugins.load.paths` quoting, and removes the dangerous overwrite-style `plugins.allow` example in favor of merge-safe guidance.
+- **Install tracks clarified.** Docs now distinguish source-clone plugin setup from older npm package behavior so first-run operators do not follow the wrong path.
+- **`zod` now ships for plugin runtime use.** The published package now includes the runtime `zod` dependency required by the HyperCompositor plugin, fixing `Cannot find module 'zod'` on package-based installs.
+
 ## 0.8.2 — npm packaging & install path clarity
 
 - **INSTALL.md and CHANGELOG.md now ship in the npm package.** Previously missing from `package.json` `files` array, so `npm pack` / `npm publish` excluded them. Users installing from the registry now get the full install guide without cloning the repo.

package/INSTALL.md

@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - **Node.js 22+** (uses built-in `node:sqlite`)
-- **OpenClaw** must already be installed, onboarded, and running. The plugin install assumes a working OpenClaw home with a valid `openclaw.json` and a gateway that can restart.
+- **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.
 - **Disk space:** allow at least 2 GB free. Plugin builds pull OpenClaw as a dev dependency.
 
 **Verify before starting:**
@@ -17,21 +17,22 @@ If `gateway status` shows "disabled" or "not configured", complete OpenClaw onbo
 
 ## Quick Start
 
-> **Disk space:** plugin installs pull OpenClaw as a dev dependency. Allow at least 2 GB free before starting.
->
-> **Prerequisites:** OpenClaw must be installed and onboarded before this step. Run `openclaw gateway status` to confirm. If the gateway is not configured, complete OpenClaw setup first.
->
-> **Production runtime path:** install the built runtime payload into `~/.openclaw/plugins/hypermem`. Do not point production at `/tmp` or at your development repo clone.
+> **Release note:** if the npm package you installed does not contain `hypermem-install` or `install:runtime`, you are on an older public release. Use the source-clone path in this guide or wait for `0.8.4+`.
+
+```bash
+npm install @psiclawops/hypermem
+npx hypermem-install
+```
+
+`hypermem-install` stages the plugin runtime into `~/.openclaw/plugins/hypermem`. It does **not** modify your OpenClaw config and does **not** restart the gateway.
+
+> **Prerequisites:** OpenClaw must be installed and onboarded. Run `openclaw gateway 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 them blindly.
+> **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 set the embedding provider:
 
 ```bash
-git clone https://github.com/PsiClawOps/hypermem.git
-cd hypermem
-npm install && npm run build
-npm --prefix plugin install && npm --prefix plugin run build   # ~1 min on a clean machine
-npm --prefix memory-plugin install && npm --prefix memory-plugin run build
-npm run install:runtime
 mkdir -p ~/.openclaw/hypermem
 cat > ~/.openclaw/hypermem/config.json <<'JSON'
 {
@@ -42,19 +43,43 @@ cat > ~/.openclaw/hypermem/config.json <<'JSON'
 JSON
 ```
 
-`install:runtime` stages the built plugin files into `~/.openclaw/plugins/hypermem`. It does **not** modify your OpenClaw config. The commands below wire the plugins manually.
-
 Wire both plugins into OpenClaw:
 
+**Step 1: Check your existing config (mandatory — do this before wiring).**
+
 ```bash
-openclaw config set plugins.load.paths "[\"$HOME/.openclaw/plugins/hypermem/plugin\",\"$HOME/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+openclaw config get plugins.load.paths
+openclaw config get plugins.allow
+```
+
+Note any existing values. You must include them in the commands below.
+
+**Step 2: Wire plugins.**
+
+```bash
+# Wire plugin load paths — use a variable to avoid shell quoting problems, then merge if needed:
+HYPERMEM_PATHS="[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]"
+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 config set plugins.allow '["hypercompositor","hypermem"]' --strict-json
+
+# 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.
+# If it returns an array, copy that array and append "hypercompositor" and "hypermem".
+openclaw config set plugins.allow '["existing-plugin","hypercompositor","hypermem"]' --strict-json
+```
+
+> **⚠️  Merge, don't replace.** Do not set `plugins.allow` to only `['hypercompositor','hypermem']`. That can disable bundled CLI surfaces and channel plugins. If your system already has a non-empty allowlist, append the HyperMem plugin ids to that existing array.
+
+**Step 3: Restart.**
+
+```bash
 openclaw gateway restart
 ```
 
-The repo clone is for build and release work. OpenClaw should load the installed runtime payload from `~/.openclaw/plugins/hypermem/`.
+OpenClaw loads the plugin runtime from `~/.openclaw/plugins/hypermem/`.
 
 ### Verification checkpoints
 
@@ -342,7 +367,9 @@ Then:
 
 ## Installation Steps
 
-### Step 1 — Clone and build
+### Step 1 — Source Build (contributors)
+
+> **Most users should use the npm Quick Start above.** This section is for contributors or users who need to modify HyperMem source.
 
 ```bash
 git clone https://github.com/PsiClawOps/hypermem.git
@@ -351,7 +378,7 @@ npm install
 npm run build
 ```
 
-Build both plugins, then install the runtime payload into OpenClaw's durable plugin directory:
+Build both plugins, then install the runtime payload into 's durable plugin directory:
 
 ```bash
 npm --prefix plugin install && npm --prefix plugin run build
@@ -365,32 +392,31 @@ Verify:
 npm test
 ```
 
-The full suite takes 30–60 seconds. When complete, output ends with `ALL N TESTS PASSED ✅`. If you see `ENOSPC`, free up disk space and retry.
+The full suite takes 30–60 seconds. When complete, output ends with `N passed, 0 failed`. If you see `ENOSPC`, free up disk space and retry.
 
 ### Step 2 — Wire the plugins
 
 Use the OpenClaw CLI. **Do not edit `openclaw.json` directly.**
 
 ```bash
-# Add plugin load paths
-openclaw config set plugins.load.paths "[\"$HOME/.openclaw/plugins/hypermem/plugin\",\"$HOME/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+# Check existing values first — merge if non-empty:
+openclaw config get plugins.load.paths
+openclaw config get plugins.allow
 
-# Set the context engine slot
-openclaw config set plugins.slots.contextEngine hypercompositor
+# Wire plugin load paths (use a variable to avoid shell quoting problems):
+HYPERMEM_PATHS="[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]"
+openclaw config set plugins.load.paths "$HYPERMEM_PATHS" --strict-json
 
-# Set the memory slot
+# Set the context engine and memory slots:
+openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
 
-# Allow both plugins
-openclaw config set plugins.allow '["hypercompositor","hypermem"]' --strict-json
+# 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.
+openclaw config set plugins.allow '["existing-plugin","hypercompositor","hypermem"]' --strict-json
 ```
 
-If you already have entries in `plugins.allow` or `plugins.load.paths`, merge rather than replace. Check current values:
-
-```bash
-openclaw config get plugins.allow
-openclaw config get plugins.load.paths
-```
+> **⚠️  Merge, don't replace.** Never replace a working `plugins.allow` list with only HyperMem entries. If `plugins.allow` is unset or empty, leave it alone.
 
 ### Step 3 — Choose embedding provider
 
@@ -422,7 +448,7 @@ Expected:
 [hypermem:compose] agent=main triggers=0 fallback=true facts=3 semantic=2 ...
 ```
 
-Full health check (run from the repo clone directory):
+Full health check (run from the repo clone directory — `bin/` is a relative path):
 
 ```bash
 node bin/hypermem-status.mjs              # full dashboard
@@ -430,6 +456,8 @@ node bin/hypermem-status.mjs --health     # health checks only (exit 1 on failur
 ```
 
 > **Note:** The health check requires the data directory to exist. It is created on first gateway restart with the plugin active. Run the `openclaw logs` check first to confirm initialization, then run the health check.
+>
+> **Empty results on fresh installs are normal.** If the health check shows `facts=0`, `episodes=0`, or `no agent messages.db found`, that means the install worked but no conversations have happened yet. Data populates after real agent sessions.
 
 If the plugin didn't load:
 
@@ -549,23 +577,66 @@ npm --prefix memory-plugin run build
 
 ---
 
-## OpenClaw Settings (Optional Tuning)
+## OpenClaw Platform Settings
+
+HyperMem manages its own context pressure, memory injection, and compaction. Several OpenClaw defaults conflict with this or are too conservative for memory-augmented agents. Apply these after plugin installation, before the gateway restart.
+
+### Disable OpenClaw context pruning (required)
+
+OpenClaw has a built-in context pruning system (`cache-ttl` mode) that independently truncates and clears tool results from the message history based on time and context-window ratio thresholds. When HyperMem is active, these two systems fight each other: OpenClaw prunes tool results to free space, then HyperMem injects context that refills it, triggering aggressive compaction on the next turn. The result is unpredictable amnesia.
+
+Disable OpenClaw's pruning and let HyperMem handle context pressure exclusively:
+
+```bash
+openclaw config set agents.defaults.contextPruning.mode off
+```
+
+### Startup context (recommended)
 
-These are optional. hypermem works with OpenClaw defaults, but these changes reduce unnecessary overhead.
+Controls how much daily memory context agents receive on session start. The defaults are very conservative (2 days, 2800 chars total). For memory-augmented agents, increase these so agents wake up with meaningful context:
+
+```bash
+openclaw config set agents.defaults.startupContext.dailyMemoryDays 4 --strict-json
+openclaw config set agents.defaults.startupContext.maxFileChars 4000 --strict-json
+openclaw config set agents.defaults.startupContext.maxTotalChars 12000 --strict-json
+openclaw config set agents.defaults.startupContext.maxFileBytes 32768 --strict-json
+```
+
+This gives agents 4 days of working memory at startup (~12k chars total). Still under 10% of a 128k context window.
+
+### Bootstrap max chars (recommended)
+
+Controls the maximum size of bootstrap files (AGENTS.md, SOUL.md, etc.) injected on session start. The default (12000) is tight for agents with governance rules, tool references, and identity docs:
+
+```bash
+openclaw config set agents.defaults.bootstrapMaxChars 20000 --strict-json
+```
 
-### Lower OpenClaw's compaction threshold
+### Compaction safety net
 
-hypermem owns compaction. OpenClaw's default fires at 24K reserved tokens, which races hypermem's budget management:
+OpenClaw's built-in compaction (`safeguard` mode) serves as a last-resort safety net. Keep it enabled but tuned so it only fires when HyperMem's own pressure management is insufficient:
 
 ```bash
-openclaw config set agents.defaults.compaction.reserveTokens 1000 --strict-json
+openclaw config set agents.defaults.compaction.mode safeguard
+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
 ```
 
-This makes OpenClaw's compaction a last-resort safety net that never fires in normal operation.
+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.
+
+### LLM idle timeout
+
+Tool-heavy sessions with large outputs can stall during streaming. Raise the idle timeout from the default (120s):
+
+```bash
+openclaw config set agents.defaults.llm.idleTimeoutSeconds 300 --strict-json
+```
 
 ### Tighter session store retention
 
-With hypermem active, SQLite is the durable record. JSONL transcripts provide no memory benefit:
+With HyperMem active, SQLite is the durable record. JSONL transcripts provide no memory benefit:
 
 ```bash
 openclaw config set sessions.maintenance.pruneAfter "14d"
@@ -744,6 +815,10 @@ The background indexer runs on a 5-minute interval. After the first cycle, check
 
 Expected on fresh installs. Facts and episodes accumulate over real conversations. After a few sessions these numbers grow. Workspace files can be seeded manually via the seeder API.
 
+**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.
+
 **Plugin not found**
 
 Confirm the installed runtime artifacts exist:
@@ -797,4 +872,22 @@ Data in `~/.openclaw/hypermem/` is untouched. Re-enable by switching back.
 
 ---
 
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `HYPERMEM_DATA_DIR` | `~/.openclaw/hypermem` | Override the data directory where hypermem stores `library.db`, per-agent `messages.db` files, and `vectors.db`. Useful when you want data on a separate volume, need isolated test data dirs, or run multiple hypermem instances. The directory is created automatically if it does not exist. |
+
+Example:
+
+```bash
+# Point hypermem at a different data location:
+export HYPERMEM_DATA_DIR=/mnt/data/hypermem
+openclaw gateway 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.
+
+---
+
 _Questions or issues: file against [the repo](https://github.com/PsiClawOps/hypermem) or ask in `#hypermem`._

package/README.md

@@ -8,10 +8,20 @@
 
 hypermem is a SQLite-backed runtime context engine for OpenClaw agents.
 
+**Quick install** (interactive, detects hardware, writes config):
+
+```bash
+npm install @psiclawops/hypermem && npx hypermem-install
+```
+
+Or via the shell installer:
+
 ```bash
 curl -fsSL https://raw.githubusercontent.com/PsiClawOps/hypermem/main/install.sh | bash
 ```
 
+Or install manually via `npm install @psiclawops/hypermem` — see [Installation](#installation) for plugin wiring, embedding setup, and step-by-step paths.
+
 
 ---
 
@@ -376,7 +386,7 @@ Slot-level budget allocation is shown in the [hypercompositor diagram](#what-the
 
 ## Requirements
 
-**Current release: hypermem 0.8.1.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
+**Current release: hypermem 0.8.2.** Changelog: [CHANGELOG.md](./CHANGELOG.md)
 
 | Requirement | Version | Notes |
 |---|---|---|
@@ -389,7 +399,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.8.1'
+  ENGINE_VERSION,        // '0.8.2'
   MIN_NODE_VERSION,      // '22.0.0'
   SQLITE_VEC_VERSION,    // '0.1.9'
   MAIN_SCHEMA_VERSION,   // 10 (messages.db)
@@ -439,6 +449,8 @@ That's it. No gateway, no plugins, no config files. See [API](#api) for the full
 
 ### OpenClaw plugin install (from source)
 
+> **Release note:** if the npm package you installed does not contain `install:runtime`, you are on an older public release. Use the source-clone path below or wait for `0.8.4+`.
+
 ```bash
 git clone https://github.com/PsiClawOps/hypermem.git
 cd hypermem
@@ -448,7 +460,7 @@ npm --prefix memory-plugin install && npm --prefix memory-plugin run build
 npm run install:runtime
 ```
 
-`install:runtime` stages the runtime payload into `~/.openclaw/plugins/hypermem` and prints the exact config commands to wire the plugins. Before running them, create the data directory and config:
+`install:runtime` stages the runtime payload into `~/.openclaw/plugins/hypermem` and prints the exact config commands to wire the plugins. It does not finish wiring automatically. Before running them, create the data directory and config:
 
 ```bash
 mkdir -p ~/.openclaw/hypermem
@@ -465,15 +477,33 @@ This sets lightweight mode (FTS5 keyword search, no embedding provider needed).
 
 Wire the plugins into OpenClaw:
 
+> **⚠️  Merge, don't overwrite.** If you already have values in `plugins.load.paths` or `plugins.allow`, check them first and include your existing entries alongside the new ones. Replacing the list drops whatever was there before.
+>
+> ```bash
+> openclaw config get plugins.allow
+> openclaw config get plugins.load.paths
+> ```
+
 ```bash
-openclaw config set plugins.load.paths "[\"$HOME/.openclaw/plugins/hypermem/plugin\",\"$HOME/.openclaw/plugins/hypermem/memory-plugin\"]" --strict-json
+# Use a variable to avoid shell quote-escaping issues with $HOME:
+HYPERMEM_PATHS="[\"${HOME}/.openclaw/plugins/hypermem/plugin\",\"${HOME}/.openclaw/plugins/hypermem/memory-plugin\"]"
+openclaw config set plugins.load.paths "$HYPERMEM_PATHS" --strict-json
+# If you have existing load paths, merge them into the array in HYPERMEM_PATHS.
+
 openclaw config set plugins.slots.contextEngine hypercompositor
 openclaw config set plugins.slots.memory hypermem
-openclaw config set plugins.allow '["hypercompositor","hypermem"]' --strict-json
+
+# 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.
+# If it returns an array, copy that array and append "hypercompositor" and "hypermem".
+openclaw config set plugins.allow '["existing-plugin","hypercompositor","hypermem"]' --strict-json
+
 openclaw gateway restart
 ```
 
-Verify (run from the repo clone directory):
+Do **not** replace a working `plugins.allow` list with only `['hypercompositor','hypermem']`. That can disable bundled CLI surfaces and channel plugins.
+
+Verify (run these commands from the repo clone directory — `bin/` is a relative path):
 
 ```bash
 openclaw plugins list                    # hypercompositor and hypermem should show as loaded

package/dist/compaction-fence.d.ts

@@ -41,6 +41,14 @@ export interface CompactionEligibility {
     /** The fence itself */
     fence: CompactionFence | null;
 }
+export interface UpdateCompactionFenceOptions {
+    /**
+     * Minimum number of most-recent non-system messages that must remain above
+     * the fence. Prevents compaction from fencing off the live conversational
+     * tail under pressure.
+     */
+    minTailMessages?: number;
+}
 /**
  * Add the compaction_fences table to an existing messages.db.
  * Idempotent — safe to call on every startup.
@@ -57,7 +65,7 @@ export declare function ensureCompactionFenceSchema(db: DatabaseSync): void;
  * This prevents a short compose window from accidentally exposing
  * already-compacted messages.
  */
-export declare function updateCompactionFence(db: DatabaseSync, conversationId: number, oldestVisibleMessageId: number): void;
+export declare function updateCompactionFence(db: DatabaseSync, conversationId: number, oldestVisibleMessageId: number, opts?: UpdateCompactionFenceOptions): void;
 /**
  * Get the current compaction fence for a conversation.
  * Returns null if no fence has been set (meaning: no compaction allowed).

package/dist/compaction-fence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compaction-fence.d.ts","sourceRoot":"","sources":["../src/compaction-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uBAAuB;IACvB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/B;AAID;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAQlE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,sBAAsB,EAAE,MAAM,GAC7B,IAAI,CAqBN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,eAAe,GAAG,IAAI,CAYxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,qBAAqB,CAwCvB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAY,GAClB,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B7E"}
+{"version":3,"file":"compaction-fence.d.ts","sourceRoot":"","sources":["../src/compaction-fence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,+DAA+D;IAC/D,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,uBAAuB;IACvB,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAQlE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,sBAAsB,EAAE,MAAM,EAC9B,IAAI,GAAE,4BAAiC,GACtC,IAAI,CAgDN;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,eAAe,GAAG,IAAI,CAYxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,GACrB,qBAAqB,CAwCvB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,YAAY,EAChB,cAAc,EAAE,MAAM,EACtB,KAAK,GAAE,MAAY,GAClB,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CA8B7E"}

package/dist/compaction-fence.js

@@ -48,17 +48,38 @@ export function ensureCompactionFenceSchema(db) {
  * This prevents a short compose window from accidentally exposing
  * already-compacted messages.
  */
-export function updateCompactionFence(db, conversationId, oldestVisibleMessageId) {
+export function updateCompactionFence(db, conversationId, oldestVisibleMessageId, opts = {}) {
     const now = new Date().toISOString();
+    const minTailMessages = typeof opts.minTailMessages === 'number' && Number.isFinite(opts.minTailMessages)
+        ? Math.max(1, Math.floor(opts.minTailMessages))
+        : undefined;
+    const oldestRecentRow = minTailMessages != null
+        ? db.prepare(`
+          SELECT id FROM messages
+          WHERE conversation_id = ?
+            AND role != 'system'
+          ORDER BY message_index DESC
+          LIMIT 1 OFFSET ?
+        `).get(conversationId, minTailMessages - 1) ?? db.prepare(`
+          SELECT id FROM messages
+          WHERE conversation_id = ?
+            AND role != 'system'
+          ORDER BY message_index ASC
+          LIMIT 1
+        `).get(conversationId)
+        : undefined;
+    const clampedMessageId = oldestRecentRow
+        ? Math.min(oldestVisibleMessageId, oldestRecentRow.id)
+        : oldestVisibleMessageId;
     const existing = db.prepare('SELECT fence_message_id FROM compaction_fences WHERE conversation_id = ?').get(conversationId);
     if (!existing) {
         // First fence for this conversation
-        db.prepare('INSERT INTO compaction_fences (conversation_id, fence_message_id, updated_at) VALUES (?, ?, ?)').run(conversationId, oldestVisibleMessageId, now);
+        db.prepare('INSERT INTO compaction_fences (conversation_id, fence_message_id, updated_at) VALUES (?, ?, ?)').run(conversationId, clampedMessageId, now);
         return;
     }
     // Monotone progress: fence only moves forward
-    if (oldestVisibleMessageId > existing.fence_message_id) {
-        db.prepare('UPDATE compaction_fences SET fence_message_id = ?, updated_at = ? WHERE conversation_id = ?').run(oldestVisibleMessageId, now, conversationId);
+    if (clampedMessageId > existing.fence_message_id) {
+        db.prepare('UPDATE compaction_fences SET fence_message_id = ?, updated_at = ? WHERE conversation_id = ?').run(clampedMessageId, now, conversationId);
     }
 }
 /**

package/dist/compositor.js

@@ -2495,7 +2495,7 @@ export class Compositor {
             `).get(conversation.id, historyMsgCount - 1);
                         if (oldestIncluded) {
                             ensureCompactionFenceSchema(db);
-                            updateCompactionFence(db, conversation.id, oldestIncluded.id);
+                            updateCompactionFence(db, conversation.id, oldestIncluded.id, { minTailMessages: 8 });
                         }
                     }
                 }

package/docs/API_STABILITY.md

@@ -0,0 +1,33 @@
+# API Stability — hypermem
+
+## Public API (frozen at 0.5.0)
+
+The following four methods are the stable public surface of hypermem. They are
+frozen as of 0.5.0. Breaking changes require a 1.0.0 semver bump — no exceptions.
+
+| Method | Signature | Description |
+|---|---|---|
+| `create` | `create(config: HypermemConfig): HypermemInstance` | Initialize a hypermem instance |
+| `record` | `record(agentId, sessionKey, message): Promise<void>` | Store a message in the session store |
+| `compose` | `compose(agentId, sessionKey, opts?): Promise<ComposedContext>` | Assemble context for a prompt |
+| `close` | `close(): Promise<void>` | Gracefully shut down, flush, close DB connections |
+
+## What "frozen" means
+
+- No argument removal or rename
+- No return type narrowing that breaks existing consumers
+- No behavior change that breaks existing consumers without a deprecation cycle
+- Additive changes (new optional args, new fields in return type) are allowed
+
+## Internal APIs
+
+Everything else — `FactStore`, `CacheLayer`, `Compositor`, `HybridRetrieval`,
+`DreamingPromoter`, etc. — is internal and may change between minor versions.
+These are exported for advanced use but carry no stability guarantee until 1.0.
+
+## Versioning policy
+
+| Version range | Policy |
+|---|---|
+| `0.x.y` | Public API frozen, internal APIs may change on minor bumps |
+| `1.0.0+` | Full semver — breaking changes require major bump |

package/docs/KNOWN_LIMITATIONS.md

@@ -0,0 +1,35 @@
+# Known Limitations — HyperMem 0.8.0
+
+## Global-scope fact write authorization
+
+Facts written with `scope='global'` are readable fleet-wide at L4 priority. The write path has no authorization gate — any agent with access to the HyperMem API can write a global-scope fact.
+
+**Impact:** In a trusted single-operator deployment (the intended target), this is acceptable. All agents are operator-controlled and share the same trust boundary.
+
+**Planned fix:** Introduce a write-authority model that gates global-scope writes to designated agents (council seats or explicitly allowlisted agent IDs). See [docs/ROADMAP.md](ROADMAP.md).
+
+**Workaround:** Restrict HyperMem API access to trusted agents only. Do not expose the API to untrusted external agents.
+
+## Cross-agent org registry is hardcoded
+
+`visibilityFilter()` in `cross-agent.ts` resolves agent tiers and visibility from a hardcoded `defaultOrgRegistry()`. This duplicates fleet topology that lives authoritatively in `fleet_agents` + `fleet_orgs` in library.db.
+
+**Impact:** New agents added to library.db but not the hardcoded registry get fleet-only visibility until the registry is updated in code.
+
+**Planned fix:** Live-load registry from library.db on startup, hardcoded as cold-start fallback only. See [docs/ROADMAP.md](ROADMAP.md).
+
+## Cursor durability across restarts
+
+The compositor writes a session cursor to hot cache (SQLite `:memory:`) with a 24h TTL. On gateway restart, the cursor is lost until the next `compose()` call repopulates it.
+
+**Impact:** Background indexer may miss the cursor on the first turn after a restart, falling back to full-history scan.
+
+**Planned fix:** Dual-write cursor to messages.db so it survives restarts. See [docs/ROADMAP.md](ROADMAP.md).
+
+## Cross-session context has no boundary markers
+
+`buildCrossSessionContext()` renders flat previews with no per-message boundaries or sender identity labels.
+
+**Impact:** Context from different sessions blends together, making attribution ambiguous in multi-agent scenarios.
+
+**Planned fix:** WQ-20260402-001. See [docs/ROADMAP.md](ROADMAP.md).