clawmem 0.9.0 → 0.10.0

package/AGENTS.md

@@ -208,7 +208,9 @@ When using ClawMem with OpenClaw, choose one of two deployment options:
 
 **Active Memory coexistence:** ClawMem is fully compatible with OpenClaw's Active Memory plugin (v2026.4.10+). They search different backends (ClawMem vault vs dreaming/wiki) and inject into different prompt regions (user prompt vs system prompt). Both can run simultaneously — no configuration needed.
 
-**OpenClaw v2026.4.10+ recommended:** Fixes a config normalization bug where `plugins.slots.contextEngine` was silently dropped (#64192).
+**OpenClaw v2026.4.11+ required for ClawMem v0.10.0+.** v2026.4.11 tightened plugin discovery (`readdirSync({ withFileTypes: true })` + `dirent.isDirectory()`) and added a plugin-directory ownership check. ClawMem v0.10.0+ ships the new discovery manifest (`src/openclaw/package.json` with `openclaw.extensions`) and defaults to recursive copy (not symlink) installs to clear both gates. Older notes: v2026.4.10 fixed #64192 (`plugins.slots.contextEngine` silently dropped during config normalization, relevant only for pre-v0.10.0 ClawMem that still used the `contextEngine` slot).
+
+**ClawMem v0.10.0 uses the `memory` slot, not `contextEngine`.** `openclaw plugins enable clawmem` sets `plugins.slots.memory: "clawmem"` and disables competing memory plugins (`memory-core`, `memory-lancedb`) in one step. The older `openclaw config set plugins.slots.contextEngine clawmem` pattern does not apply to v0.10.0+.
 
 ### Option 1: ClawMem Exclusive (Recommended)
 
@@ -735,6 +737,8 @@ clawmem focus clear --session-id abc123
 - Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs with A-MEM notes + links. Only runs if the MCP process stays alive long enough to tick (every 5min).
 - Beads integration: `syncBeadsIssues()` queries `bd` CLI (Dolt backend, v0.58.0+) for live issue data, creates markdown docs in `beads` collection, maps all dependency edge types into `memory_relations`, and triggers A-MEM enrichment for new docs. Watcher auto-triggers on `.beads/` directory changes; `beads_sync` MCP tool for manual sync. Requires `bd` binary on PATH or at `~/go/bin/bd`.
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
-- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw context engine. Uses `before_prompt_build` for retrieval (prompt-aware), `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation. Shares same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
-- **OpenClaw v2026.3.28+ compaction fix (v0.3.0):** `compact()` now delegates to OpenClaw's runtime compactor via `delegateCompactionToRuntime()` from `openclaw/plugin-sdk/core`. Previous versions returned `compacted: false` expecting legacy fallback — that fallback no longer exists. Without this fix, sessions never compact. Bootstrap context is now cached in `bootstrap()` and consumed once in `before_prompt_build`, eliminating duplicate hook invocations.
+- OpenClaw memory plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw memory plugin (`kind: memory`, v0.10.0+). Lifecycle events on the plugin-hook bus: `before_prompt_build` is the **load-bearing** path — it runs prompt-aware retrieval (context-surfacing) AND the pre-emptive `precompact-extract` synchronously when token usage approaches the compaction threshold, so state is captured BEFORE the LLM call that could trigger compaction; `agent_end` runs decision-extractor + handoff-generator + feedback-loop in parallel (fire-and-forget at OpenClaw); `before_compaction` is **defense-in-depth fallback only** — fire-and-forget, races the compactor, exists for the rare case where the `before_prompt_build` proximity heuristic missed a sudden token jump; `session_start` registers the session and caches first-turn bootstrap context. Shares the same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
+- **§14.3 pure-memory migration (v0.10.0):** v0.10.0 drops the `ClawMemContextEngine` class entirely. Previous versions registered as `kind: context-engine` and implemented `assemble()`/`bootstrap()`/`afterTurn()`/`compact()` on a class. v0.10.0 registers as `kind: memory` and wires every lifecycle surface through plugin hooks on the event bus. Retrieval pipeline, composite scoring, vault format, and the 5 registered agent tools are unchanged — this is a packaging and registration change, not a behavioral one.
+- **v2026.4.11 packaging fix (v0.10.0):** `src/openclaw/package.json` declares `openclaw.extensions: ["./index.ts"]` (required by v2026.4.11's discovery path), and `cmdSetupOpenClaw` defaults to `cpSync(..., { recursive: true, dereference: true })` because v2026.4.11's discoverer uses `readdirSync({ withFileTypes: true })` where symlink `isDirectory() === false`. A `--link` opt-in flag preserves the old symlink behavior for dev workflows with a warning.
+- **Precompact correctness contract (v0.10.0):** The load-bearing precompact path is `before_prompt_build`, NOT `before_compaction`. `before_prompt_build` is awaited synchronously before the LLM call that could trigger compaction, so it cannot race the compactor. `before_compaction` is fire-and-forget at OpenClaw's call site and exists only as a safety net for the rare case the proximity heuristic in `before_prompt_build` missed a sudden token-count jump. Do not describe `before_compaction` as the primary surface — the guarantee comes from `before_prompt_build`. v0.3.0 did the pre-emptive extraction from `ContextEngine.compact()` via `delegateCompactionToRuntime()`; v0.10.0 moves it into `before_prompt_build` where it can be awaited before the triggering LLM call. User-visible behavior is equivalent or better: state capture now happens strictly before compaction, not in a race with it.
 - Hermes Agent MemoryProvider plugin: `src/hermes/` — Python plugin implementing Hermes's `MemoryProvider` ABC. Symlink or copy into `hermes-agent/plugins/memory/clawmem/`. Uses shell-out for lifecycle hooks (session-bootstrap, context-surfacing, extraction) and REST API for tools (retrieve, get, session_log, timeline, similar). Plugin manages its own transcript JSONL for ClawMem hooks. Supports external (you run `clawmem serve`) and managed (plugin starts/stops serve) modes.

package/CLAUDE.md

@@ -208,7 +208,9 @@ When using ClawMem with OpenClaw, choose one of two deployment options:
 
 **Active Memory coexistence:** ClawMem is fully compatible with OpenClaw's Active Memory plugin (v2026.4.10+). They search different backends (ClawMem vault vs dreaming/wiki) and inject into different prompt regions (user prompt vs system prompt). Both can run simultaneously — no configuration needed.
 
-**OpenClaw v2026.4.10+ recommended:** Fixes a config normalization bug where `plugins.slots.contextEngine` was silently dropped (#64192).
+**OpenClaw v2026.4.11+ required for ClawMem v0.10.0+.** v2026.4.11 tightened plugin discovery (`readdirSync({ withFileTypes: true })` + `dirent.isDirectory()`) and added a plugin-directory ownership check. ClawMem v0.10.0+ ships the new discovery manifest (`src/openclaw/package.json` with `openclaw.extensions`) and defaults to recursive copy (not symlink) installs to clear both gates. Older notes: v2026.4.10 fixed #64192 (`plugins.slots.contextEngine` silently dropped during config normalization, relevant only for pre-v0.10.0 ClawMem that still used the `contextEngine` slot).
+
+**ClawMem v0.10.0 uses the `memory` slot, not `contextEngine`.** `openclaw plugins enable clawmem` sets `plugins.slots.memory: "clawmem"` and disables competing memory plugins (`memory-core`, `memory-lancedb`) in one step. The older `openclaw config set plugins.slots.contextEngine clawmem` pattern does not apply to v0.10.0+.
 
 ### Option 1: ClawMem Exclusive (Recommended)
 
@@ -735,6 +737,8 @@ clawmem focus clear --session-id abc123
 - Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs with A-MEM notes + links. Only runs if the MCP process stays alive long enough to tick (every 5min).
 - Beads integration: `syncBeadsIssues()` queries `bd` CLI (Dolt backend, v0.58.0+) for live issue data, creates markdown docs in `beads` collection, maps all dependency edge types into `memory_relations`, and triggers A-MEM enrichment for new docs. Watcher auto-triggers on `.beads/` directory changes; `beads_sync` MCP tool for manual sync. Requires `bd` binary on PATH or at `~/go/bin/bd`.
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
-- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw context engine. Uses `before_prompt_build` for retrieval (prompt-aware), `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation. Shares same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
-- **OpenClaw v2026.3.28+ compaction fix (v0.3.0):** `compact()` now delegates to OpenClaw's runtime compactor via `delegateCompactionToRuntime()` from `openclaw/plugin-sdk/core`. Previous versions returned `compacted: false` expecting legacy fallback — that fallback no longer exists. Without this fix, sessions never compact. Bootstrap context is now cached in `bootstrap()` and consumed once in `before_prompt_build`, eliminating duplicate hook invocations.
+- OpenClaw memory plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw memory plugin (`kind: memory`, v0.10.0+). Lifecycle events on the plugin-hook bus: `before_prompt_build` is the **load-bearing** path — it runs prompt-aware retrieval (context-surfacing) AND the pre-emptive `precompact-extract` synchronously when token usage approaches the compaction threshold, so state is captured BEFORE the LLM call that could trigger compaction; `agent_end` runs decision-extractor + handoff-generator + feedback-loop in parallel (fire-and-forget at OpenClaw); `before_compaction` is **defense-in-depth fallback only** — fire-and-forget, races the compactor, exists for the rare case where the `before_prompt_build` proximity heuristic missed a sudden token jump; `session_start` registers the session and caches first-turn bootstrap context. Shares the same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
+- **§14.3 pure-memory migration (v0.10.0):** v0.10.0 drops the `ClawMemContextEngine` class entirely. Previous versions registered as `kind: context-engine` and implemented `assemble()`/`bootstrap()`/`afterTurn()`/`compact()` on a class. v0.10.0 registers as `kind: memory` and wires every lifecycle surface through plugin hooks on the event bus. Retrieval pipeline, composite scoring, vault format, and the 5 registered agent tools are unchanged — this is a packaging and registration change, not a behavioral one.
+- **v2026.4.11 packaging fix (v0.10.0):** `src/openclaw/package.json` declares `openclaw.extensions: ["./index.ts"]` (required by v2026.4.11's discovery path), and `cmdSetupOpenClaw` defaults to `cpSync(..., { recursive: true, dereference: true })` because v2026.4.11's discoverer uses `readdirSync({ withFileTypes: true })` where symlink `isDirectory() === false`. A `--link` opt-in flag preserves the old symlink behavior for dev workflows with a warning.
+- **Precompact correctness contract (v0.10.0):** The load-bearing precompact path is `before_prompt_build`, NOT `before_compaction`. `before_prompt_build` is awaited synchronously before the LLM call that could trigger compaction, so it cannot race the compactor. `before_compaction` is fire-and-forget at OpenClaw's call site and exists only as a safety net for the rare case the proximity heuristic in `before_prompt_build` missed a sudden token-count jump. Do not describe `before_compaction` as the primary surface — the guarantee comes from `before_prompt_build`. v0.3.0 did the pre-emptive extraction from `ContextEngine.compact()` via `delegateCompactionToRuntime()`; v0.10.0 moves it into `before_prompt_build` where it can be awaited before the triggering LLM call. User-visible behavior is equivalent or better: state capture now happens strictly before compaction, not in a race with it.
 - Hermes Agent MemoryProvider plugin: `src/hermes/` — Python plugin implementing Hermes's `MemoryProvider` ABC. Symlink or copy into `hermes-agent/plugins/memory/clawmem/`. Uses shell-out for lifecycle hooks (session-bootstrap, context-surfacing, extraction) and REST API for tools (retrieve, get, session_log, timeline, similar). Plugin manages its own transcript JSONL for ClawMem hooks. Supports external (you run `clawmem serve`) and managed (plugin starts/stops serve) modes.

package/README.md

@@ -1,4 +1,4 @@
-# ClawMem — Context engine for Claude Code, OpenClaw, and Hermes agents
+# ClawMem — On-device memory layer for Claude Code, OpenClaw, and Hermes agents
 
 <p align="center">
   <img src="docs/clawmem_hero.jpg" alt="ClawMem" width="100%">
@@ -8,7 +8,7 @@
 
 ClawMem fuses recent research into a retrieval-augmented memory layer that agents actually use. The hybrid architecture combines [QMD](https://github.com/tobi/qmd)-derived multi-signal retrieval (BM25 + vector search + reciprocal rank fusion + query expansion + cross-encoder reranking), [SAME](https://github.com/sgx-labs/statelessagent)-inspired composite scoring (recency decay, confidence, content-type half-lives, co-activation reinforcement), [MAGMA](https://arxiv.org/abs/2501.13956)-style intent classification with multi-graph traversal (semantic, temporal, and causal beam search), and [A-MEM](https://arxiv.org/abs/2510.02178) self-evolving memory notes that enrich documents with keywords, tags, and causal links between entries. Pattern extraction from [Engram](https://github.com/Gentleman-Programming/engram) adds deduplication windows, frequency-based durability scoring, and temporal navigation.
 
-Integrates via Claude Code hooks, an MCP server (works with any MCP-compatible client), a native OpenClaw ContextEngine plugin, or a Hermes Agent MemoryProvider plugin. All paths write to the same local SQLite vault. A decision captured during a Claude Code session shows up immediately when an OpenClaw or Hermes agent picks up the same project.
+Integrates via Claude Code hooks, an MCP server (works with any MCP-compatible client), a native OpenClaw plugin, or a Hermes Agent `MemoryProvider` plugin. All paths write to the same local SQLite vault. A decision captured during a Claude Code session shows up immediately when an OpenClaw or Hermes agent picks up the same project.
 
 TypeScript on Bun. MIT License.
 
@@ -47,7 +47,7 @@ ClawMem turns your markdown notes, project docs, and research dumps into persist
 - **Syncs project issues** from Beads issue trackers into searchable memory
 - **Runs a quiet-window heavy maintenance lane** — a second consolidation worker, off by default behind `CLAWMEM_HEAVY_LANE=true`, that runs on a longer interval only inside a configurable hour window. Gated by `context_usage` query-rate so it never competes for CPU/GPU with interactive sessions, scoped exclusively via DB-backed `worker_leases`, stale-first by default with an optional surprisal selector, and journals every attempt in `maintenance_runs` for operator visibility (v0.8.0)
 
-Runs fully local with no API keys and no cloud services. Integrates via Claude Code hooks and MCP tools, as an OpenClaw ContextEngine plugin, or as a Hermes Agent MemoryProvider plugin. All modes share the same vault for cross-runtime memory. Works with any MCP-compatible client.
+Runs fully local with no API keys and no cloud services. Integrates via Claude Code hooks and MCP tools, as a native OpenClaw plugin, or as a Hermes Agent `MemoryProvider` plugin. All modes share the same vault for cross-runtime memory. Works with any MCP-compatible client.
 
 Full version history is in [RELEASE_NOTES.md](RELEASE_NOTES.md). Upgrade instructions for existing vaults are in [docs/guides/upgrading.md](docs/guides/upgrading.md).
 
@@ -83,8 +83,8 @@ Full version history is in [RELEASE_NOTES.md](RELEASE_NOTES.md). Upgrade instruc
 **Optional integrations:**
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — for hooks + MCP integration
-- [OpenClaw](https://github.com/openclaw/openclaw) — for ContextEngine plugin integration
-- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — for MemoryProvider plugin integration
+- [OpenClaw](https://github.com/openclaw/openclaw) — for native plugin integration
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — for `MemoryProvider` plugin integration
 - [bd CLI](https://github.com/dolthub/dolt) v0.58.0+ — for Beads issue tracker sync (only if using Beads)
 
 ### Install from npm (recommended)
@@ -185,29 +185,31 @@ clawmem setup mcp      # Register MCP server in ~/.claude.json (31 tools)
 
 #### OpenClaw
 
-ClawMem registers as a native ContextEngine plugin - OpenClaw's pluggable interface for context management. Same 90/10 automatic retrieval, delivered through OpenClaw's lifecycle system instead of Claude Code hooks.
+ClawMem registers as a native OpenClaw memory plugin (`kind: memory`, v0.10.0+). Same 90/10 automatic retrieval, delivered through OpenClaw's plugin-hook bus instead of Claude Code hooks.
 
 ```bash
-clawmem setup openclaw   # Auto-installs plugin, prints remaining steps
+clawmem setup openclaw   # Installs plugin into ~/.openclaw/extensions/clawmem (copy, not symlink)
 ```
 
 **What the plugin provides:**
-- **`before_prompt_build` hook** - prompt-aware retrieval (context-surfacing + session-bootstrap)
-- **`ContextEngine.afterTurn()`** - decision extraction, handoff generation, feedback loop
-- **`ContextEngine.compact()`** - pre-compaction state preservation, delegates real compaction to legacy engine
+- **`before_prompt_build` hook (load-bearing)** - prompt-aware retrieval (context-surfacing + session-bootstrap) AND the pre-emptive `precompact-extract` run when token usage approaches the compaction threshold. This is the authoritative path for precompact state capture because it runs synchronously before the LLM call that would trigger compaction, so it cannot race the compactor.
+- **`agent_end` hook** - decision extraction, handoff generation, feedback loop (parallel, fire-and-forget at the OpenClaw call site)
+- **`before_compaction` hook (defense-in-depth fallback)** - fires `precompact-extract` again for the rare case where `before_prompt_build`'s proximity heuristic missed a sudden token-count jump. Fire-and-forget at OpenClaw's call site, so it races the compactor and offers no correctness guarantee on its own — the `before_prompt_build` path is what actually holds the invariant.
+- **`session_start` hook** - session registration + cached first-turn bootstrap context
 - **5 agent tools** - `clawmem_search`, `clawmem_get`, `clawmem_session_log`, `clawmem_timeline`, `clawmem_similar`
-- **Session lifecycle hooks** - `session_start`, `session_end`, `before_reset` safety net
 
 Disable OpenClaw's native memory search to avoid duplicate injection:
 ```bash
 openclaw config set agents.defaults.memorySearch.extraPaths "[]"
 ```
 
-ClawMem coexists cleanly with OpenClaw's [Active Memory](https://docs.openclaw.ai/concepts/active-memory) plugin (v2026.4.10+) — they search different backends and inject into different prompt regions, so both can run simultaneously without conflict. See the [OpenClaw plugin guide](docs/guides/openclaw-plugin.md#coexistence-with-openclaw-active-memory) for details.
+ClawMem coexists cleanly with OpenClaw's [Active Memory](https://docs.openclaw.ai/concepts/active-memory) plugin (v2026.4.10+). They search different backends and inject into different prompt regions, so both can run simultaneously without conflict. See the [OpenClaw plugin guide](docs/guides/openclaw-plugin.md#coexistence-with-openclaw-active-memory) for details.
 
-> **OpenClaw v2026.4.10+** recommended — fixes a config normalization bug where `plugins.slots.contextEngine` was silently dropped (#64192).
+**Pair ClawMem (memory) with a context-engine plugin (v0.10.0+).** OpenClaw and Hermes maintainers have converged on a two-surface plugin model: one slot for memory plugins (cross-session, retrieval-first) and a separate slot for context-engine plugins (in-session, compression/compaction-first). Under that model ClawMem is a memory layer — it has always been one in Hermes via the `MemoryProvider` ABC, and v0.10.0 moves the OpenClaw integration to the same semantic slot. You can now run ClawMem in the `memory` slot alongside an LCM-style compression plugin (for example, `lossless-claw`) in the `context-engine` slot. The two plugins do not overlap: one persists across sessions, the other reshapes the live window. See the [OpenClaw plugin guide — memory vs context engine](docs/guides/openclaw-plugin.md#memory-vs-context-engine--the-dual-plugin-surface) for the full rationale.
 
-**Alternative:** OpenClaw agents can also use ClawMem's MCP server directly (`clawmem setup mcp`), with or without hooks. This gives full access to all 31 MCP tools but bypasses OpenClaw's ContextEngine lifecycle, so you lose token budget awareness, native compaction orchestration, and the `afterTurn()` message pipeline. The ContextEngine plugin is recommended for new OpenClaw setups; MCP is available as an additional or standalone integration.
+> **OpenClaw v2026.4.11+ recommended (required for ClawMem v0.10.0+).** v2026.4.11 introduced a new plugin discovery contract that requires each plugin directory to ship a `package.json` with `openclaw.extensions` declared, and that rejects symlinked plugin directories. ClawMem v0.10.0 includes both fixes. Older ClawMem versions (< v0.10.0) on OpenClaw v2026.4.11+ will fail to discover silently — upgrade ClawMem, then re-run `clawmem setup openclaw`. See [docs/guides/upgrading.md](docs/guides/upgrading.md#v090--v0100).
+
+**Alternative:** OpenClaw agents can also use ClawMem's MCP server directly (`clawmem setup mcp`), with or without hooks. This gives full access to all 31 MCP tools but bypasses OpenClaw's plugin lifecycle, so you lose token budget awareness, native compaction orchestration, and the `agent_end` message pipeline. The native OpenClaw plugin is recommended for new setups; MCP is available as an additional or standalone integration.
 
 #### Hermes Agent
 
@@ -1088,9 +1090,14 @@ clawmem install-service --enable
 #### OpenClaw-specific
 
 ```bash
-# Install the ContextEngine plugin (auto-symlinks into ~/.openclaw/extensions/)
+# Install the OpenClaw plugin (v0.10.0+: recursively copies into ~/.openclaw/extensions/clawmem)
 clawmem setup openclaw
-# Then follow the printed next steps: restart gateway, set slot, configure GPU endpoints
+# Then follow the printed next steps:
+#   1. openclaw plugins enable clawmem   (switches memory slot + disables memory-core)
+#   2. openclaw gateway restart
+#   3. Configure GPU endpoints if needed (see setup openclaw output)
+# Multi-user installs also need: sudo chown -R <gateway-user>:<gateway-group> ~/.openclaw/extensions/clawmem
+# Requires OpenClaw v2026.4.11+.
 ```
 
 Index your content directories with `clawmem bootstrap` as above. The OpenClaw plugin shares the same vault as Claude Code hooks.

package/SKILL.md

@@ -605,9 +605,11 @@ Phase 3 deductive synthesis applies the same `contradicts` link for any draft th
 
 ## OpenClaw Integration
 
-**Active Memory coexistence:** ClawMem is fully compatible with OpenClaw's Active Memory plugin (v2026.4.10+). They search different backends and inject into different prompt regions — both can run simultaneously. The deployment options below control native memory search (`memorySearch.extraPaths`), not Active Memory.
+**Active Memory coexistence:** ClawMem is fully compatible with OpenClaw's Active Memory plugin (v2026.4.10+). They search different backends and inject into different prompt regions, both can run simultaneously. The deployment options below control native memory search (`memorySearch.extraPaths`), not Active Memory.
 
-**OpenClaw v2026.4.10+ recommended** — fixes contextEngine slot being silently dropped during config normalization (#64192).
+**OpenClaw v2026.4.11+ required for ClawMem v0.10.0+.** v2026.4.11 tightened plugin discovery (requires `package.json` with `openclaw.extensions`, rejects symlinked plugin directories). ClawMem v0.10.0 ships the new discovery manifest and defaults `clawmem setup openclaw` to recursive copy (not symlink). v2026.4.10 earlier fixed the #64192 config-normalization bug that dropped the `contextEngine` slot, which is now moot on v0.10.0+ because v0.10.0 uses the `memory` slot instead.
+
+**ClawMem v0.10.0 plugin kind:** `memory` (not `context-engine`). Enable with `openclaw plugins enable clawmem`, which also disables `memory-core` / `memory-lancedb` in one step.
 
 ### Option 1: ClawMem Exclusive (Recommended)
 
@@ -629,9 +631,15 @@ openclaw config set agents.defaults.memorySearch.extraPaths '["~/documents", "~/
 
 **Tradeoffs:** Redundant recall but 10-15% context window waste from duplicate facts.
 
-### Compaction (v0.3.0+, required for OpenClaw v2026.3.28+)
+### Multi-user install gotcha (v2026.4.11+)
+
+If the gateway runs as a dedicated system user (e.g. `openclaw`) different from the user who runs `clawmem setup openclaw` (e.g. `sciros`), the copied plugin dir is rejected with `suspicious ownership (uid=X, expected uid=Y or root)`. Fix: `sudo chown -R <gateway-user>:<gateway-group> ~/.openclaw/extensions/clawmem`. Single-user installs are not affected.
+
+Also: if the gateway user cannot traverse `~/<installer>/.openclaw/` (directory mode 700), the gateway fails to start with `Missing config. Run openclaw setup or set gateway.mode=local`. Fix: `sudo chmod 750 ~/<installer>/.openclaw` and ensure the gateway user is in the owning group.
+
+### Precompact state capture — where it runs
 
-`compact()` delegates to OpenClaw's runtime compactor via `delegateCompactionToRuntime()`. Previous versions returned `compacted: false` expecting legacy fallback — that fallback no longer exists. Without this fix, OpenClaw sessions never compact and context grows unbounded.
+The load-bearing surface for `precompact-extract` is `before_prompt_build`, not `before_compaction`. `before_prompt_build` awaits the extraction synchronously when token usage approaches the compaction threshold, so state capture completes before the LLM call that could trigger compaction on this turn. `before_compaction` is a defense-in-depth fallback only — fire-and-forget at OpenClaw's call site, races the compactor, exists for the rare case the proximity heuristic in `before_prompt_build` missed a sudden token jump. v0.3.0 did the pre-emptive extraction from `ContextEngine.compact()` via `delegateCompactionToRuntime()`; v0.10.0 moves it into `before_prompt_build` where it has a real pre-LLM hook to await on. ClawMem does not implement compaction itself — if you want compression in the same OpenClaw runtime, install a context-engine plugin (e.g. `lossless-claw`) into the context-engine slot, which v0.10.0 no longer occupies.
 
 ---
 
@@ -786,7 +794,7 @@ clawmem focus clear --session-id abc123
 - Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs and runs Phase 2 merge / Phase 3 deductive synthesis. **v0.8.2:** hosted by either `clawmem watch` (long-lived, canonical) or `clawmem mcp` (per-session fallback); every tick acquires a `light-consolidation` `worker_leases` row before doing work, so dual-hosting against the same vault is safe.
 - Beads integration: `syncBeadsIssues()` queries `bd` CLI (Dolt backend, v0.58.0+), creates markdown docs, maps dependency edges into `memory_relations`. Watcher auto-triggers on `.beads/` changes; `beads_sync` MCP for manual sync.
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
-- OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers as native OpenClaw context engine. Dual-mode: shares vault with Claude Code hooks. Uses `before_prompt_build` for retrieval, `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation (v0.3.0+, required for OpenClaw v2026.3.28+).
+- OpenClaw memory plugin (v0.10.0+): `clawmem setup openclaw` — registers as native OpenClaw memory plugin (`kind: memory`). Dual-mode: shares vault with Claude Code hooks. Hook wiring on the plugin-hook bus: `before_prompt_build` is the **load-bearing** path — it runs prompt-aware retrieval AND the pre-emptive `precompact-extract` synchronously when token usage approaches the compaction threshold, so state is captured before the LLM call that could trigger compaction. `agent_end` runs decision-extractor + handoff-generator + feedback-loop in parallel (fire-and-forget at OpenClaw's call site). `before_compaction` is **defense-in-depth fallback only** — fire-and-forget, races the compactor, exists for the rare case where the proximity heuristic in `before_prompt_build` missed a sudden token jump. `session_start` registers the session + caches first-turn bootstrap context. The §14.3 migration removed the `ClawMemContextEngine` class and moved the plugin from the `context-engine` slot to the `memory` slot. Requires OpenClaw v2026.4.11+ (earlier versions do not support the new discovery contract).
 - Hermes Agent MemoryProvider plugin: `src/hermes/` — Python plugin for Hermes's memory system. Shell-out hooks for lifecycle (prefetch, extraction, precompact), REST API for tools. Plugin-managed transcript JSONL bridges Hermes turn pairs to ClawMem file format. Shares vault with Claude Code and OpenClaw.
 
 ## Tool Selection (one-liner)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clawmem",
-  "version": "0.9.0",
-  "description": "On-device context engine and memory for AI agents. Claude Code and OpenClaw. Hooks + MCP server + hybrid RAG search.",
+  "version": "0.10.0",
+  "description": "On-device memory layer for AI agents. Claude Code, OpenClaw, and Hermes. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {
     "clawmem": "./bin/clawmem"

package/src/clawmem.ts

@@ -1304,8 +1304,28 @@ function cmdPath() {
   console.log(getDefaultDbPath());
 }
 
+/**
+ * Read a single OpenClaw config key via `openclaw config get <key>`. Returns
+ * the trimmed string value, or undefined when the key is unset / the CLI is
+ * unavailable / the key is missing. Callers should treat undefined as
+ * "no opinion" rather than "definitely unset".
+ */
+function readOpenClawConfigValue(key: string): string | undefined {
+  try {
+    const r = Bun.spawnSync(["openclaw", "config", "get", key], { stdout: "pipe", stderr: "pipe" });
+    if (r.exitCode !== 0) return undefined;
+    const out = new TextDecoder().decode(r.stdout).trim();
+    if (!out) return undefined;
+    // `openclaw config get` may print JSON ("clawmem"\n) or raw (clawmem). Strip quotes.
+    return out.replace(/^"(.*)"$/, "$1");
+  } catch {
+    return undefined;
+  }
+}
+
 async function cmdSetupOpenClaw(args: string[]) {
   const remove = args.includes("--remove");
+  const linkMode = args.includes("--link");
   const pluginDir = pathResolve(import.meta.dir, "openclaw");
   const extensionsDir = pathResolve(process.env.HOME || "~", ".openclaw", "extensions");
   const linkPath = pathResolve(extensionsDir, "clawmem");
@@ -1339,10 +1359,21 @@ async function cmdSetupOpenClaw(args: string[]) {
     }
 
     if (hasOpenClawCli) {
-      Bun.spawnSync(["openclaw", "config", "set", "plugins.slots.contextEngine", "legacy"], { stdout: "inherit", stderr: "inherit" });
-      console.log(`${c.green}Reset context engine slot to legacy${c.reset}`);
+      // Reset the memory slot if ClawMem owned it (post-§14.3-migration installs).
+      const memSlot = readOpenClawConfigValue("plugins.slots.memory");
+      if (memSlot === "clawmem") {
+        Bun.spawnSync(["openclaw", "config", "unset", "plugins.slots.memory"], { stdout: "inherit", stderr: "inherit" });
+        console.log(`${c.green}Cleared memory slot (was clawmem)${c.reset}`);
+      }
+      // Reset the legacy context-engine slot if any pre-§14.3-migration install
+      // left it pointing at clawmem.
+      const ceSlot = readOpenClawConfigValue("plugins.slots.contextEngine");
+      if (ceSlot === "clawmem") {
+        Bun.spawnSync(["openclaw", "config", "set", "plugins.slots.contextEngine", "legacy"], { stdout: "inherit", stderr: "inherit" });
+        console.log(`${c.green}Reset context engine slot to legacy (was clawmem)${c.reset}`);
+      }
     } else if (removed) {
-      console.log(`${c.dim}openclaw CLI not found — manually run: openclaw config set plugins.slots.contextEngine legacy${c.reset}`);
+      console.log(`${c.dim}openclaw CLI not found — manually clear: openclaw config unset plugins.slots.memory && openclaw config set plugins.slots.contextEngine legacy${c.reset}`);
     }
     return;
   }
@@ -1354,42 +1385,86 @@ async function cmdSetupOpenClaw(args: string[]) {
   if (!existsSync(pathResolve(pluginDir, "openclaw.plugin.json"))) {
     die(`Plugin manifest not found at ${pluginDir}/openclaw.plugin.json`);
   }
+  if (!existsSync(pathResolve(pluginDir, "package.json"))) {
+    die(`Plugin package.json not found at ${pluginDir}/package.json — required for OpenClaw v2026.4.11+ discovery`);
+  }
 
   // Create extensions directory
   if (!existsSync(extensionsDir)) {
     mkdirSync(extensionsDir, { recursive: true });
   }
 
-  // Remove stale symlink/directory if present
+  // Remove any stale install (symlink or directory) before re-installing.
+  // OpenClaw v2026.4.11+ discovery (discoverInDirectory in ids-*.js) uses
+  // readdirSync({ withFileTypes: true }) where symlinks report
+  // isDirectory() === false and get silently skipped, so copy mode is the
+  // default. The --link flag keeps symlink behavior for older OpenClaw
+  // versions or local development workflows where editing the live source
+  // should take effect without re-running setup.
   try {
     const { lstatSync, unlinkSync, rmSync } = await import("fs");
     const stat = lstatSync(linkPath);
     if (stat.isSymbolicLink()) {
-      const { readlinkSync } = await import("fs");
-      const target = readlinkSync(linkPath);
-      if (target === pluginDir) {
-        console.log(`${c.dim}Symlink already correct at ${linkPath}${c.reset}`);
-      } else {
-        unlinkSync(linkPath);
-        console.log(`${c.dim}Replaced stale symlink (was → ${target})${c.reset}`);
-      }
+      unlinkSync(linkPath);
+      console.log(`${c.dim}Replaced stale symlink at ${linkPath}${c.reset}`);
     } else if (stat.isDirectory()) {
       rmSync(linkPath, { recursive: true });
       console.log(`${c.dim}Replaced existing directory at ${linkPath}${c.reset}`);
     } else {
-      // Regular file or other non-symlink, non-directory — conflict
       die(`${linkPath} exists but is not a symlink or directory. Remove it manually and re-run setup.`);
     }
   } catch (e: any) {
     if (e.code !== "ENOENT") throw e;
   }
 
-  // Create symlink
-  if (!existsSync(linkPath)) {
+  if (linkMode) {
     const { symlinkSync } = await import("fs");
     symlinkSync(pluginDir, linkPath);
+    console.log(`${c.green}Installed plugin: ${linkPath} → ${pluginDir} (symlink)${c.reset}`);
+    console.log(`${c.yellow}  Warning: symlink mode. OpenClaw v2026.4.11+ discovery skips${c.reset}`);
+    console.log(`${c.yellow}  symlinks silently. Re-run without --link on current releases.${c.reset}`);
+  } else {
+    const { cpSync } = await import("fs");
+    cpSync(pluginDir, linkPath, { recursive: true, dereference: true });
+    console.log(`${c.green}Installed plugin: ${linkPath} (copied from ${pluginDir})${c.reset}`);
+  }
+
+  // ----- §14.3 upgrade migration -----
+  // ClawMem v0.10.0 changed `kind: "context-engine"` to `kind: "memory"`.
+  // Existing installs with `plugins.slots.contextEngine = "clawmem"` will hit
+  // a hard runtime error after upgrading because OpenClaw's
+  // `resolveContextEngine()` throws on unknown engine ids. Detect and rewrite
+  // the stale config to "legacy" so OpenClaw's built-in LegacyContextEngine
+  // takes over compaction. Also detect any pre-existing `plugins.slots.memory`
+  // assignment so we don't clobber a user's choice during upgrade.
+  let migrationApplied = false;
+  if (hasOpenClawCli) {
+    const staleContextEngine = readOpenClawConfigValue("plugins.slots.contextEngine");
+    if (staleContextEngine === "clawmem") {
+      console.log();
+      console.log(`${c.bold}${c.cyan}Upgrade migration detected:${c.reset}`);
+      console.log(`  Found legacy ClawMem context-engine slot config from v0.9.x or earlier.`);
+      console.log(`  Rewriting plugins.slots.contextEngine: clawmem → legacy`);
+      console.log(`  ${c.dim}(ClawMem now registers as a memory plugin. OpenClaw's built-in${c.reset}`);
+      console.log(`  ${c.dim} LegacyContextEngine will handle compaction unless you install a${c.reset}`);
+      console.log(`  ${c.dim} third-party context-engine plugin like hermes-lcm.)${c.reset}`);
+      const migrate = Bun.spawnSync(
+        ["openclaw", "config", "set", "plugins.slots.contextEngine", "legacy"],
+        { stdout: "inherit", stderr: "inherit" },
+      );
+      if (migrate.exitCode === 0) {
+        migrationApplied = true;
+      } else {
+        console.log(`${c.yellow}  Warning: failed to rewrite stale config — please run manually:${c.reset}`);
+        console.log(`    ${c.cyan}openclaw config set plugins.slots.contextEngine legacy${c.reset}`);
+      }
+    }
+  } else {
+    console.log();
+    console.log(`${c.dim}Upgrade migration skipped — openclaw CLI not on PATH. If upgrading${c.reset}`);
+    console.log(`${c.dim}from v0.9.x or earlier, manually run:${c.reset}`);
+    console.log(`  ${c.cyan}openclaw config set plugins.slots.contextEngine legacy${c.reset}`);
   }
-  console.log(`${c.green}Installed plugin: ${linkPath} → ${pluginDir}${c.reset}`);
 
   // Version warning
   console.log();
@@ -1397,17 +1472,21 @@ async function cmdSetupOpenClaw(args: string[]) {
   console.log(`have a bug where plugins.slots.contextEngine is silently dropped`);
   console.log(`during config normalization (openclaw/openclaw#64192).`);
 
-  // Remaining steps — gateway must restart BEFORE setting the context engine slot,
-  // otherwise OpenClaw hasn't discovered the plugin yet and the slot assignment
-  // fails or is ignored (the exact bug reported in issue #5).
+  // Remaining steps. CLI discovery finds the plugin immediately because the
+  // plugin dir now ships a package.json with openclaw.extensions declared, so
+  // `openclaw plugins enable clawmem` can run before any gateway restart.
+  // The enable command switches the exclusive memory slot to clawmem and
+  // disables memory-core/memory-lancedb automatically. Then the gateway
+  // restart applies the new slot assignment.
   console.log();
   console.log(`${c.bold}Next steps:${c.reset}`);
   console.log();
-  console.log(`  1. Restart OpenClaw gateway to discover the plugin:`);
-  console.log(`     ${c.cyan}openclaw gateway restart${c.reset}`);
+  console.log(`  1. Enable ClawMem as the active memory plugin:`);
+  console.log(`     ${c.cyan}openclaw plugins enable clawmem${c.reset}`);
+  console.log(`     ${c.dim}(Switches plugins.slots.memory to clawmem and disables memory-core if active.)${c.reset}`);
   console.log();
-  console.log(`  2. Set ClawMem as the active context engine (after restart):`);
-  console.log(`     ${c.cyan}openclaw config set plugins.slots.contextEngine clawmem${c.reset}`);
+  console.log(`  2. Restart the gateway to apply:`);
+  console.log(`     ${c.cyan}openclaw gateway restart${c.reset}`);
   console.log();
   console.log(`  3. Configure GPU endpoints (if not using defaults):`);
   console.log(`     ${c.cyan}openclaw config set plugins.entries.clawmem.config.gpuEmbed http://YOUR_GPU:8088${c.reset}`);
@@ -1417,7 +1496,24 @@ async function cmdSetupOpenClaw(args: string[]) {
   console.log(`  4. Start the REST API (for agent tools):`);
   console.log(`     ${c.cyan}clawmem serve &${c.reset}`);
   console.log();
+  console.log(`${c.bold}Important: keep dreaming disabled${c.reset}`);
+  console.log(`  ClawMem runs its own consolidation workers (CLAWMEM_ENABLE_CONSOLIDATION`);
+  console.log(`  light lane and CLAWMEM_HEAVY_LANE heavy lane). Keep ${c.cyan}dreaming.enabled = false${c.reset}`);
+  console.log(`  in OpenClaw's memory config to avoid auto-loading the bundled memory-core`);
+  console.log(`  dreaming engine alongside ClawMem (#65411 coexistence rule).`);
+  console.log();
+  console.log(`${c.bold}Compaction:${c.reset} OpenClaw's built-in LegacyContextEngine handles compaction`);
+  console.log(`by default. Install a third-party context-engine plugin (hermes-lcm, etc.)`);
+  console.log(`if you want a different compaction strategy. ClawMem injects pre-emptive`);
+  console.log(`precompact state via ${c.cyan}before_prompt_build${c.reset} when token usage approaches the`);
+  console.log(`compaction threshold.`);
+  console.log();
   console.log(`${c.dim}ClawMem will work alongside Claude Code hooks — both modes share the same vault.${c.reset}`);
+
+  if (migrationApplied) {
+    console.log();
+    console.log(`${c.green}✓ Upgrade migration applied — restart OpenClaw to pick up the new plugin kind.${c.reset}`);
+  }
 }
 
 function findClawmemBinary(): string {
@@ -1735,6 +1831,37 @@ async function cmdDoctor() {
     // Skip
   }
 
+  // 8. OpenClaw plugin slot config (§14.3 upgrade migration check)
+  try {
+    const stale = readOpenClawConfigValue("plugins.slots.contextEngine");
+    if (stale === "clawmem") {
+      console.log(
+        `${c.red}✗${c.reset} OpenClaw config: stale ${c.cyan}plugins.slots.contextEngine = "clawmem"${c.reset}`,
+      );
+      console.log(
+        `   ${c.dim}ClawMem v0.10.0 is now a memory plugin. Run ${c.cyan}clawmem setup openclaw${c.dim} to migrate,${c.reset}`,
+      );
+      console.log(
+        `   ${c.dim}or manually: ${c.cyan}openclaw config set plugins.slots.contextEngine legacy${c.reset}`,
+      );
+      issues++;
+    } else if (stale && stale !== "legacy") {
+      console.log(
+        `${c.green}✓${c.reset} OpenClaw context-engine slot: ${c.cyan}${stale}${c.reset} (third-party LCM)`,
+      );
+    }
+    const memSlot = readOpenClawConfigValue("plugins.slots.memory");
+    if (memSlot === "clawmem") {
+      console.log(`${c.green}✓${c.reset} OpenClaw memory slot: ${c.cyan}clawmem${c.reset}`);
+    } else if (memSlot) {
+      console.log(
+        `${c.dim}-${c.reset} OpenClaw memory slot: ${c.cyan}${memSlot}${c.reset} (ClawMem hooks will not fire under this agent)`,
+      );
+    }
+  } catch {
+    // openclaw CLI unavailable — skip silently
+  }
+
   console.log();
   if (issues > 0) {
     console.log(`${c.yellow}${issues} issue(s) found.${c.reset}`);