clawmem 0.10.0 → 0.10.2

package/AGENTS.md

@@ -208,6 +208,8 @@ 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.
 
+**memory-core dreaming sidecar coexistence (v2026.4.18+, #65411):** ClawMem and `memory-core` dreaming can also run side-by-side. When ClawMem owns the memory slot AND `plugins.entries.memory-core.config.dreaming.enabled = true`, OpenClaw loads `memory-core`'s dreaming engine alongside ClawMem (rest of `memory-core` stays unloaded). Dreaming continues writing to `memory/dreaming/{phase}/YYYY-MM-DD.md` (separate from ClawMem's vault). Default after `openclaw plugins enable clawmem` is `dreaming.enabled = false` (ClawMem-only). Set it `true` if you want to keep the dreaming output stream alongside ClawMem.
+
 **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+.
@@ -740,5 +742,6 @@ clawmem focus clear --session-id abc123
 - 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.
+- **v2026.4.18 synchronous-`register()` constraint:** OpenClaw v2026.4.18 (`fix(plugins): enforce synchronous registration`) throws `"plugin register must be synchronous"` if the plugin's `register()` function returns a Promise. ClawMem's `register(api)` in `src/openclaw/index.ts` is intentionally synchronous — all `await` work lives inside per-event handlers, never in registration itself. Companion change: register failures now atomically roll back side effects (globals, hook registrations, tool registrations), so any future throw inside `register()` will leave OpenClaw in a clean state. Keep the function synchronous and throw-free; do not add `async` or top-level `await`.
 - **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.
+- Hermes Agent MemoryProvider plugin: `src/hermes/` — Python plugin implementing Hermes's `MemoryProvider` ABC. **Preferred install:** copy into `$HERMES_HOME/plugins/clawmem/` (typically `~/.hermes/plugins/clawmem/`) — Hermes #10529 (v2026.4.13+) added user-plugin discovery, so this path survives `git pull` of hermes-agent. **Bundled-style install:** `hermes-agent/plugins/memory/clawmem/` still works (bundled-first precedence on name collisions). 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. **Agent-context isolation:** `initialize()` reads the `agent_context` kwarg Hermes passes ("primary"/"subagent"/"cron"/"flush"); for non-primary contexts the read-side hooks (session-bootstrap, context-surfacing) still run but the write-side surfaces (`sync_turn` transcript appends, `on_session_end` extraction, `on_pre_compress` precompact) early-return so cron system prompts and subagent intermediate state never reach the vault.

package/CLAUDE.md

@@ -208,6 +208,8 @@ 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.
 
+**memory-core dreaming sidecar coexistence (v2026.4.18+, #65411):** ClawMem and `memory-core` dreaming can also run side-by-side. When ClawMem owns the memory slot AND `plugins.entries.memory-core.config.dreaming.enabled = true`, OpenClaw loads `memory-core`'s dreaming engine alongside ClawMem (rest of `memory-core` stays unloaded). Dreaming continues writing to `memory/dreaming/{phase}/YYYY-MM-DD.md` (separate from ClawMem's vault). Default after `openclaw plugins enable clawmem` is `dreaming.enabled = false` (ClawMem-only). Set it `true` if you want to keep the dreaming output stream alongside ClawMem.
+
 **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+.
@@ -740,5 +742,6 @@ clawmem focus clear --session-id abc123
 - 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.
+- **v2026.4.18 synchronous-`register()` constraint:** OpenClaw v2026.4.18 (`fix(plugins): enforce synchronous registration`) throws `"plugin register must be synchronous"` if the plugin's `register()` function returns a Promise. ClawMem's `register(api)` in `src/openclaw/index.ts` is intentionally synchronous — all `await` work lives inside per-event handlers, never in registration itself. Companion change: register failures now atomically roll back side effects (globals, hook registrations, tool registrations), so any future throw inside `register()` will leave OpenClaw in a clean state. Keep the function synchronous and throw-free; do not add `async` or top-level `await`.
 - **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.
+- Hermes Agent MemoryProvider plugin: `src/hermes/` — Python plugin implementing Hermes's `MemoryProvider` ABC. **Preferred install:** copy into `$HERMES_HOME/plugins/clawmem/` (typically `~/.hermes/plugins/clawmem/`) — Hermes #10529 (v2026.4.13+) added user-plugin discovery, so this path survives `git pull` of hermes-agent. **Bundled-style install:** `hermes-agent/plugins/memory/clawmem/` still works (bundled-first precedence on name collisions). 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. **Agent-context isolation:** `initialize()` reads the `agent_context` kwarg Hermes passes ("primary"/"subagent"/"cron"/"flush"); for non-primary contexts the read-side hooks (session-bootstrap, context-surfacing) still run but the write-side surfaces (`sync_turn` transcript appends, `on_session_end` extraction, `on_pre_compress` precompact) early-return so cron system prompts and subagent intermediate state never reach the vault.

package/README.md

@@ -203,7 +203,7 @@ Disable OpenClaw's native memory search to avoid duplicate injection:
 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+) and, on OpenClaw v2026.4.18+ (#65411), with the `memory-core` dreaming sidecar — both run alongside ClawMem instead of being mutually exclusive. They search different backends and inject into different prompt regions, so they do not conflict. See the [OpenClaw plugin guide — Active Memory coexistence](docs/guides/openclaw-plugin.md#coexistence-with-openclaw-active-memory) and the [memory-core dreaming sidecar section](docs/guides/openclaw-plugin.md#coexistence-with-memory-core-dreaming-sidecar) for the two patterns.
 
 **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.
 
@@ -218,11 +218,16 @@ ClawMem integrates as a native MemoryProvider plugin — Hermes's pluggable inte
 **Install:**
 
 ```bash
-# Copy or symlink the plugin into Hermes's plugin directory
+# Preferred — user-plugin path (Hermes #10529, v2026.4.13+).
+# Survives `git pull` of hermes-agent and avoids dual-registration with bundled providers.
+cp -r /path/to/ClawMem/src/hermes ${HERMES_HOME:-~/.hermes}/plugins/clawmem
+
+# Or, the bundled-style path (always supported, takes precedence on name collisions).
+# Recommended only when you actively work in the hermes-agent source tree.
 cp -r /path/to/ClawMem/src/hermes /path/to/hermes-agent/plugins/memory/clawmem
 
-# Or symlink for development
-ln -s /path/to/ClawMem/src/hermes /path/to/hermes-agent/plugins/memory/clawmem
+# Symlink alternative for in-place development (either path).
+ln -s /path/to/ClawMem/src/hermes ${HERMES_HOME:-~/.hermes}/plugins/clawmem
 ```
 
 **Configure** in your Hermes profile's `.env` or environment:
@@ -327,6 +332,7 @@ If your GPU lives on a separate machine, point the env vars at it:
 ```bash
 export CLAWMEM_EMBED_URL=http://gpu-host:8088
 export CLAWMEM_LLM_URL=http://gpu-host:8089
+export CLAWMEM_LLM_MODEL=qwen3
 export CLAWMEM_RERANK_URL=http://gpu-host:8090
 ```
 
@@ -939,6 +945,9 @@ Notes referenced by the agent during a session get boosted (`access_count++`). U
 | `CLAWMEM_EMBED_TPM_LIMIT` | `100000` | Tokens-per-minute limit for cloud embedding pacing. Match to your provider tier. |
 | `CLAWMEM_EMBED_DIMENSIONS` | (none) | Output dimensions for OpenAI `text-embedding-3-*` Matryoshka models (e.g. `512`, `1024`). |
 | `CLAWMEM_LLM_URL` | `http://localhost:8089` | LLM server URL for intent/query/A-MEM. Without it, falls to `node-llama-cpp` (if allowed). |
+| `CLAWMEM_LLM_MODEL` | `qwen3` | Model name sent to the configured LLM endpoint. Override this for OpenAI-compatible proxies such as `gpt-5.4-mini`. |
+| `CLAWMEM_LLM_REASONING_EFFORT` | (none) | Optional top-level `reasoning_effort` field for Chat Completions endpoints that support it (for example OpenAI reasoning models). Leave unset for llama-server/vLLM unless your serving stack explicitly accepts that field. |
+| `CLAWMEM_LLM_NO_THINK` | `true` | Append `/no_think` to remote LLM prompts. Set to `false` for standard OpenAI models and other endpoints that reject or treat the Qwen-style suffix as literal prompt text. |
 | `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server URL. Without it, falls to `node-llama-cpp` (if allowed). |
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Block `node-llama-cpp` from auto-downloading GGUF models. Set `true` for remote-only setups where you want fail-fast on unreachable endpoints. |
 | `CLAWMEM_MERGE_SCORE_NORMAL` | `0.93` | **v0.7.1.** Phase 2 consolidation merge-safety threshold when candidate and existing anchors align. Merges above this normalized 3-gram cosine score are allowed. |
@@ -1105,8 +1114,12 @@ Index your content directories with `clawmem bootstrap` as above. The OpenClaw p
 #### Hermes-specific
 
 ```bash
-# Install the memory provider plugin (symlink or copy)
-ln -s $(npm root -g)/clawmem/src/hermes /path/to/hermes-agent/plugins/memory/clawmem
+# Install the memory provider plugin.
+# Preferred: $HERMES_HOME/plugins/clawmem/ (user-plugin path, Hermes #10529, v2026.4.13+).
+ln -s $(npm root -g)/clawmem/src/hermes ${HERMES_HOME:-~/.hermes}/plugins/clawmem
+
+# Bundled-style path is also supported (takes precedence on name collisions):
+#   ln -s $(npm root -g)/clawmem/src/hermes /path/to/hermes-agent/plugins/memory/clawmem
 
 # Start the REST API (required for Hermes tool calls)
 clawmem serve --port 7438 &

package/SKILL.md

@@ -607,6 +607,8 @@ Phase 3 deductive synthesis applies the same `contradicts` link for any draft th
 
 **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.
 
+**memory-core dreaming sidecar coexistence (v2026.4.18+, #65411):** When ClawMem owns the memory slot AND `plugins.entries.memory-core.config.dreaming.enabled = true`, OpenClaw loads `memory-core`'s dreaming engine alongside ClawMem (rest of `memory-core` stays unloaded). Default after `openclaw plugins enable clawmem` is `dreaming.enabled = false` (ClawMem-only). Set it `true` to keep the dreaming output stream (`memory/dreaming/{phase}/YYYY-MM-DD.md`) alongside ClawMem.
+
 **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.
@@ -795,7 +797,7 @@ clawmem focus clear --session-id abc123
 - 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 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.
+- 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. **Preferred install path:** `$HERMES_HOME/plugins/clawmem/` (Hermes #10529 user-plugin discovery, v2026.4.13+) — survives `git pull` of hermes-agent. The bundled `hermes-agent/plugins/memory/clawmem/` path still works. **Agent-context isolation:** read-side hooks always run; write-side surfaces (`sync_turn`, `on_session_end`, `on_pre_compress`) early-return when `agent_context != "primary"` so cron/subagent state never reaches the vault.
 
 ## Tool Selection (one-liner)
 

package/package.json

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

package/src/clawmem.ts

@@ -1491,6 +1491,7 @@ async function cmdSetupOpenClaw(args: string[]) {
   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}`);
   console.log(`     ${c.cyan}openclaw config set plugins.entries.clawmem.config.gpuLlm http://YOUR_GPU:8089${c.reset}`);
+  console.log(`     ${c.cyan}openclaw config set plugins.entries.clawmem.config.gpuLlmModel qwen3${c.reset}`);
   console.log(`     ${c.cyan}openclaw config set plugins.entries.clawmem.config.gpuRerank http://YOUR_GPU:8090${c.reset}`);
   console.log();
   console.log(`  4. Start the REST API (for agent tools):`);

package/src/hermes/__init__.py

@@ -15,7 +15,21 @@ Config via environment variables:
   CLAWMEM_PROFILE       — Retrieval profile: speed, balanced, deep (default: balanced)
   CLAWMEM_EMBED_URL     — GPU embedding server URL (optional)
   CLAWMEM_LLM_URL       — GPU LLM server URL (optional)
+  CLAWMEM_LLM_MODEL     — Model name sent to the GPU/cloud LLM endpoint (optional)
+  CLAWMEM_LLM_REASONING_EFFORT — Top-level reasoning_effort for supporting Chat Completions endpoints (optional)
+  CLAWMEM_LLM_NO_THINK  — Append /no_think to remote prompts; false disables it for standard OpenAI models (optional)
   CLAWMEM_RERANK_URL    — GPU reranker server URL (optional)
+
+Agent-context isolation:
+  Hermes ``run_agent.py`` passes ``agent_context`` to ``initialize()``
+  with one of "primary", "subagent", "cron", or "flush". Per the
+  ``MemoryProvider`` ABC contract ("Providers should skip writes for
+  non-primary contexts (cron system prompts would corrupt user
+  representations)"), this plugin treats the read-side hooks
+  (session-bootstrap, context-surfacing) as always safe but routes the
+  write-side surfaces (transcript appends in ``sync_turn``, extraction
+  in ``on_session_end`` and ``on_pre_compress``) through a primary-only
+  guard. Non-primary contexts get retrieval but no vault writes.
 """
 
 from __future__ import annotations
@@ -223,6 +237,10 @@ class ClawMemProvider(MemoryProvider):
         self._serve_mode: str = "external"
         self._serve_proc: Optional[subprocess.Popen] = None
         self._env_extra: dict = {}
+        # Agent-context isolation. "primary" = full read+write; everything else
+        # ("subagent", "cron", "flush") = reads OK, writes suppressed. See file
+        # docstring for the ABC contract this implements.
+        self._agent_context: str = "primary"
 
         # Prefetch state (generation counter prevents stale overwrites)
         self._prefetch_result: str = ""
@@ -280,6 +298,24 @@ class ClawMemProvider(MemoryProvider):
                 "secret": False,
                 "env_var": "CLAWMEM_LLM_URL",
             },
+            {
+                "key": "llm_model",
+                "description": "Model name sent to the GPU LLM server (e.g., qwen3, gpt-5.4-mini)",
+                "secret": False,
+                "env_var": "CLAWMEM_LLM_MODEL",
+            },
+            {
+                "key": "llm_reasoning_effort",
+                "description": "Optional top-level reasoning_effort for Chat Completions endpoints that support it",
+                "secret": False,
+                "env_var": "CLAWMEM_LLM_REASONING_EFFORT",
+            },
+            {
+                "key": "llm_no_think",
+                "description": "Append /no_think to remote LLM prompts; disable for standard OpenAI models",
+                "secret": False,
+                "env_var": "CLAWMEM_LLM_NO_THINK",
+            },
         ]
 
     # -- Core lifecycle --------------------------------------------------------
@@ -301,9 +337,23 @@ class ClawMemProvider(MemoryProvider):
             self._port = _DEFAULT_PORT
         self._serve_mode = os.environ.get("CLAWMEM_SERVE_MODE", "external")
         self._hermes_home = kwargs.get("hermes_home", str(Path.home() / ".hermes"))
+        self._agent_context = str(kwargs.get("agent_context", "primary") or "primary")
+        if self._agent_context != "primary":
+            logger.info(
+                "clawmem: agent_context=%s — reads enabled, writes suppressed",
+                self._agent_context,
+            )
 
         # Build env for hook shell-outs (GPU endpoints, profile)
-        for var in ("CLAWMEM_EMBED_URL", "CLAWMEM_LLM_URL", "CLAWMEM_RERANK_URL", "CLAWMEM_PROFILE"):
+        for var in (
+            "CLAWMEM_EMBED_URL",
+            "CLAWMEM_LLM_URL",
+            "CLAWMEM_LLM_MODEL",
+            "CLAWMEM_LLM_REASONING_EFFORT",
+            "CLAWMEM_LLM_NO_THINK",
+            "CLAWMEM_RERANK_URL",
+            "CLAWMEM_PROFILE",
+        ):
             val = os.environ.get(var)
             if val:
                 self._env_extra[var] = val
@@ -410,7 +460,11 @@ class ClawMemProvider(MemoryProvider):
         """Append turn to plugin-managed transcript JSONL.
 
         Writes in Claude Code transcript format so ClawMem hooks can read it.
+        Suppressed for non-primary agent contexts (subagent/cron/flush) so the
+        vault never absorbs system-prompt or background-task content.
         """
+        if self._agent_context != "primary":
+            return
         if not self._transcript_path:
             return
 
@@ -441,7 +495,15 @@ class ClawMemProvider(MemoryProvider):
     # -- Session end / compression hooks ---------------------------------------
 
     def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
-        """Run extraction hooks in parallel."""
+        """Run extraction hooks in parallel.
+
+        Suppressed for non-primary agent contexts (subagent/cron/flush) — the
+        decision-extractor / handoff-generator / feedback-loop pipeline would
+        otherwise capture cron system prompts or subagent intermediate state
+        as if it were primary-agent reasoning.
+        """
+        if self._agent_context != "primary":
+            return
         if not self._bin or not self._transcript_path:
             return
 
@@ -470,7 +532,13 @@ class ClawMemProvider(MemoryProvider):
         logger.info("clawmem: session %s extraction complete", self._session_id[:8])
 
     def on_pre_compress(self, messages: List[Dict[str, Any]]) -> str:
-        """Run precompact-extract (side effect only — Hermes ignores return)."""
+        """Run precompact-extract (side effect only — Hermes ignores return).
+
+        Suppressed for non-primary agent contexts so the precompact state file
+        in auto-memory never picks up cron/subagent context as primary state.
+        """
+        if self._agent_context != "primary":
+            return ""
         if not self._bin or not self._transcript_path:
             return ""
 

package/src/llm.ts

@@ -237,6 +237,23 @@ export type LlamaCppConfig = {
    * When set, generate() calls /v1/chat/completions instead of local node-llama-cpp.
    */
   remoteLlmUrl?: string;
+  /**
+   * Remote LLM model name to send with chat completion requests.
+   * Env: CLAWMEM_LLM_MODEL
+   */
+  remoteLlmModel?: string;
+  /**
+   * Optional top-level reasoning_effort field for Chat Completions endpoints that support it.
+   * Example values: none, minimal, low, medium, high, xhigh.
+   * Env: CLAWMEM_LLM_REASONING_EFFORT
+   */
+  remoteLlmReasoningEffort?: string;
+  /**
+   * Whether to append /no_think to remote LLM prompts.
+   * Defaults to true to preserve current behavior with Qwen3-compatible endpoints.
+   * Env: CLAWMEM_LLM_NO_THINK
+   */
+  remoteLlmNoThink?: boolean;
   /**
    * Inactivity timeout in ms before unloading contexts (default: 2 minutes, 0 to disable).
    *
@@ -259,6 +276,23 @@ export type LlamaCppConfig = {
  */
 // Default inactivity timeout: 2 minutes
 const DEFAULT_INACTIVITY_TIMEOUT_MS = 2 * 60 * 1000;
+const ALLOWED_REMOTE_LLM_REASONING_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh"]);
+
+function normalizeRemoteLlmReasoningEffort(value?: string): string | null {
+  const raw = (value || "").trim().toLowerCase();
+  if (!raw) return null;
+  if (!ALLOWED_REMOTE_LLM_REASONING_EFFORTS.has(raw)) {
+    console.warn(`[clawmem] Ignoring unsupported remoteLlmReasoningEffort=${raw}`);
+    return null;
+  }
+  return raw;
+}
+
+function buildRemoteChatCompletionsUrl(remoteLlmUrl: string): string {
+  const baseUrl = remoteLlmUrl.replace(/\/+$/, "");
+  const endpoint = baseUrl.endsWith("/v1") ? "/chat/completions" : "/v1/chat/completions";
+  return `${baseUrl}${endpoint}`;
+}
 
 export class LlamaCpp implements LLM {
   private llama: Llama | null = null;
@@ -276,6 +310,9 @@ export class LlamaCpp implements LLM {
   private remoteEmbedApiKey: string | null;
   private remoteEmbedModel: string;
   private remoteLlmUrl: string | null;
+  private remoteLlmModel: string;
+  private remoteLlmReasoningEffort: string | null;
+  private remoteLlmNoThink: boolean;
 
   // Ensure we don't load the same model concurrently (which can allocate duplicate VRAM).
   private embedModelLoadPromise: Promise<LlamaModel> | null = null;
@@ -306,6 +343,10 @@ export class LlamaCpp implements LLM {
     this.remoteEmbedApiKey = config.remoteEmbedApiKey || null;
     this.remoteEmbedModel = config.remoteEmbedModel || "embedding";
     this.remoteLlmUrl = config.remoteLlmUrl || null;
+    const normalizedRemoteLlmModel = config.remoteLlmModel?.trim();
+    this.remoteLlmModel = normalizedRemoteLlmModel || "qwen3";
+    this.remoteLlmReasoningEffort = normalizeRemoteLlmReasoningEffort(config.remoteLlmReasoningEffort);
+    this.remoteLlmNoThink = config.remoteLlmNoThink ?? true;
     this.inactivityTimeoutMs = config.inactivityTimeoutMs ?? DEFAULT_INACTIVITY_TIMEOUT_MS;
     this.disposeModelsOnInactivity = config.disposeModelsOnInactivity ?? false;
   }
@@ -921,15 +962,19 @@ export class LlamaCpp implements LLM {
     // Re-check: concurrent call may have set cooldown while we were awaited
     if (this.isRemoteLlmDown()) return null;
     try {
-      const resp = await fetch(`${this.remoteLlmUrl}/v1/chat/completions`, {
+      const body: Record<string, unknown> = {
+        model: this.remoteLlmModel,
+        messages: [{ role: "user", content: this.remoteLlmNoThink ? `${prompt} /no_think` : prompt }],
+        max_tokens: maxTokens,
+        temperature,
+      };
+      if (this.remoteLlmReasoningEffort) {
+        body.reasoning_effort = this.remoteLlmReasoningEffort;
+      }
+      const resp = await fetch(buildRemoteChatCompletionsUrl(this.remoteLlmUrl!), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-          model: "qwen3",
-          messages: [{ role: "user", content: `${prompt} /no_think` }],
-          max_tokens: maxTokens,
-          temperature,
-        }),
+        body: JSON.stringify(body),
         signal,
       });
 
@@ -1254,6 +1299,13 @@ export function getDefaultLlamaCpp(): LlamaCpp {
       remoteEmbedApiKey: embedApiKey,
       remoteEmbedModel: process.env.CLAWMEM_EMBED_MODEL || undefined,
       remoteLlmUrl: process.env.CLAWMEM_LLM_URL || undefined,
+      remoteLlmModel: process.env.CLAWMEM_LLM_MODEL?.trim() || undefined,
+      remoteLlmReasoningEffort: process.env.CLAWMEM_LLM_REASONING_EFFORT || undefined,
+      remoteLlmNoThink: (() => {
+        const raw = (process.env.CLAWMEM_LLM_NO_THINK || "").trim().toLowerCase();
+        if (!raw) return undefined;
+        return !["0", "false", "no", "off"].includes(raw);
+      })(),
     });
   }
   return defaultLlamaCpp;
@@ -1276,4 +1328,3 @@ export async function disposeDefaultLlamaCpp(): Promise<void> {
     defaultLlamaCpp = null;
   }
 }
-

package/src/openclaw/index.ts

@@ -37,8 +37,8 @@
  *   4. REST API service (`clawmem serve`) lifecycle — unchanged.
  *
  * §14.3 critical correctness contract: `agent_end` is fire-and-forget at
- * `attempt.ts:2226-2249`. Precompact-extract MUST run inside
- * `handleBeforePromptBuild` (which IS awaited at `attempt.ts:1661`), gated
+ * `attempt.ts:2470-2496`. Precompact-extract MUST run inside
+ * `handleBeforePromptBuild` (which IS awaited at `attempt.ts:1873`), gated
  * by the proximity heuristic in `compaction-threshold.ts`. See `engine.ts`
  * top-of-file comment for the full rationale.
  */
@@ -89,7 +89,7 @@ const clawmemPlugin = {
   name: "ClawMem",
   description:
     "On-device hybrid memory layer for OpenClaw — composite scoring, graph traversal, lifecycle management, and pre-emptive compaction state extraction",
-  version: "0.10.0",
+  version: "0.10.1",
   kind: "memory" as const,
 
   register(api: any) {
@@ -107,6 +107,13 @@ const clawmemPlugin = {
       env: {
         ...(pluginCfg.gpuEmbed ? { CLAWMEM_EMBED_URL: pluginCfg.gpuEmbed as string } : {}),
         ...(pluginCfg.gpuLlm ? { CLAWMEM_LLM_URL: pluginCfg.gpuLlm as string } : {}),
+        ...(pluginCfg.gpuLlmModel ? { CLAWMEM_LLM_MODEL: pluginCfg.gpuLlmModel as string } : {}),
+        ...(pluginCfg.gpuLlmReasoningEffort
+          ? { CLAWMEM_LLM_REASONING_EFFORT: pluginCfg.gpuLlmReasoningEffort as string }
+          : {}),
+        ...(pluginCfg.gpuLlmNoThink !== undefined
+          ? { CLAWMEM_LLM_NO_THINK: String(pluginCfg.gpuLlmNoThink) }
+          : {}),
         ...(pluginCfg.gpuRerank ? { CLAWMEM_RERANK_URL: pluginCfg.gpuRerank as string } : {}),
         CLAWMEM_PROFILE: profile,
       },
@@ -154,7 +161,7 @@ const clawmemPlugin = {
     // ----- Plugin Hook: before_prompt_build (AWAITED — load-bearing path) -----
     // Both context-surfacing retrieval injection and pre-emptive precompact
     // extraction live here. handleBeforePromptBuild is async and the OpenClaw
-    // attempt path awaits the result at attempt.ts:1661 before building the
+    // attempt path awaits the result at attempt.ts:1873 before building the
     // effective prompt. precompact-extract therefore runs strictly before
     // the LLM call that could trigger compaction on this turn.
     api.on(
@@ -168,7 +175,7 @@ const clawmemPlugin = {
     // ----- Plugin Hook: agent_end (FIRE-AND-FORGET in core) -----
     // Decision-extractor, handoff-generator, and feedback-loop run here.
     // These writes are eventually-consistent (saveMemory dedupes), so the
-    // fire-and-forget context at attempt.ts:2226-2249 is acceptable.
+    // fire-and-forget context at attempt.ts:2470-2496 is acceptable.
     // precompact-extract is intentionally NOT in this handler — it lives
     // in handleBeforePromptBuild for correctness reasons.
     api.on("agent_end", async (event: AgentEndEvent, ctx: AgentEndContext) => {

package/src/openclaw/openclaw.plugin.json

@@ -41,6 +41,23 @@
       "help": "URL for ClawMem LLM (query expansion, extraction)",
       "advanced": true
     },
+    "gpuLlmModel": {
+      "label": "LLM Model",
+      "placeholder": "qwen3",
+      "help": "Model name sent to the configured LLM endpoint",
+      "advanced": true
+    },
+    "gpuLlmReasoningEffort": {
+      "label": "Reasoning Effort",
+      "placeholder": "(unset)",
+      "help": "Optional top-level reasoning_effort for Chat Completions endpoints that support it. Unset omits the field.",
+      "advanced": true
+    },
+    "gpuLlmNoThink": {
+      "label": "Append /no_think",
+      "help": "Append /no_think to remote LLM prompts (default: true). Disable for standard OpenAI models.",
+      "advanced": true
+    },
     "gpuRerank": {
       "label": "Reranker Endpoint",
       "placeholder": "http://localhost:8090",
@@ -78,6 +95,16 @@
       "gpuLlm": {
         "type": "string"
       },
+      "gpuLlmModel": {
+        "type": "string"
+      },
+      "gpuLlmReasoningEffort": {
+        "type": "string",
+        "enum": ["none", "minimal", "low", "medium", "high", "xhigh"]
+      },
+      "gpuLlmNoThink": {
+        "type": "boolean"
+      },
       "gpuRerank": {
         "type": "string"
       }

package/src/openclaw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem-openclaw-plugin",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "OpenClaw plugin adapter for ClawMem — on-device hybrid memory layer",
   "type": "module",
   "openclaw": {