@psiclawops/hypermem 0.9.4 → 0.9.5

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 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.
@@ -13,7 +22,7 @@ All notable changes to hypermem are documented here.
 ## 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.
+- **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.
@@ -32,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
 
@@ -65,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,17 +5,17 @@ This is the canonical install procedure. Keep README shorter and point operators
 ## Prerequisites
 
 - **Node.js 22+** (uses built-in `node:sqlite`)
-- **OpenClaw** must already be installed, onboarded, and running. HyperMem is a plugin for an existing OpenClaw deployment -- it does not bootstrap OpenClaw itself. If you have never run `openclaw daemon 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:**
 
 ```bash
-openclaw daemon status    # should show "running" or "ready"
+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 daemon restart` only works when the gateway service is already set up. On a brand-new OpenClaw install that has never been started, you need `openclaw daemon start` (or the full onboarding flow) before installing plugins.
+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
 
@@ -68,29 +68,23 @@ 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 the recall-friendly starter config only if no config exists, and prints merge-safe OpenClaw activation commands. It does not edit OpenClaw config and does not restart the gateway.
+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).
 
-> **Prerequisites:** OpenClaw must be installed and onboarded. Run `openclaw daemon status` to confirm. If the gateway is not configured, complete OpenClaw setup first.
+> **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 blindly.
 
-`hypermem-install` creates the current recommended starter config automatically when `~/.openclaw/hypermem/config.json` is missing. The shipped starter config is recall-friendly standard mode:
+`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:
 
-- `embedding.provider: "ollama"` with `nomic-embed-text`
+- `embedding.provider: "none"`
 - `warmHistoryBudgetFraction: 0.45`
 - standard fact, keystone, and history caps
 
-If Ollama is not running or `nomic-embed-text` is not installed, `hypermem-install` fails with a remediation block instead of silently staging a degraded semantic-recall install. For CI, container practice, or intentional FTS-only installs, either run:
+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.
 
-```bash
-npx hypermem-install --skip-embedding-check
-```
-
-or pre-create `~/.openclaw/hypermem/config.json` with `{"embedding":{"provider":"none"}}` before running the installer. Existing config files are preserved unchanged.
-
-If you want a lighter or richer memory profile later, adjust from this baseline using the tuning guidance below instead of starting from the older code defaults.
+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
 
@@ -106,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,7 +145,7 @@ openclaw config set plugins.allow '["existing-plugin","hypercompositor","hyperme
 **Step 3: Restart.**
 
 ```bash
-openclaw daemon restart
+openclaw gateway restart
 ```
 
 OpenClaw loads the plugin runtime from `~/.openclaw/plugins/hypermem/`.
@@ -219,7 +223,7 @@ Upgrades preserve the HyperMem data directory and existing config. The runtime s
 cp -a ~/.openclaw/plugins/hypermem ~/.openclaw/plugins/hypermem.backup.$(date +%Y%m%d-%H%M%S) 2>/dev/null || true
 npm install @psiclawops/hypermem@latest
 npx hypermem-install
-openclaw daemon restart
+openclaw gateway restart
 ```
 
 Then validate:
@@ -244,7 +248,7 @@ Rollback disables HyperMem without deleting data:
 ```bash
 openclaw config set plugins.slots.contextEngine legacy
 openclaw config set plugins.slots.memory none
-openclaw daemon restart
+openclaw gateway restart
 ```
 
 ---
@@ -278,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.
 
 ---
 
@@ -309,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
 {
@@ -319,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:
 ```
@@ -563,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). HyperMem applies retrieval query/document prefixes for supported Ollama embedders (`nomic-embed-text`, `qwen3-embedding`, `mxbai-embed-large`) unless `queryPrefix` / `documentPrefix` are set explicitly.
+- **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
@@ -572,7 +576,7 @@ See [Embedding Providers](#embedding-providers) above.
 Do not start tuning before this section passes. If HyperMem is not loaded and composing, the next problem is installation, not tuning.
 
 ```bash
-openclaw daemon restart
+openclaw gateway restart
 ```
 
 > **If restart reports the gateway is disabled or not configured:** you need to complete OpenClaw onboarding before this step. See [Prerequisites](#prerequisites). `gateway restart` only works on an already-running gateway.
@@ -583,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 daemon status` to confirm the gateway is running and accessible. If the gateway is running but logs fail, check `openclaw config get gateway.token` and ensure your shell session has the correct auth context.
+> **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:
 ```
@@ -612,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 |
 |---|---|
@@ -639,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:
 
@@ -647,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' },
@@ -657,7 +661,7 @@ architect: { agentId: 'architect', tier: 'council' },
 
 ```typescript
 // Before (placeholder):
-agent1: 'infrastructure',
+alice: 'infrastructure',
 
 // After (your fleet):
 architect: 'infrastructure',
@@ -668,7 +672,7 @@ architect: 'infrastructure',
 ```bash
 npm run build
 npm --prefix plugin run build
-openclaw daemon restart
+openclaw gateway restart
 ```
 
 Agents not listed in `AGENT_DOMAIN_MAP` default to domain `'general'`, which is fine for most setups. The org registry only matters if you use cross-agent memory visibility (org-scoped or council-scoped facts). If all your facts are agent-private or fleet-wide, you can skip the org structure entirely.
@@ -686,7 +690,7 @@ npm install
 npm run build
 npm --prefix plugin install && npm --prefix plugin run build
 npm --prefix memory-plugin install && npm --prefix memory-plugin run build
-openclaw daemon restart
+openclaw gateway restart
 ```
 
 What changed on the path from 0.5.x to current:
@@ -1000,7 +1004,7 @@ Expected on fresh installs. Facts and episodes accumulate over real conversation
 
 **Lost bundled plugins after setting `plugins.allow`**
 
-If you set `plugins.allow` to only `["hypercompositor","hypermem"]` without including your pre-existing allowed plugins, OpenClaw can stop loading bundled CLI surfaces and channel plugins. Fix: restore the prior allowlist, append `hypercompositor` and `hypermem`, then `openclaw daemon restart`. If `plugins.allow` was previously unset or empty, remove the HyperMem-only allowlist instead of keeping it.
+If you set `plugins.allow` to only `["hypercompositor","hypermem"]` without including your pre-existing allowed plugins, OpenClaw can stop loading bundled CLI surfaces and channel plugins. Fix: restore the prior allowlist, append `hypercompositor` and `hypermem`, then `openclaw gateway restart`. If `plugins.allow` was previously unset or empty, remove the HyperMem-only allowlist instead of keeping it.
 
 **Plugin not found**
 
@@ -1048,7 +1052,7 @@ To return to OpenClaw's default context engine:
 ```bash
 openclaw config set plugins.slots.contextEngine legacy
 openclaw config set plugins.slots.memory none
-openclaw daemon restart
+openclaw gateway restart
 ```
 
 Data in `~/.openclaw/hypermem/` is untouched. Re-enable by switching back.
@@ -1066,7 +1070,7 @@ Example:
 ```bash
 # Point hypermem at a different data location:
 export HYPERMEM_DATA_DIR=/mnt/data/hypermem
-openclaw daemon restart
+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.

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.4.** 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.4'
+  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';
 ```
@@ -437,7 +437,7 @@ Install states:
 | Runtime loaded | gateway restarted and both plugins loaded |
 | Runtime active | logs show `hypermem initialized` and compose activity |
 
-The installer writes the starter config for you when `~/.openclaw/hypermem/config.json` is missing. The default is recall-friendly standard mode with Ollama `nomic-embed-text`; if Ollama is not available, install it or run `npx hypermem-install --skip-embedding-check` for CI/container practice. To force lightweight FTS-only mode, pre-create `~/.openclaw/hypermem/config.json` with `{"embedding":{"provider":"none"}}` before running the installer.
+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:
 
@@ -477,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
@@ -495,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';
@@ -546,7 +546,7 @@ 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
@@ -594,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 |
@@ -613,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

@@ -1,12 +1,6 @@
 {
   "embedding": {
-    "provider": "ollama",
-    "model": "nomic-embed-text",
-    "dims": 768,
-    "dimensions": 768,
-    "ollamaUrl": "http://localhost:11434",
-    "timeout": 10000,
-    "batchSize": 32
+    "provider": "none"
   },
   "compositor": {
     "turnBudget": {

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

package/dist/background-indexer.js

@@ -37,27 +37,27 @@ import { isSafeForSharedVisibility } from './secret-scanner.js';
 // returns results. New agents default to 'general'.
 //
 // ── EXAMPLE DATA ──────────────────────────────────────────────────
-// The agent names below (agent1, director1, etc.) are PLACEHOLDERS.
+// The agent names below (alice, director1, etc.) are PLACEHOLDERS.
 // Replace them with your own agent IDs and domain labels to match
 // your fleet. Single-agent installs don't need to edit this:
 // unknown agents fall through to 'general' automatically.
 // See INSTALL.md § "Configure your fleet" for details.
 // ─────────────────────────────────────────────────────────────────
 const AGENT_DOMAIN_MAP = {
-    agent1: 'infrastructure',
+    alice: 'infrastructure',
     director2: 'infrastructure',
     director1: 'infrastructure',
     director3: 'infrastructure',
-    agent2: 'product',
+    bob: 'product',
     director4: 'product',
     director5: 'product',
     director6: 'product',
-    agent3: 'security',
+    dave: 'security',
     director7: 'security',
     director8: 'security',
     agent4: 'ux',
-    agent6: 'governance',
-    agent5: 'strategy',
+    carol: 'governance',
+    oscar: 'strategy',
     specialist1: 'development',
     specialist2: 'communications',
     main: 'general',
@@ -94,7 +94,7 @@ function extractFactCandidates(content) {
     // Preference patterns — medium confidence (0.60)
     const preferencePatterns = [
         /(?:prefer|always use|never use|don't use|avoid) (.{10,150})/gi,
-        /(?:operator|operator) (?:wants|prefers|likes|hates|dislikes) (.{10,150})/gi,
+        /(?:operator) (?:wants|prefers|likes|hates|dislikes) (.{10,150})/gi,
     ];
     // Operational patterns: deployments, incidents, fixes — high confidence (0.70)
     const operationalPatterns = [
@@ -148,7 +148,7 @@ const OPERATIONAL_BOILERPLATE = [
     /still\s*waiting/i,
     /will\s*pick\s*(it\s*)?up\s*(on\s*(next|the))?/i,
     /message\s*is\s*in\s*(his|her|their|the)\s*queue/i,
-    /sent\s+to\s+(agent6|agent2|agent4|agent3|agent5|agent1)/i,
+    /sent\s+to\s+(carol|bob|agent4|dave|oscar|alice)/i,
     /dispatched\s+(it\s+)?to/i,
     /timed\s*out\s*after/i,
     /\bNO_REPLY\b/,
@@ -393,7 +393,7 @@ function detectTopic(content) {
     if (!content || content.length < 50)
         return null;
     // Product/project name detection
-    const productMatch = content.match(/\b(HyperMem|ClawText|ClawDash|ClawCanvas|ClawCouncil|ClawTomation|OpenClaw|ClawDispatch)\b/i);
+    const productMatch = content.match(/\b(HyperMem|ClawText|dashboard|canvas|council|automation|OpenClaw|dispatch)\b/i);
     if (productMatch)
         return productMatch[1];
     // Infrastructure topic detection

package/dist/cross-agent.d.ts

@@ -27,7 +27,7 @@ export interface OrgRegistry {
  * Default fleet org structure.
  *
  * ── EXAMPLE DATA ──────────────────────────────────────────────────────────
- * The agent names below (agent1, agent2, director1, etc.) are PLACEHOLDERS.
+ * The agent names below (alice, bob, director1, etc.) are PLACEHOLDERS.
  * Replace them with your own agent IDs to match your fleet configuration.
  *
  * Single-agent installs: you don't need to edit this. Your agent ID is

package/dist/cross-agent.js

@@ -21,7 +21,7 @@ import { FleetStore } from './fleet-store.js';
  * Default fleet org structure.
  *
  * ── EXAMPLE DATA ──────────────────────────────────────────────────────────
- * The agent names below (agent1, agent2, director1, etc.) are PLACEHOLDERS.
+ * The agent names below (alice, bob, director1, etc.) are PLACEHOLDERS.
  * Replace them with your own agent IDs to match your fleet configuration.
  *
  * Single-agent installs: you don't need to edit this. Your agent ID is
@@ -34,27 +34,27 @@ import { FleetStore } from './fleet-store.js';
  */
 export function defaultOrgRegistry() {
     const agents = {
-        agent1: { agentId: 'agent1', tier: 'council' },
-        agent2: { agentId: 'agent2', tier: 'council' },
+        alice: { agentId: 'alice', tier: 'council' },
+        bob: { agentId: 'bob', tier: 'council' },
         agent4: { agentId: 'agent4', tier: 'council' },
-        agent3: { agentId: 'agent3', tier: 'council' },
-        agent6: { agentId: 'agent6', tier: 'council' },
-        agent5: { agentId: 'agent5', tier: 'council' },
-        director1: { agentId: 'director1', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
-        director2: { agentId: 'director2', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
-        director3: { agentId: 'director3', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
-        director4: { agentId: 'director4', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
-        director5: { agentId: 'director5', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
-        director6: { agentId: 'director6', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
-        director7: { agentId: 'director7', tier: 'director', org: 'agent3-org', councilLead: 'agent3' },
-        director8: { agentId: 'director8', tier: 'director', org: 'agent3-org', councilLead: 'agent3' },
+        dave: { agentId: 'dave', tier: 'council' },
+        carol: { agentId: 'carol', tier: 'council' },
+        oscar: { agentId: 'oscar', tier: 'council' },
+        director1: { agentId: 'director1', tier: 'director', org: 'alice-org', councilLead: 'alice' },
+        director2: { agentId: 'director2', tier: 'director', org: 'alice-org', councilLead: 'alice' },
+        director3: { agentId: 'director3', tier: 'director', org: 'alice-org', councilLead: 'alice' },
+        director4: { agentId: 'director4', tier: 'director', org: 'bob-org', councilLead: 'bob' },
+        director5: { agentId: 'director5', tier: 'director', org: 'bob-org', councilLead: 'bob' },
+        director6: { agentId: 'director6', tier: 'director', org: 'bob-org', councilLead: 'bob' },
+        director7: { agentId: 'director7', tier: 'director', org: 'dave-org', councilLead: 'dave' },
+        director8: { agentId: 'director8', tier: 'director', org: 'dave-org', councilLead: 'dave' },
         specialist1: { agentId: 'specialist1', tier: 'specialist' },
         specialist2: { agentId: 'specialist2', tier: 'specialist' },
     };
     const orgs = {
-        'agent1-org': ['agent1', 'director1', 'director2', 'director3'],
-        'agent2-org': ['agent2', 'director4', 'director5', 'director6'],
-        'agent3-org': ['agent3', 'director7', 'director8'],
+        'alice-org': ['alice', 'director1', 'director2', 'director3'],
+        'bob-org': ['bob', 'director4', 'director5', 'director6'],
+        'dave-org': ['dave', 'director7', 'director8'],
     };
     return { orgs, agents };
 }

package/dist/index.d.ts

@@ -135,8 +135,8 @@ export interface StartupFleetSeedResult {
  *
  * Usage:
  *   const hm = await hypermem.create({ dataDir: '~/.openclaw/hypermem' });
- *   await hm.record('agent1', 'agent:agent1:webchat:main', userMsg);
- *   const result = await hm.compose({ agentId: 'agent1', sessionKey: '...', ... });
+ *   await hm.record('alice', 'agent:alice:webchat:main', userMsg);
+ *   const result = await hm.compose({ agentId: 'alice', sessionKey: '...', ... });
  */
 export declare class HyperMem {
     readonly dbManager: DatabaseManager;
@@ -202,7 +202,7 @@ export declare class HyperMem {
     /**
      * List archived or forked contexts for an agent.
      *
-     * Operator-safe enumeration path. This is the approved archived-context
+     * operator-safe enumeration path. This is the approved archived-context
      * listing surface. Active composition remains separate.
      */
     listArchivedContexts(agentId: string, opts?: {
@@ -226,11 +226,9 @@ export declare class HyperMem {
      * Routes to MessageStore.queryHistory which owns all history SQL.
      * No general SQL execution, no bypass of compaction fences.
      *
-     * Plugin surface: preferred shape is history.query action in the OpenClaw plugin tool
-     * surface. The SDK currently only exposes registerContextEngine and registerMemoryCapability,
-     * so no plugin tool action is registered in this release. Blocker: no api.registerTool
-     * or equivalent action-routing surface in definePluginEntry. This method is the
-     * public API; agents can call it directly via HyperMem.queryHistory().
+     * Plugin surface: preferred shape is the history_query OpenClaw agent tool,
+     * labeled history.query for operator-facing output. This method is the core
+     * public API that backs the tool via HyperMem.queryHistory().
      */
     queryHistory(query: HistoryQuery): HistoryQueryResult;
     /**