@psiclawops/hypermem 0.8.1 → 0.8.3

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)
@@ -405,7 +415,39 @@ Schema versions are stamped into each database on startup and checked on open. A
 
 **Requirements:** Node.js 22+, OpenClaw with context engine plugin support. No standalone SQLite install needed (uses Node 22 built-in `node:sqlite`). Embedding provider is optional for first install.
 
-### From source
+hypermem works two ways:
+- **As a library** — import directly into your own Node.js code. No OpenClaw required.
+- **As an OpenClaw plugin** — replaces the default context engine. Requires a running OpenClaw gateway.
+
+### Library usage (no OpenClaw required)
+
+```bash
+npm install @psiclawops/hypermem
+```
+
+```typescript
+import { HyperMem } from '@psiclawops/hypermem';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const hm = await HyperMem.create({
+  dataDir: join(homedir(), '.openclaw', 'hypermem'),
+  embedding: { provider: 'none' },
+});
+
+await hm.recordUserMessage('my-agent', 'session-1', 'Hello');
+const composed = await hm.compose({
+  agentId: 'my-agent',
+  sessionKey: 'session-1',
+  prompt: 'Hello',
+  tokenBudget: 4000,
+  provider: 'anthropic',
+});
+```
+
+That's it. No gateway, no plugins, no config files. See [API](#api) for the full interface.
+
+### OpenClaw plugin install (from source)
 
 ```bash
 git clone https://github.com/PsiClawOps/hypermem.git
@@ -433,15 +475,30 @@ 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
+
+# ⚠️  Add to your existing plugins.allow — do not replace your current list.
+# Edit the array below to include any plugins you already have allowed:
 openclaw config set plugins.allow '["hypercompositor","hypermem"]' --strict-json
+
 openclaw gateway restart
 ```
 
-Verify (run from the repo clone directory):
+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
@@ -530,9 +587,11 @@ Full reference: **[docs/TUNING.md](./docs/TUNING.md)**
 
 ```typescript
 import { HyperMem } from '@psiclawops/hypermem';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
 
 const hm = await HyperMem.create({
-  dataDir: '~/.openclaw/hypermem',
+  dataDir: join(homedir(), '.openclaw', 'hypermem'),
   cache: { maxEntries: 10000 },
   // Local (Ollama):
   embedding: { ollamaUrl: 'http://localhost:11434', model: 'nomic-embed-text' },
@@ -581,6 +640,14 @@ node bin/hypermem-status.mjs --json          # machine-readable output
 node bin/hypermem-status.mjs --health        # health checks only (exit 1 on failure)
 ```
 
+By default, `hypermem-status` looks for data in `~/.openclaw/hypermem`. If your data directory is elsewhere (e.g. testing in an isolated environment), set:
+
+```bash
+HYPERMEM_DATA_DIR=/path/to/data node bin/hypermem-status.mjs --health
+```
+
+> **Fresh install note:** If no agent has run a session yet, `--health` will report "no sessions ingested" rather than a database error. This is expected. Send a test message to any agent, then re-run the health check.
+
 ---
 
 ## Pressure management
@@ -612,6 +679,22 @@ hypermem composes context fresh on every turn, but a long-running session still
 
 ---
 
+## Common issues
+
+| 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 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 |
+| JS code creates `./~/.openclaw/` directory | Used literal `~` in JS instead of `homedir()` | Use `join(homedir(), '.openclaw', 'hypermem')` from `node:path` and `node:os` |
+| `INSTALL.md` not found in npm package | Older published version | Update to latest or read INSTALL.md on [GitHub](https://github.com/PsiClawOps/hypermem/blob/main/INSTALL.md) |
+
+Full troubleshooting: **[INSTALL.md § Troubleshooting](./INSTALL.md#troubleshooting)**
+
+---
+
 ## Migration
 
 hypermem doesn't touch your existing memory data. Install it, switch the context engine, and migrate historical data on your own timeline.

package/bin/hypermem-status.mjs

@@ -104,6 +104,16 @@ if (flags.agent) {
 }
 
 if (!mainDbPath || !existsSync(mainDbPath)) {
+  if (args.includes('--health') || args.includes('--json')) {
+    const result = { status: 'no_sessions', message: 'Installed but no agent sessions ingested yet. Send a message to any agent, then re-run.' };
+    if (args.includes('--json')) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log('Status: installed, no sessions ingested yet.');
+      console.log('Send a message to any agent, then re-run this health check.');
+    }
+    process.exit(0);
+  }
   console.error('Error: no agent messages.db found. Has HyperMem ingested any sessions?');
   process.exit(1);
 }

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** Release version — matches package.json and is stamped into library.db on every startup. */
-export declare const ENGINE_VERSION = "0.8.1";
+export declare const ENGINE_VERSION = "0.8.2";
 /** Minimum Node.js version required — matches package.json engines field. */
 export declare const MIN_NODE_VERSION = "22.0.0";
 /** @deprecated No longer used — Redis was replaced with SQLite :memory: CacheLayer. */
@@ -19,15 +19,15 @@ export declare const LIBRARY_SCHEMA_VERSION_EXPORT = 19;
 /**
  * Compatibility version — the single number operators and consumers check.
  * Maps to: messages.db schema v10, library schema v19.
- * Matches ENGINE_VERSION for the 0.8.1 release.
+ * Matches ENGINE_VERSION for the 0.8.2 release.
  */
-export declare const HYPERMEM_COMPAT_VERSION = "0.8.1";
+export declare const HYPERMEM_COMPAT_VERSION = "0.8.2";
 /**
  * Schema compatibility map — machine-readable version requirements.
  * Use this to verify DB schemas match the running engine.
  */
 export declare const SCHEMA_COMPAT: {
-    readonly compatVersion: "0.8.1";
+    readonly compatVersion: "0.8.2";
     readonly mainSchema: 10;
     readonly librarySchema: 19;
 };

package/dist/version.js

@@ -1,5 +1,5 @@
 /** Release version — matches package.json and is stamped into library.db on every startup. */
-export const ENGINE_VERSION = '0.8.1';
+export const ENGINE_VERSION = '0.8.2';
 /** Minimum Node.js version required — matches package.json engines field. */
 export const MIN_NODE_VERSION = '22.0.0';
 /** @deprecated No longer used — Redis was replaced with SQLite :memory: CacheLayer. */
@@ -19,15 +19,15 @@ export const LIBRARY_SCHEMA_VERSION_EXPORT = 19;
 /**
  * Compatibility version — the single number operators and consumers check.
  * Maps to: messages.db schema v10, library schema v19.
- * Matches ENGINE_VERSION for the 0.8.1 release.
+ * Matches ENGINE_VERSION for the 0.8.2 release.
  */
-export const HYPERMEM_COMPAT_VERSION = '0.8.1';
+export const HYPERMEM_COMPAT_VERSION = '0.8.2';
 /**
  * Schema compatibility map — machine-readable version requirements.
  * Use this to verify DB schemas match the running engine.
  */
 export const SCHEMA_COMPAT = {
-    compatVersion: '0.8.1',
+    compatVersion: '0.8.2',
     mainSchema: 10,
     librarySchema: 19,
 };

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).

package/docs/MEMORY_MD_AUTHORING.md

@@ -0,0 +1,243 @@
+# MEMORY.md authoring
+
+`MEMORY.md` is an index, not a dump.
+
+Use it to preserve durable signal the agent should keep noticing across sessions: decisions, operating rules, important architecture facts, stable paths, active plans, and search pointers into deeper history.
+
+Do not use it as a transcript, changelog, or a second database. hypermem already stores the raw history. `MEMORY.md` should make the right things easy to find again.
+
+## What belongs in MEMORY.md
+
+Keep items that are still likely to matter after the current session ends:
+
+- stable architectural facts
+- standing rules and constraints
+- current project plans worth reloading next session
+- important decisions with enough context to recover why they happened
+- durable paths, repo locations, and operational references
+- search pointers for deeper recall
+
+Good rule: if losing the item would make the next session slower, riskier, or more error-prone, it probably belongs.
+
+## What does not belong
+
+Do not put these in `MEMORY.md`:
+
+- full conversation summaries
+- test logs and build output
+- one-off debugging notes with no ongoing value
+- temporary status that belongs in a daily checkpoint
+- long implementation detail blocks copied from code or specs
+- duplicate facts already obvious from repo structure
+
+If the value is only "this happened today," it usually belongs in the daily file, not the index.
+
+## Authoring style
+
+Write pointer-first entries. One line should stand on its own, and one search pointer should reopen the deeper context.
+
+Preferred format:
+
+```md
+- TUNE-011: indexer quality gate, 33% fact noise removed (2527→1707 facts)
+  → memory_search("TUNE-011 indexer quality")
+```
+
+Avoid this:
+
+```md
+- TUNE-011
+  - changed isQualityFact()
+  - added guards for code blocks
+  - adjusted token thresholds
+  - updated tests
+  - shipped at 11:42 PM
+```
+
+The first format reloads context fast. The second turns `MEMORY.md` into a bad replica of history.
+
+## Recommended sections
+
+Most agents do well with some version of these:
+
+- Identity
+- Domain priming
+- Key specs and plans
+- Standing rules
+- Key decisions
+- Recent actions or active facts, if they are still durable enough to matter
+
+Use only the sections that actually carry signal.
+
+## Recency checking
+
+Some facts are true now but should not be treated like permanent law.
+
+Examples:
+
+- current default model provider
+- active fallback model
+- temporary deployment workarounds
+- known incidents, freezes, or suspensions
+- "current release" statements
+- performance numbers tied to a recent benchmark
+
+For these, add recency cues and review them on a cadence.
+
+### Mark temporal facts clearly
+
+When a fact is time-bound, include one or more of:
+
+- an explicit date, such as `as of 2026-04-18`
+- a condition, such as `until Copilot is restored`
+- a review trigger, such as `recheck after next deploy`
+- a search pointer to the deeper event history
+
+Example:
+
+```md
+- Fleet model drift checks suspended as of 2026-04-14, until Copilot is restored
+  → memory_search("model drift suspension Copilot restored")
+```
+
+### Use a stale-question test
+
+Before adding an item, ask:
+
+1. Will this still be true in 30 days?
+2. If it changed silently, would stale memory cause a bad decision?
+3. Does the entry tell the next session how to verify freshness?
+
+If the answer pattern is `no / yes / no`, the item needs recency metadata or it belongs somewhere else.
+
+### Review cadence
+
+A simple operating rule works well:
+
+- review "current state" lines every 7 to 14 days
+- review release, benchmark, and provider facts after each upgrade or deployment change
+- remove or rewrite any entry whose time condition no longer holds
+
+### Prefer ranges over false permanence
+
+Bad:
+
+```md
+- Forge runs copilot-local/claude-sonnet-4.6
+```
+
+Better:
+
+```md
+- Forge standard model was copilot-local/claude-sonnet-4.6 as of 2026-04-11; recheck after provider routing changes
+  → memory_search("Forge standard model 2026-04-11 provider routing")
+```
+
+## Relationship to daily memory files
+
+Use daily files for checkpoint logging: what changed, what blocked, what to resume.
+
+Use `MEMORY.md` for the compact map of durable context.
+
+A good daily file helps you resume tomorrow. A good `MEMORY.md` helps you resume next month.
+
+## Maintenance rule
+
+If an entry no longer earns its place, delete it.
+
+A shorter `MEMORY.md` with current signal beats a larger one full of expired truth.
+
+## Static index vs runtime tail (compositor contract)
+
+`MEMORY.md` has two regions. The contract between them is enforced by the
+compositor and must be preserved by anyone editing the file.
+
+```
+┌─────────────────────────────────────────────┐
+│  Static curated index (human-authored)      │
+│  • identity, pointers, durable facts        │
+│  • edit this region by hand                 │
+├─────────────────────────────────────────────┤
+│  <!-- OPENCLAW_CACHE_BOUNDARY -->           │
+├─────────────────────────────────────────────┤
+│  Runtime tail (compositor-generated)        │
+│  • Active Facts                             │
+│  • Temporal Context                         │
+│  • Other Active Sessions                    │
+│  • Recent Actions                           │
+│  • Dynamic Project Context                  │
+└─────────────────────────────────────────────┘
+```
+
+### Rules
+
+1. **On-disk `MEMORY.md` is the curated static index.** It holds identity
+   anchors, pointer entries with `memory_search()` hints, and durable facts
+   that earn their place long-term.
+
+2. **Everything below `<!-- OPENCLAW_CACHE_BOUNDARY -->` is the compositor's
+   runtime tail.** It is regenerated on session warm from live stores: the
+   fact table, contradiction audits, topic activity, recent tool actions,
+   and dynamic project context. Treat the text below the boundary as a
+   snapshot, not a source of truth.
+
+3. **Do not hand-edit the runtime tail.** Anything you write there will be
+   overwritten on the next compositor pass.
+
+4. **Do not copy runtime tail content back up into the static index.**
+   Facts in the runtime tail originate from the fact store. Copying them
+   into the static region:
+   - duplicates the content between two layers,
+   - hardens a temporary state into a durable record,
+   - and bypasses the promoter's quality filters and temporal-marker screen.
+
+   If a runtime fact genuinely belongs in the durable index, let the
+   dreaming promoter handle it, or re-author the claim manually with the
+   durability rules above.
+
+5. **The compositor owns the boundary marker.** Do not delete, move, or
+   relabel `<!-- OPENCLAW_CACHE_BOUNDARY -->`. Deleting it makes the entire
+   file look static to the compositor and breaks the runtime tail rebuild.
+
+### Why this matters
+
+The runtime tail exists to surface what is live right now: active facts,
+recent actions, other sessions, current project context. The static index
+exists to hold what will still be true next month. Conflating the two
+produces the exact failure mode the temporal-marker screen guards against:
+temporary state hardens into durable memory, and the agent loses the
+ability to tell "fresh right now" from "true forever."
+
+## Promoter temporal-marker screen
+
+The dreaming promoter (`src/dreaming-promoter.ts`) uses a second line of
+defense to keep time-bound facts out of durable memory: the
+temporal-marker screen.
+
+**How it works.** When `isPromotable()` evaluates a candidate fact, it
+checks the content against a centralized list of temporal markers:
+
+- explicit time bounds: `as of`, `until`, `currently`, `for now`
+- transitional states: `suspended`, `pending`, `paused`, `blocked`, `frozen`
+- rollout language: `rollout`, `phase`, `migration ongoing`, `pre-release`
+- experimental language: `temporary`, `trial`, `experiment(al)`, `exploratory period`, `override`, `hotfix`, `workaround`, `recheck`
+- conditional scope: `in effect during`, `active while … continues/ongoing/rolling out`
+
+If any marker matches, the fact must carry structured recency metadata
+(`validFrom` or `invalidAt` on the facts row) to be eligible for durable
+promotion. Plain ISO dates in the content text are **not** a bypass: a
+sentence like `suspended pending X as of 2026-04-18` still contains the
+temporal markers `suspended` and `pending`, and the date only confirms
+that the claim is time-bound.
+
+**Extending the marker list.** The list is exported from
+`src/dreaming-promoter.ts` as `TEMPORAL_MARKERS`. Keep it centralized.
+Tests in `test/dreaming-promoter-temporal.mjs` exercise coverage on both
+direct and disguised phrasing; add new fixtures there when adding markers.
+
+**Implications for hand-written `MEMORY.md` entries.** The same
+discipline applies at the authoring layer. If you find yourself writing
+"currently," "for now," "pending X," or "in effect during Y" in the
+static index, add an explicit date-stamped condition or move the note to
+a daily file. The promoter's screen is a safety net, not a substitute
+for good authoring.

package/docs/MIGRATION.md

@@ -0,0 +1,56 @@
+# HyperMem Migration
+
+Start here.
+
+- **Operator guide:** [`MIGRATION_GUIDE.md`](./MIGRATION_GUIDE.md)
+- **Current repo state:** source-specific migration examples live in `MIGRATION_GUIDE.md`. There is no bundled unified migration dispatcher in this repo yet.
+
+All migration examples default to **dry-run** where shown. Add `--apply` only when you are ready to write data.
+
+---
+
+## Multi-operator deployments (breaking change warning)
+
+> ⚠️ **KL-01: No global-scope write gate (still open as of 0.8.0)**
+>
+> hypermem 0.5.0 ships without a write gate for `scope='global'` facts. In a
+> **single-operator deployment** (one user, one fleet sharing `library.db`), this
+> is acceptable — agents share context intentionally.
+>
+> In a **multi-operator deployment** (multiple users or tenants sharing one
+> `library.db`), this is a **breaking isolation risk**: a global-scope write from
+> one operator's agent propagates to all other operators' agents.
+>
+> **Do not run hypermem 0.5.0 in a multi-operator deployment without an external
+> write gate at the application layer.** The write gate is deferred to 1.0.0
+> where it will be enforced at the library DB level.
+>
+> A runtime warning is logged whenever `scope='global'` is written — monitor
+> for this in production: `[hypermem] WARNING: ... scope='global'`
+
+---
+
+## Schema compatibility map
+
+Current releases do **not** require Redis. The hot cache is SQLite `:memory:`.
+Older versions below 0.5.0 used Redis, so the table keeps that history explicit.
+
+| hypermem version | Main DB schema | Library DB schema | Min Node | External cache |
+|---|---|---|---|---|
+| 0.8.0 | v10 | v19 | 22.0.0 | none, SQLite `:memory:` hot cache |
+| 0.7.0 | v7 | v13 | 22.0.0 | none, SQLite `:memory:` hot cache |
+| 0.6.0 | v6 | v12 | 22.0.0 | none, SQLite `:memory:` hot cache |
+| 0.5.0 | v6 | v12 | 22.0.0 | transition release, SQLite `:memory:` hot cache |
+| 0.4.0 | v5 | v10 | 20.0.0 | Redis 6.0.0 |
+
+Schema versions are importable for programmatic checks:
+```ts
+import { SCHEMA_COMPAT, HYPERMEM_COMPAT_VERSION } from 'hypermem';
+// HYPERMEM_COMPAT_VERSION = '0.8.0'
+// SCHEMA_COMPAT = { compatVersion: '0.8.0', mainSchema: 10, librarySchema: 19 }
+```
+
+If your DBs are behind, run:
+```bash
+node scripts/migrate-legacy-sessions.mjs --apply
+```