clawmem 0.10.2 → 0.10.4

package/AGENTS.md

@@ -739,9 +739,10 @@ 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 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.
+- 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, plus a 30s default void-hook timeout from OpenClaw v2026.4.26+ that logs slow handlers but does not cancel the underlying postrun work); `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.
+- **Profile-aware install (v0.10.4, §28.1, issue #11):** `cmdSetupOpenClaw` is now a three-path installer. When `openclaw` is on `PATH` it delegates to `openclaw plugins install <pluginDir> --force` (or `-l` for `--link`), inheriting OpenClaw's destination resolution (`OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, `--profile`), manifest validation, security scan, install records, slot selection, and registry refresh. The plugin is auto-enabled — Path 1's "Next steps" output drops `openclaw plugins enable clawmem` because it's redundant. `--link` in delegated mode records the source in `plugins.load.paths` (NOT a filesystem symlink, so the v2026.4.11 discovery skip does NOT apply). When `openclaw` is absent, ClawMem falls back to recursive copy at a destination resolved by `src/openclaw-paths.ts:resolveExtensionsDirNoOpenClaw` — a faithful mirror of OpenClaw's `resolveConfigDir` (priority: `OPENCLAW_STATE_DIR` → `OPENCLAW_CONFIG_PATH` → `OPENCLAW_HOME`/`HOME`/`USERPROFILE`/`os.homedir()`/`cwd` → `~/.openclaw`). The fallback's filesystem symlink in `--link` mode is still subject to OpenClaw's discovery skip (warning surfaced). `--remove` tries `openclaw plugins uninstall clawmem --force` first; on failure (typical for legacy unmanaged direct-copy installs), warns the user that config/install records may need manual repair, then runs manual cleanup at the resolved path. On success, also performs a constrained stale cleanup of any leftover unmanaged directory at the same path. `--help` / `-h` short-circuits before any spawn or filesystem work and prints the full flag + env-var reference (§28.2). Helpers in `src/openclaw-paths.ts` take injected `env` + `homedir` for testability.
 - **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. **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

@@ -739,9 +739,10 @@ 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 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.
+- 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, plus a 30s default void-hook timeout from OpenClaw v2026.4.26+ that logs slow handlers but does not cancel the underlying postrun work); `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.
+- **Profile-aware install (v0.10.4, §28.1, issue #11):** `cmdSetupOpenClaw` is now a three-path installer. When `openclaw` is on `PATH` it delegates to `openclaw plugins install <pluginDir> --force` (or `-l` for `--link`), inheriting OpenClaw's destination resolution (`OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, `--profile`), manifest validation, security scan, install records, slot selection, and registry refresh. The plugin is auto-enabled — Path 1's "Next steps" output drops `openclaw plugins enable clawmem` because it's redundant. `--link` in delegated mode records the source in `plugins.load.paths` (NOT a filesystem symlink, so the v2026.4.11 discovery skip does NOT apply). When `openclaw` is absent, ClawMem falls back to recursive copy at a destination resolved by `src/openclaw-paths.ts:resolveExtensionsDirNoOpenClaw` — a faithful mirror of OpenClaw's `resolveConfigDir` (priority: `OPENCLAW_STATE_DIR` → `OPENCLAW_CONFIG_PATH` → `OPENCLAW_HOME`/`HOME`/`USERPROFILE`/`os.homedir()`/`cwd` → `~/.openclaw`). The fallback's filesystem symlink in `--link` mode is still subject to OpenClaw's discovery skip (warning surfaced). `--remove` tries `openclaw plugins uninstall clawmem --force` first; on failure (typical for legacy unmanaged direct-copy installs), warns the user that config/install records may need manual repair, then runs manual cleanup at the resolved path. On success, also performs a constrained stale cleanup of any leftover unmanaged directory at the same path. `--help` / `-h` short-circuits before any spawn or filesystem work and prints the full flag + env-var reference (§28.2). Helpers in `src/openclaw-paths.ts` take injected `env` + `homedir` for testability.
 - **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. **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

@@ -188,12 +188,18 @@ clawmem setup mcp      # Register MCP server in ~/.claude.json (31 tools)
 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   # Installs plugin into ~/.openclaw/extensions/clawmem (copy, not symlink)
+# v0.10.4+: profile-aware. Delegates to `openclaw plugins install --force` when the OpenClaw CLI
+# is on PATH (auto-enables the plugin, honors OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, --profile).
+# Falls back to a recursive copy honoring OPENCLAW_STATE_DIR when the CLI is absent.
+clawmem setup openclaw
+
+# Custom profile (e.g. dev profile at ~/.openclaw-dev):
+OPENCLAW_STATE_DIR=~/.openclaw-dev clawmem setup openclaw
 ```
 
 **What the plugin provides:**
 - **`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)
+- **`agent_end` hook** - decision extraction, handoff generation, feedback loop (parallel, fire-and-forget at the OpenClaw call site). OpenClaw v2026.4.26+ also enforces a 30s default void-hook timeout on `agent_end` — slow handlers are logged but the underlying postrun work is not cancelled (fail-open).
 - **`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`
@@ -1099,13 +1105,16 @@ clawmem install-service --enable
 #### OpenClaw-specific
 
 ```bash
-# Install the OpenClaw plugin (v0.10.0+: recursively copies into ~/.openclaw/extensions/clawmem)
+# Install the OpenClaw plugin
+# v0.10.4+: delegates to `openclaw plugins install --force` when the CLI is on PATH (auto-enables;
+#   honors OPENCLAW_STATE_DIR / OPENCLAW_CONFIG_PATH / --profile). Falls back to recursive copy
+#   honoring OPENCLAW_STATE_DIR when the CLI is absent.
+# v0.10.0–v0.10.3: hardcoded recursive copy into ~/.openclaw/extensions/clawmem (issue #11).
 clawmem setup openclaw
-# 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
+# Then follow the printed next steps. The exact list depends on which path ran:
+#   Path 1 (delegated): plugin already auto-enabled — just `openclaw gateway restart` + GPU config
+#   Path 3 (CLI absent): manually `openclaw plugins enable clawmem`, then restart + GPU config
+# Multi-user installs also need: sudo chown -R <gateway-user>:<gateway-group> <extensions>/clawmem
 # Requires OpenClaw v2026.4.11+.
 ```
 

package/SKILL.md

@@ -796,7 +796,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 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).
+- 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, plus a 30s default void-hook timeout from OpenClaw v2026.4.26+ that logs slow handlers but does not cancel the underlying postrun work). `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. **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.2",
+  "version": "0.10.4",
   "description": "On-device memory layer for AI agents. Claude Code, OpenClaw, and Hermes. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/amem.ts

@@ -22,50 +22,243 @@ const EMPTY_NOTE: MemoryNote = {
   context: ""
 };
 
-/**
- * Extract and parse JSON from LLM output, handling:
- * - Markdown code blocks (```json ... ```)
- * - Leading/trailing prose around JSON
- * - Truncated JSON from token limits (repairs arrays/objects)
- */
-export function extractJsonFromLLM(raw: string): any | null {
-  let text = raw.trim();
+function uniqueStrings(values: string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const value of values) {
+    const trimmed = value.trim();
+    if (!trimmed || seen.has(trimmed)) continue;
+    seen.add(trimmed);
+    out.push(trimmed);
+  }
+  return out;
+}
+
+type LinkRelationType = 'semantic' | 'supporting' | 'contradicts';
+
+type ParsedLinkGeneration = {
+  target_idx: number;
+  link_type: LinkRelationType;
+  confidence: number;
+  reasoning: string;
+};
+
+
+function isLinkRelationType(value: unknown): value is LinkRelationType {
+  return value === 'semantic' || value === 'supporting' || value === 'contradicts';
+}
+
+function isUnitIntervalNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+function isParsedLinkGeneration(value: unknown): value is ParsedLinkGeneration {
+  if (!value || typeof value !== 'object') return false;
+  const link = value as Record<string, unknown>;
+  return Number.isInteger(link.target_idx) &&
+    (link.target_idx as number) > 0 &&
+    isLinkRelationType(link.link_type) &&
+    isUnitIntervalNumber(link.confidence) &&
+    typeof link.reasoning === 'string';
+}
+
+export function parseMemoryNoteFromLLM(raw: string): MemoryNote | null {
+  const parsed = extractJsonFromLLM(raw) as Partial<MemoryNote> | null;
+  if (parsed && Array.isArray(parsed.keywords)) {
+    return {
+      keywords: parsed.keywords.filter((v): v is string => typeof v === 'string'),
+      tags: Array.isArray(parsed.tags) ? parsed.tags.filter((v): v is string => typeof v === 'string') : [],
+      context: typeof parsed.context === 'string' ? parsed.context : '',
+    };
+  }
+
+  const lines = raw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const keywords = uniqueStrings(lines.filter((line) => line.startsWith('lex:')).map((line) => line.slice(4).trim()));
+  const context = lines.find((line) => line.startsWith('hyde:'))?.slice(5).trim() ?? '';
+  if (keywords.length === 0 && !context) {
+    return null;
+  }
+
+  return {
+    keywords,
+    tags: [],
+    context,
+  };
+}
+
+export function parseLinkGenerationFromLLM(raw: string): ParsedLinkGeneration[] | null {
+  const parsed = extractJsonFromLLM(raw) as { result?: unknown } | unknown[] | null;
+  const wrapped = parsed && typeof parsed === 'object' ? parsed as { result?: unknown } : null;
+  const items = Array.isArray(parsed)
+    ? parsed
+    : wrapped && Array.isArray(wrapped.result)
+      ? wrapped.result
+      : null;
+
+  if (!items) return null;
+  const validItems = items.filter(isParsedLinkGeneration);
+  return validItems.length === items.length ? validItems : null;
+}
+
+function tryParseJsonWithCommaRepair(text: string): any | null {
+  // Repair missing commas between object fields without rewriting adjacent array strings.
+  const repaired = text.replace(
+    /(\]|\}|"(?:[^"\\]|\\.)*"|-?\d(?:[\d.eE+-])*|true|false|null)(\s*"[^"\n]+"\s*:)/g,
+    '$1,$2'
+  );
+  if (repaired === text) return null;
+  try {
+    return JSON.parse(repaired);
+  } catch {
+    return null;
+  }
+}
+
+function extractBalancedJsonCandidate(text: string): string | null {
+  if (text[0] !== '{' && text[0] !== '[') return null;
+
+  const stack: string[] = [text[0]!];
+  let inString = false;
+  let escaped = false;
+
+  for (let i = 1; i < text.length; i++) {
+    const ch = text[i]!;
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+      } else if (ch === '\\') {
+        escaped = true;
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+
+    if (ch === '{' || ch === '[') {
+      stack.push(ch);
+      continue;
+    }
+
+    if (ch === '}' || ch === ']') {
+      const expected = ch === '}' ? '{' : '[';
+      if (stack[stack.length - 1] !== expected) return null;
+      stack.pop();
+      if (stack.length === 0) return text.slice(0, i + 1);
+    }
+  }
+
+  return null;
+}
 
-  // Strip markdown code blocks
-  const codeBlock = text.match(/```(?:json)?\s*\n?([\s\S]*?)(?:\n```|$)/);
-  if (codeBlock) {
-    text = codeBlock[1]!.trim();
+function parseBalancedJsonValue(candidate: string): any | null {
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    return tryParseJsonWithCommaRepair(candidate);
+  }
+}
+
+function jsonStartsAtTrimmedLineStart(text: string, index: number): boolean {
+  const lineStart = text.lastIndexOf('\n', index - 1) + 1;
+  return text.slice(lineStart, index).trim().length === 0;
+}
+
+function findLineStartJsonAfter(text: string, index: number): number {
+  for (let i = index; i < text.length; i++) {
+    if ((text[i] === '{' || text[i] === '[') && jsonStartsAtTrimmedLineStart(text, i)) return i;
+  }
+  return -1;
+}
+
+function isLikelyInlineProseLiteral(text: string, index: number): boolean {
+  return !jsonStartsAtTrimmedLineStart(text, index) && !hasPayloadCueBefore(text, index);
+}
+
+function collectParseableBalancedJsonCandidates(
+  text: string,
+  startIndex: number
+): Array<{ start: number; parsed: any }> {
+  const candidates: Array<{ start: number; parsed: any }> = [];
+  for (let i = startIndex; i < text.length; i++) {
+    if (text[i] !== '{' && text[i] !== '[') continue;
+
+    const balancedCandidate = extractBalancedJsonCandidate(text.slice(i));
+    if (!balancedCandidate) continue;
+
+    const parsed = parseBalancedJsonValue(balancedCandidate);
+    if (parsed !== null) candidates.push({ start: i, parsed });
+
+    i += balancedCandidate.length - 1;
+  }
+  return candidates;
+}
+
+function selectBalancedJsonCandidate(text: string, candidates: Array<{ start: number; parsed: any }>): any | null {
+  if (candidates.length === 0) return null;
+
+  const payloadCandidate = candidates.find((candidate) => hasPayloadCueBefore(text, candidate.start));
+  if (payloadCandidate) return payloadCandidate.parsed;
+
+  const first = candidates[0]!;
+  if (candidates.length > 1 && (hasExampleCueBefore(text, first.start) || isLikelyInlineProseLiteral(text, first.start))) {
+    const laterPayload = candidates.find((candidate) =>
+      !hasExampleCueBefore(text, candidate.start) && !isLikelyInlineProseLiteral(text, candidate.start)
+    );
+    if (laterPayload) return laterPayload.parsed;
   }
 
-  // Find the first [ or { to skip leading prose
-  const arrStart = text.indexOf('[');
-  const objStart = text.indexOf('{');
+  return first.parsed;
+}
+
+function parseJsonCandidate(raw: string): any | null {
+  const trimmed = raw.trim();
+  const arrStart = trimmed.indexOf('[');
+  const objStart = trimmed.indexOf('{');
   if (arrStart === -1 && objStart === -1) return null;
 
   const start = arrStart === -1 ? objStart : objStart === -1 ? arrStart : Math.min(arrStart, objStart);
-  text = text.slice(start);
+  const text = trimmed.slice(start);
 
-  // Try parsing as-is first
   try {
     return JSON.parse(text);
   } catch {
-    // Attempt truncated JSON repair
+    // Try extracting balanced JSON values before lighter repairs.
   }
 
-  // Repair truncated arrays: find last complete object, close the array
+  const firstBalancedCandidate = extractBalancedJsonCandidate(text);
+  if (firstBalancedCandidate) {
+    if (hasExampleCueBefore(trimmed, start) || isLikelyInlineProseLiteral(trimmed, start)) {
+      const laterLineStartJson = findLineStartJsonAfter(trimmed, start + firstBalancedCandidate.length);
+      if (laterLineStartJson !== -1) {
+        const laterParsed = parseJsonCandidate(trimmed.slice(laterLineStartJson));
+        if (laterParsed !== null) return laterParsed;
+      }
+    }
+    const balancedParsed = selectBalancedJsonCandidate(
+      trimmed,
+      collectParseableBalancedJsonCandidates(trimmed, start)
+    );
+    if (balancedParsed !== null) return balancedParsed;
+  }
+
+  const commaRepaired = tryParseJsonWithCommaRepair(text);
+  if (commaRepaired !== null) return commaRepaired;
+
   if (text.startsWith('[')) {
     const lastBrace = text.lastIndexOf('}');
     if (lastBrace > 0) {
       const repaired = text.slice(0, lastBrace + 1) + ']';
       try { return JSON.parse(repaired); } catch { /* continue */ }
     }
-    // Might be an empty or trivial array
     try { return JSON.parse(text.replace(/,\s*$/, '') + ']'); } catch { /* continue */ }
   }
 
-  // Repair truncated objects: find last complete value, close the object
   if (text.startsWith('{')) {
-    // Try closing at each } from the end
     for (let i = text.length - 1; i > 0; i--) {
       if (text[i] === '}' || text[i] === '"' || text[i] === '0' || text[i] === '1' ||
           text[i] === '2' || text[i] === '3' || text[i] === '4' || text[i] === '5' ||
@@ -80,6 +273,201 @@ export function extractJsonFromLLM(raw: string): any | null {
   return null;
 }
 
+function collectFenceBlocks(text: string): Array<{ start: number; end: number; tag: string | null; body: string }> {
+  const lines = text.split('\n');
+  const fences: Array<{ start: number; end: number; tag: string | null; body: string }> = [];
+  let offset = 0;
+  let open: { start: number; tag: string | null; bodyLines: string[] } | null = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    const lineStart = offset;
+    const lineEnd = offset + line.length;
+
+    if (!open) {
+      const match = trimmed.match(/^```([^\s`]*)?\s*$/);
+      if (match) {
+        open = { start: lineStart, tag: match[1] || null, bodyLines: [] };
+      }
+    } else if (trimmed === '```') {
+      fences.push({
+        start: open.start,
+        end: Math.min(text.length, lineEnd + 1),
+        tag: open.tag,
+        body: open.bodyLines.join('\n').trim(),
+      });
+      open = null;
+    } else {
+      open.bodyLines.push(line);
+    }
+
+    offset = lineEnd + 1;
+  }
+
+  if (open) {
+    fences.push({
+      start: open.start,
+      end: text.length,
+      tag: open.tag,
+      body: open.bodyLines.join('\n').trim(),
+    });
+  }
+
+  return fences;
+}
+
+function stripAnyFences(text: string): string {
+  const ranges = collectAnyFenceRanges(text);
+  if (ranges.length === 0) return text.trim();
+
+  let out = '';
+  let cursor = 0;
+  for (const range of ranges) {
+    out += text.slice(cursor, range.start);
+    cursor = range.end;
+  }
+  out += text.slice(cursor);
+  return out.trim();
+}
+
+function collectStructuralFences(text: string): Array<{ body: string; isJson: boolean; start: number; end: number }> {
+  return collectFenceBlocks(text)
+    .filter((fence) => fence.tag === null || fence.tag === 'json')
+    .map((fence) => ({
+      body: fence.body,
+      isJson: fence.tag === 'json',
+      start: fence.start,
+      end: fence.end,
+    }));
+}
+
+function collectAnyFenceRanges(text: string): Array<{ start: number; end: number }> {
+  return collectFenceBlocks(text).map((fence) => ({ start: fence.start, end: fence.end }));
+}
+
+function findFirstJsonStartOutsideFences(
+  text: string,
+  fences: Array<{ start: number; end: number }>
+ ): number {
+  let fenceIndex = 0;
+  for (let i = 0; i < text.length; i++) {
+    while (fenceIndex < fences.length && i >= fences[fenceIndex]!.end) {
+      fenceIndex++;
+    }
+    if (fenceIndex < fences.length) {
+      const fence = fences[fenceIndex]!;
+      if (i >= fence.start && i < fence.end) {
+        i = fence.end - 1;
+        continue;
+      }
+    }
+    if (text[i] === '[' || text[i] === '{') return i;
+  }
+  return -1;
+}
+
+function hasExampleCueBefore(text: string, index: number): boolean {
+  let end = index;
+  while (end > 0 && /\s/.test(text[end - 1]!)) end--;
+  const lineStart = text.lastIndexOf('\n', end - 1) + 1;
+  const cue = text.slice(lineStart, end).toLowerCase();
+  return cue.includes('example') || cue.includes('e.g.') || cue.includes('schema');
+}
+
+function hasPayloadCueBefore(text: string, index: number): boolean {
+  let end = index;
+  while (end > 0 && /\s/.test(text[end - 1]!)) end--;
+  const lineStart = text.lastIndexOf('\n', end - 1) + 1;
+  const cue = text.slice(lineStart, end).trim().toLowerCase();
+  return /^(actual|result|final|answer)(?:\s+(json|answer|response|payload))?[:\-]?$/.test(cue);
+}
+/**
+ * Extract and parse JSON from LLM output, handling:
+ * - Markdown code blocks (```json ... ```)
+ * - Leading/trailing prose around JSON
+ * - Truncated JSON from token limits (repairs arrays/objects)
+ */
+export function extractJsonFromLLM(raw: string): any | null {
+  const text = raw.trim();
+  if (!text) return null;
+
+  const fences = collectStructuralFences(text);
+  const jsonFences = fences.filter((fence) => fence.isJson);
+  const anyFenceRanges = collectAnyFenceRanges(text);
+  const outsideJsonStart = findFirstJsonStartOutsideFences(text, anyFenceRanges);
+  const outsideLooksLikeExample = outsideJsonStart !== -1 && hasExampleCueBefore(text, outsideJsonStart);
+  const outsideLooksLikePayload = outsideJsonStart !== -1 && hasPayloadCueBefore(text, outsideJsonStart);
+  const preferredJsonFences = jsonFences.filter((fence) =>
+    !hasExampleCueBefore(text, fence.start) &&
+    !(text.startsWith('```') && fence.start === fences[0]?.start && outsideLooksLikePayload)
+  );
+  const preferredUntaggedFences = fences.filter((fence) => !fence.isJson && !hasExampleCueBefore(text, fence.start));
+  const firstPreferredJsonFence = preferredJsonFences[0] ?? null;
+  const firstPreferredUntaggedFence = preferredUntaggedFences[0] ?? null;
+  const untaggedFenceLooksLikeExample = firstPreferredUntaggedFence ? hasExampleCueBefore(text, firstPreferredUntaggedFence.start) : false;
+  const outsidePrecedesPreferredJsonFence = !!firstPreferredJsonFence && outsideJsonStart < firstPreferredJsonFence.start;
+  const tryOutsideBeforeJsonFences = outsideJsonStart !== -1 &&
+    !outsideLooksLikeExample &&
+    (!outsidePrecedesPreferredJsonFence || outsideLooksLikePayload);
+
+  if (text.startsWith('```') && fences[0]?.start === 0 && !outsideLooksLikePayload && (fences[0]!.isJson || preferredJsonFences.length === 0)) {
+    const parsedLeadingFence = parseJsonCandidate(fences[0]!.body);
+    if (parsedLeadingFence !== null) return parsedLeadingFence;
+  }
+
+  const tryOutsideFences = () => {
+    const withoutFences = stripAnyFences(text);
+    if (!withoutFences || withoutFences === text) return null;
+    return parseJsonCandidate(withoutFences);
+  };
+
+  if (!text.startsWith('```') && !firstPreferredJsonFence && firstPreferredUntaggedFence && outsideLooksLikeExample && !untaggedFenceLooksLikeExample) {
+    const parsedUntaggedFence = parseJsonCandidate(firstPreferredUntaggedFence.body);
+    if (parsedUntaggedFence !== null) return parsedUntaggedFence;
+  }
+
+  if (tryOutsideBeforeJsonFences) {
+    const parsedOutsideFences = tryOutsideFences();
+    if (parsedOutsideFences !== null) return parsedOutsideFences;
+  }
+
+  for (const fence of preferredJsonFences) {
+    const parsedJsonFence = parseJsonCandidate(fence.body);
+    if (parsedJsonFence !== null) return parsedJsonFence;
+  }
+
+  if (!tryOutsideBeforeJsonFences) {
+    const parsedOutsideFences = tryOutsideFences();
+    if (parsedOutsideFences !== null) return parsedOutsideFences;
+  }
+
+  if (fences.length === 0) {
+    const parsedRaw = parseJsonCandidate(text);
+    if (parsedRaw !== null) return parsedRaw;
+  }
+
+  const fallbackFences = preferredJsonFences.length === 0
+    ? [
+        ...preferredUntaggedFences,
+        ...jsonFences.filter((fence) => hasExampleCueBefore(text, fence.start)),
+        ...(text.startsWith('```')
+          ? fences.slice(1).filter((fence) => !fence.isJson && hasExampleCueBefore(text, fence.start))
+          : fences.filter((fence) => !fence.isJson && hasExampleCueBefore(text, fence.start))),
+      ]
+    : [
+        ...jsonFences.filter((fence) => hasExampleCueBefore(text, fence.start)),
+        ...(text.startsWith('```')
+          ? fences.slice(1).filter((fence) => !fence.isJson)
+          : fences.filter((fence) => !fence.isJson)),
+      ];
+  for (const fence of fallbackFences) {
+    const parsedFence = parseJsonCandidate(fence.body);
+    if (parsedFence !== null) return parsedFence;
+  }
+
+  return null;
+}
+
 /**
  * Construct a memory note for a document using LLM analysis.
  * Extracts keywords, tags, and context summary.
@@ -142,9 +530,11 @@ Return ONLY valid JSON in this exact format:
       return EMPTY_NOTE;
     }
 
-    const parsed = extractJsonFromLLM(result.text) as MemoryNote | null;
+    const parsed = parseMemoryNoteFromLLM(result.text);
 
-    if (!parsed || !Array.isArray(parsed.keywords) || !Array.isArray(parsed.tags) || typeof parsed.context !== 'string') {
+    if (!parsed) {
+      console.log(`[amem] RAW memory note output for docId ${docId}:`);
+      console.log(result.text);
       console.log(`[amem] Invalid/unparseable JSON for docId ${docId}`);
       return EMPTY_NOTE;
     }
@@ -302,34 +692,32 @@ Include all ${neighbors.length} neighbors in your response.`;
       return 0;
     }
 
-    const parsed = extractJsonFromLLM(result.text) as Array<{
-      target_idx: number;
-      link_type: 'semantic' | 'supporting' | 'contradicts';
-      confidence: number;
-      reasoning: string;
-    }> | null;
+    const parsed = parseLinkGenerationFromLLM(result.text);
 
-    if (!Array.isArray(parsed)) {
+    if (!parsed) {
+      console.log(`[amem] RAW link generation output for docId ${docId}:`);
+      console.log(result.text);
       console.log(`[amem] Invalid/unparseable JSON for link generation docId ${docId}`);
       return 0;
     }
 
+
     // Insert links into memory_relations
     let linksCreated = 0;
     const now = new Date().toISOString();
+    const linkedTargetIndexes = new Set<number>();
 
     for (const link of parsed) {
-      // Validate link structure
-      if (typeof link.target_idx !== 'number' ||
-          link.target_idx < 1 ||
-          link.target_idx > neighbors.length ||
-          !['semantic', 'supporting', 'contradicts'].includes(link.link_type) ||
-          typeof link.confidence !== 'number') {
+      const neighbor = neighbors[link.target_idx - 1];
+      if (!neighbor) {
+        console.log(`[amem] Skipping out-of-range link target ${link.target_idx} for docId ${docId}`);
         continue;
       }
-
-      const neighbor = neighbors[link.target_idx - 1];
-      if (!neighbor) continue;
+      if (linkedTargetIndexes.has(link.target_idx)) {
+        console.log(`[amem] Skipping duplicate link target ${link.target_idx} for docId ${docId}`);
+        continue;
+      }
+      linkedTargetIndexes.add(link.target_idx);
 
       // Insert link with INSERT OR IGNORE for idempotency
       store.db.prepare(`

package/src/clawmem.ts

@@ -70,6 +70,10 @@ import {
   clearSessionFocus,
   focusFilePath,
 } from "./session-focus.ts";
+import {
+  resolveExtensionsDirNoOpenClaw,
+  printSetupOpenClawHelp,
+} from "./openclaw-paths.ts";
 
 enableProductionMode();
 
@@ -1324,13 +1328,26 @@ function readOpenClawConfigValue(key: string): string | undefined {
 }
 
 async function cmdSetupOpenClaw(args: string[]) {
+  // §28.2 — short-circuit on --help / -h before any spawn or filesystem work.
+  if (args.includes("--help") || args.includes("-h")) {
+    printSetupOpenClawHelp();
+    return;
+  }
+
   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");
+
+  // Resolve the extensions/clawmem path we would touch directly. Both Path 1
+  // link-mode pre-cleanup and Path 3 direct-copy install need this. Path 1
+  // copy-mode delegation does NOT use linkPath because OpenClaw's
+  // `--force` install owns the destination resolution there.
+  const extensionsDir = resolveExtensionsDirNoOpenClaw();
   const linkPath = pathResolve(extensionsDir, "clawmem");
 
-  // Check if openclaw CLI is available
+  // Probe whether the openclaw CLI is on PATH. Used to choose between
+  // delegation (Path 1) and direct-copy fallback (Path 3) for installs,
+  // and between CLI uninstall and manual cleanup for --remove.
   const hasOpenClawCli = (() => {
     try {
       const r = Bun.spawnSync(["openclaw", "--version"], { stdout: "pipe", stderr: "pipe" });
@@ -1339,27 +1356,65 @@ async function cmdSetupOpenClaw(args: string[]) {
   })();
 
   if (remove) {
-    // Actually uninstall — mirror of install behavior
+    // §28.1 H3 / R1 / R4: try-and-fall-back uninstall + constrained stale
+    // cleanup. CLI uninstall is preferred (handles managed config + slot
+    // resets); manual cleanup is the legacy fallback for unmanaged
+    // direct-cpSync installs from older ClawMem versions. On CLI failure we
+    // fall through AND emit a warning so the user knows config/install
+    // records may need manual repair.
+    let cliUninstallSucceeded = false;
+    let cliUninstallFailed = false;
+    if (hasOpenClawCli) {
+      const r = Bun.spawnSync(
+        ["openclaw", "plugins", "uninstall", "clawmem", "--force"],
+        { stdout: "inherit", stderr: "inherit" },
+      );
+      if (r.exitCode === 0) {
+        cliUninstallSucceeded = true;
+      } else {
+        cliUninstallFailed = true;
+        console.log(
+          `${c.yellow}Warning: openclaw plugins uninstall clawmem failed (exit ${r.exitCode}).${c.reset}`,
+        );
+        console.log(
+          `${c.yellow}  OpenClaw config and install records may still reference clawmem.${c.reset}`,
+        );
+        console.log(
+          `${c.yellow}  Falling back to manual cleanup of the install directory.${c.reset}`,
+        );
+      }
+    }
+
+    // Constrained stale cleanup (R3 in BACKLOG §28.1): even if CLI uninstall
+    // succeeded, an old unmanaged direct-copy directory at the same path
+    // could still be present (managed-link + unmanaged-copy side-by-side).
+    // Always check the exact extensions/clawmem path and remove if present.
     let removed = false;
     try {
-      const stat = await import("fs").then(m => m.lstatSync(linkPath));
-      if (stat.isSymbolicLink() || stat.isDirectory()) {
-        const { unlinkSync, rmSync } = await import("fs");
-        if (stat.isSymbolicLink()) {
-          unlinkSync(linkPath);
-        } else {
-          rmSync(linkPath, { recursive: true });
-        }
-        console.log(`${c.green}Removed plugin from ${linkPath}${c.reset}`);
+      const { lstatSync, unlinkSync, rmSync } = await import("fs");
+      const stat = lstatSync(linkPath);
+      if (stat.isSymbolicLink()) {
+        unlinkSync(linkPath);
+        console.log(`${c.green}Removed plugin symlink at ${linkPath}${c.reset}`);
+        removed = true;
+      } else if (stat.isDirectory()) {
+        rmSync(linkPath, { recursive: true });
+        console.log(`${c.green}Removed plugin directory at ${linkPath}${c.reset}`);
         removed = true;
       }
     } catch (e: any) {
       if (e.code !== "ENOENT") throw e;
-      console.log(`${c.dim}Plugin not installed at ${linkPath}${c.reset}`);
+      if (!cliUninstallSucceeded && !cliUninstallFailed) {
+        // Truly nothing to do — no CLI, no directory.
+        console.log(`${c.dim}Plugin not installed at ${linkPath}${c.reset}`);
+      }
     }
 
+    // Slot reset: only meaningful if the CLI is reachable. CLI uninstall
+    // already clears the memory slot if it succeeded, but if uninstall
+    // failed we still attempt slot reset because config slots can be
+    // populated separately from install records.
     if (hasOpenClawCli) {
-      // 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" });
@@ -1378,7 +1433,8 @@ async function cmdSetupOpenClaw(args: string[]) {
     return;
   }
 
-  // Verify plugin source files exist
+  // Verify plugin source files exist (cheap defense-in-depth — surfaces
+  // ClawMem packaging bugs immediately, before any spawn).
   if (!existsSync(pathResolve(pluginDir, "index.ts"))) {
     die(`OpenClaw plugin files not found at ${pluginDir}`);
   }
@@ -1389,44 +1445,103 @@ async function cmdSetupOpenClaw(args: string[]) {
     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 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()) {
-      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}`);
+  // §28.1 H1/H2: choose path. Path 1 = openclaw plugins install delegation;
+  // Path 3 = direct-copy fallback honoring OPENCLAW_STATE_DIR.
+  let delegated = false;
+  if (hasOpenClawCli) {
+    // Path 1: delegate to OpenClaw. Auto-enables, writes install records,
+    // applies slot selection, refreshes registry.
+    if (linkMode) {
+      // §28.1 H2 link-mode: OpenClaw rejects --force with --link, so we do
+      // manual stale cleanup before delegating to preserve idempotence.
+      try {
+        const { lstatSync, unlinkSync, rmSync } = await import("fs");
+        const stat = lstatSync(linkPath);
+        if (stat.isSymbolicLink()) {
+          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}`);
+        }
+      } catch (e: any) {
+        if (e.code !== "ENOENT") throw e;
+      }
+      const r = Bun.spawnSync(
+        ["openclaw", "plugins", "install", pluginDir, "-l"],
+        { stdout: "inherit", stderr: "inherit" },
+      );
+      if (r.exitCode !== 0) {
+        die(`openclaw plugins install -l failed (exit ${r.exitCode}); aborting setup`);
+      }
+      // OpenClaw's `plugins install -l` records the source path in
+      // plugins.load.paths and persists a path install record (not a
+      // filesystem symlink). The v2026.4.11 symlink-discovery skip does
+      // NOT apply to this mode — discovery uses the load-path entry.
+      console.log(`${c.green}Linked local plugin path via openclaw plugins install -l (profile-aware, auto-enabled)${c.reset}`);
+      console.log(`${c.dim}  Source recorded in plugins.load.paths — edits to ${pluginDir} take effect on next gateway restart.${c.reset}`);
     } else {
-      die(`${linkPath} exists but is not a symlink or directory. Remove it manually and re-run setup.`);
+      // §28.1 H2 copy-mode: --force makes OpenClaw replace existing target,
+      // preserving idempotence across reruns.
+      const r = Bun.spawnSync(
+        ["openclaw", "plugins", "install", pluginDir, "--force"],
+        { stdout: "inherit", stderr: "inherit" },
+      );
+      if (r.exitCode !== 0) {
+        die(`openclaw plugins install --force failed (exit ${r.exitCode}); aborting setup`);
+      }
+      console.log(`${c.green}Installed plugin via openclaw plugins install --force (profile-aware, auto-enabled)${c.reset}`);
     }
-  } catch (e: any) {
-    if (e.code !== "ENOENT") throw e;
-  }
-
-  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}`);
+    delegated = true;
   } 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}`);
+    // Path 3: direct-copy fallback. Honors OPENCLAW_STATE_DIR via the
+    // resolveExtensionsDirNoOpenClaw helper. Profile awareness is limited
+    // to env vars (no manifest validation, no security scan, no install
+    // records) — surface that to the user.
+    console.log(`${c.yellow}openclaw CLI not on PATH — using direct-copy install.${c.reset}`);
+    console.log(`${c.yellow}  Profile awareness limited to OPENCLAW_STATE_DIR / OPENCLAW_CONFIG_PATH${c.reset}`);
+    console.log(`${c.yellow}  env vars. Install OpenClaw to enable manifest validation, security${c.reset}`);
+    console.log(`${c.yellow}  scans, and full plugin lifecycle management.${c.reset}`);
+
+    // Create extensions directory.
+    if (!existsSync(extensionsDir)) {
+      mkdirSync(extensionsDir, { recursive: true });
+    }
+
+    // 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()) {
+        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 {
+        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;
+    }
+
+    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 -----
@@ -1472,30 +1587,45 @@ 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. 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.
+  // §28.1 H1: dual next-steps output. Path 1 (delegated) auto-enables via
+  // persistPluginInstall, so the legacy "Step 1: enable" instruction is
+  // redundant and would mislead users. Path 3 (direct copy) writes only
+  // the plugin files; the user must still run `openclaw plugins enable`
+  // themselves, so the original 4-step output is preserved verbatim.
   console.log();
   console.log(`${c.bold}Next steps:${c.reset}`);
   console.log();
-  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. 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}`);
-  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):`);
-  console.log(`     ${c.cyan}clawmem serve &${c.reset}`);
+  if (delegated) {
+    // Path 1 — plugin already enabled and registered by openclaw plugins install.
+    console.log(`  1. Restart the gateway to apply:`);
+    console.log(`     ${c.cyan}openclaw gateway restart${c.reset}`);
+    console.log();
+    console.log(`  2. 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(`  3. Start the REST API (for agent tools):`);
+    console.log(`     ${c.cyan}clawmem serve &${c.reset}`);
+  } else {
+    // Path 3 — direct-copy install. User still needs to enable + restart.
+    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. 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}`);
+    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):`);
+    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`);
@@ -2844,7 +2974,7 @@ ${c.bold}Setup:${c.reset}
   clawmem collection remove <name>
   clawmem setup hooks [--remove]       Install/remove Claude Code hooks
   clawmem setup mcp [--remove]         Register/remove MCP in ~/.claude.json
-  clawmem setup openclaw [--remove]    Show OpenClaw plugin installation steps
+  clawmem setup openclaw [--link] [--remove]   Install/remove ClawMem as OpenClaw memory plugin
   clawmem install-service [--enable]   Install systemd watcher service
 
 ${c.bold}Indexing:${c.reset}

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:2470-2496`. Precompact-extract MUST run inside
- * `handleBeforePromptBuild` (which IS awaited at `attempt.ts:1873`), gated
+ * `attempt.ts:3379-3402`. Precompact-extract MUST run inside
+ * `handleBeforePromptBuild` (which IS awaited at `attempt.ts:2610`), gated
  * by the proximity heuristic in `compaction-threshold.ts`. See `engine.ts`
  * top-of-file comment for the full rationale.
  */
@@ -161,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:1873 before building the
+    // attempt path awaits the result at attempt.ts:2610 before building the
     // effective prompt. precompact-extract therefore runs strictly before
     // the LLM call that could trigger compaction on this turn.
     api.on(
@@ -175,7 +175,11 @@ 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:2470-2496 is acceptable.
+    // fire-and-forget context at attempt.ts:3379-3402 is acceptable.
+    // OpenClaw v2026.4.26+ also enforces a 30s default void-hook timeout
+    // (DEFAULT_VOID_HOOK_TIMEOUT_MS_BY_HOOK in src/plugins/hooks.ts) — a
+    // timed-out handler is logged but our underlying postrun work is not
+    // cancelled, so eventual consistency is preserved.
     // 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/shell.ts

@@ -7,7 +7,15 @@
 
 import { execFile, spawn, type ChildProcess } from "node:child_process";
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ESM equivalent of CommonJS __dirname. This package declares
+// "type": "module", so __dirname is not defined when loaded by a plain
+// Node.js ESM loader (e.g. OpenClaw's plugin host). Bun shims __dirname
+// in ESM, which is why this regression is invisible under `bun test`.
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 
 // =============================================================================
 // Types

package/src/openclaw-paths.ts

@@ -0,0 +1,244 @@
+/**
+ * OpenClaw path-resolution helpers + setup help text for `clawmem setup openclaw`.
+ *
+ * §28.1 (issue #11): historically `cmdSetupOpenClaw` hardcoded
+ * `~/.openclaw/extensions/clawmem` and ignored `OPENCLAW_STATE_DIR`. v0.10.4
+ * delegates to `openclaw plugins install` when the CLI is on PATH (which
+ * inherits OpenClaw's own `resolveConfigDir(env)` semantics) and falls back
+ * to a direct-copy install otherwise. The fallback path needs to mirror
+ * OpenClaw's `resolveConfigDir` precisely for env-var-honoring custom
+ * profile installs to land in the expected directory.
+ *
+ * Mirrors: openclaw/src/utils.ts:119 (resolveConfigDir) and
+ *          openclaw/src/infra/home-dir.ts (home resolution).
+ *
+ * Helpers take injected `env` + `homedir` so they are testable in isolation
+ * without needing to touch process.env or the real os.homedir.
+ */
+
+import { homedir as defaultHomedir } from "node:os";
+import { dirname, resolve as pathResolve } from "node:path";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type EnvLike = Record<string, string | undefined>;
+export type HomedirFn = () => string;
+
+export interface PathResolverOpts {
+  env?: EnvLike;
+  homedir?: HomedirFn;
+}
+
+// =============================================================================
+// Trim / normalize
+// =============================================================================
+
+/**
+ * Plain trim — used for OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH so the
+ * fallback resolver mirrors OpenClaw's `resolveConfigDir` (utils.ts:119)
+ * EXACTLY. OpenClaw applies only `.trim()` to those env vars, so a value
+ * of `"undefined"` or `"null"` is treated as a literal directory name (the
+ * user shot themselves in the foot, but ClawMem must agree with OpenClaw
+ * about WHERE the foot is shot — diverging here would mean Path 1 and
+ * Path 3 install into different locations for the same env, which is
+ * exactly the bug class §28.1 set out to fix).
+ */
+export function plainTrim(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const t = value.trim();
+  return t || undefined;
+}
+
+/**
+ * Mirrors OpenClaw's `home-dir.ts:normalize`. Treats empty strings,
+ * whitespace-only strings, and the literal strings "undefined" / "null" as
+ * unset. Used ONLY for home-resolution env vars (OPENCLAW_HOME, HOME,
+ * USERPROFILE) to match OpenClaw's home-dir helper; do NOT use this for
+ * OPENCLAW_STATE_DIR or OPENCLAW_CONFIG_PATH (see plainTrim).
+ */
+export function trim(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const t = value.trim();
+  if (!t || t === "undefined" || t === "null") return undefined;
+  return t;
+}
+
+// =============================================================================
+// Home resolution
+// =============================================================================
+
+/**
+ * Mirrors `openclaw/src/infra/home-dir.ts` resolution priority:
+ *   OPENCLAW_HOME → HOME → USERPROFILE → os.homedir() → path.resolve(cwd())
+ *
+ * `OPENCLAW_HOME` itself can begin with a tilde, in which case we expand it
+ * against the *next* fallback (HOME / USERPROFILE / os.homedir).
+ */
+export function resolveHomeForOpenClaw(opts: PathResolverOpts = {}): string {
+  const env = opts.env ?? process.env;
+  const homedir = opts.homedir ?? defaultHomedir;
+
+  const explicitHome = trim(env.OPENCLAW_HOME);
+  if (explicitHome) {
+    if (
+      explicitHome === "~" ||
+      explicitHome.startsWith("~/") ||
+      explicitHome.startsWith("~\\")
+    ) {
+      const fallback = resolveOsHome(env, homedir);
+      if (fallback) {
+        return pathResolve(explicitHome.replace(/^~(?=$|[\\/])/, fallback));
+      }
+      // No fallback available; fall through to other priorities below.
+    } else {
+      return pathResolve(explicitHome);
+    }
+  }
+
+  const osHome = resolveOsHome(env, homedir);
+  if (osHome) return pathResolve(osHome);
+
+  // Last-resort: cwd. Matches `resolveRequiredHomeDir` in OpenClaw.
+  return pathResolve(process.cwd());
+}
+
+function resolveOsHome(env: EnvLike, homedir: HomedirFn): string | undefined {
+  const homeEnv = trim(env.HOME);
+  if (homeEnv) return homeEnv;
+  const userProfile = trim(env.USERPROFILE);
+  if (userProfile) return userProfile;
+  try {
+    const safe = trim(homedir());
+    if (safe) return safe;
+  } catch {
+    // os.homedir() can throw on misconfigured systems
+  }
+  return undefined;
+}
+
+// =============================================================================
+// Tilde expansion
+// =============================================================================
+
+/**
+ * Expands a leading `~`, `~/`, or `~\` against the OpenClaw home resolver.
+ * Does NOT support `~user/...` (other-user expansion) — neither does
+ * OpenClaw's `expandHomePrefix`.
+ */
+export function expandHome(input: string, opts: PathResolverOpts = {}): string {
+  if (!input.startsWith("~")) return input;
+  if (
+    input !== "~" &&
+    !input.startsWith("~/") &&
+    !input.startsWith("~\\")
+  ) {
+    // Looks like `~user` or some other non-home tilde form; leave untouched.
+    return input;
+  }
+  const home = resolveHomeForOpenClaw(opts);
+  return input.replace(/^~(?=$|[\\/])/, home);
+}
+
+// =============================================================================
+// Extensions directory resolver (CLI-absent fallback)
+// =============================================================================
+
+/**
+ * Resolves the `extensions/` directory we should write into when `openclaw`
+ * CLI is not on PATH. Mirrors `openclaw/src/utils.ts:119 resolveConfigDir`:
+ *   1. OPENCLAW_STATE_DIR overrides everything
+ *   2. OPENCLAW_CONFIG_PATH → config root = dirname(file)
+ *   3. <home>/.openclaw
+ *
+ * The result is `pathResolve`d so callers can compare against equally
+ * normalized paths.
+ */
+export function resolveExtensionsDirNoOpenClaw(
+  opts: PathResolverOpts = {},
+): string {
+  const env = opts.env ?? process.env;
+
+  // OPENCLAW_STATE_DIR + OPENCLAW_CONFIG_PATH use plainTrim (no
+  // "undefined"/"null" filtering) to match OpenClaw's resolveConfigDir
+  // exactly. See plainTrim docstring.
+  const stateDir = plainTrim(env.OPENCLAW_STATE_DIR);
+  if (stateDir) {
+    return pathResolve(expandHome(stateDir, opts), "extensions");
+  }
+
+  const configPath = plainTrim(env.OPENCLAW_CONFIG_PATH);
+  if (configPath) {
+    return pathResolve(dirname(expandHome(configPath, opts)), "extensions");
+  }
+
+  return pathResolve(resolveHomeForOpenClaw(opts), ".openclaw", "extensions");
+}
+
+// =============================================================================
+// `clawmem setup openclaw --help` text
+// =============================================================================
+
+/**
+ * Prints help for `clawmem setup openclaw`. Documents flags, env vars
+ * consulted, and the CLI-delegation behavior introduced in v0.10.4 (§28.1).
+ */
+export function printSetupOpenClawHelp(): void {
+  const lines = [
+    "",
+    "clawmem setup openclaw [--link] [--remove] [--help|-h]",
+    "",
+    "  Install ClawMem as an OpenClaw memory plugin.",
+    "",
+    "  When the openclaw CLI is on PATH, this command delegates to",
+    "  `openclaw plugins install <pluginDir>`, which auto-enables the plugin,",
+    "  writes install records, and applies slot selection. Otherwise it falls",
+    "  back to a direct-copy install honoring OPENCLAW_STATE_DIR.",
+    "",
+    "Flags:",
+    "  --link        Install in load-path mode instead of copying files.",
+    "                When openclaw is on PATH, delegates to `openclaw plugins",
+    "                install -l <path>` which records the source in",
+    "                plugins.load.paths (NOT a filesystem symlink). When",
+    "                openclaw is absent, falls back to a real symlink at",
+    "                <extensions>/clawmem (note: OpenClaw v2026.4.11+",
+    "                discovery silently skips symlinked plugins in the",
+    "                fallback path, so prefer the delegated path).",
+    "  --remove      Uninstall ClawMem from the OpenClaw extensions dir.",
+    "                Tries `openclaw plugins uninstall clawmem --force` first;",
+    "                falls back to manual cleanup at the resolved extensions",
+    "                path for legacy unmanaged installs.",
+    "  --help, -h    Print this message and exit.",
+    "",
+    "Environment variables (consulted by the CLI-absent fallback path and",
+    "inherited by the openclaw subprocess in the delegation path):",
+    "  OPENCLAW_STATE_DIR      Override the OpenClaw config root. Plugin",
+    "                          installs into <OPENCLAW_STATE_DIR>/extensions/",
+    "                          clawmem.",
+    "  OPENCLAW_CONFIG_PATH    Override the OpenClaw config file path; root",
+    "                          becomes dirname(OPENCLAW_CONFIG_PATH).",
+    "  OPENCLAW_HOME           Override the home directory used to resolve",
+    "                          the default ~/.openclaw root.",
+    "  HOME / USERPROFILE      Standard home-dir env vars; consulted in that",
+    "                          order when OPENCLAW_HOME is unset.",
+    "",
+    "Examples:",
+    "  clawmem setup openclaw",
+    "      Install with default profile.",
+    "",
+    "  OPENCLAW_STATE_DIR=~/.openclaw-dev clawmem setup openclaw",
+    "      Install into the `dev` profile (~/.openclaw-dev/extensions/clawmem).",
+    "",
+    "  clawmem setup openclaw --link",
+    "      Load-path mode (delegated install) or symlink (fallback) — local",
+    "      development workflow where edits to the source dir take effect.",
+    "",
+    "  clawmem setup openclaw --remove",
+    "      Uninstall ClawMem and reset OpenClaw memory slot.",
+    "",
+  ];
+  for (const line of lines) {
+    console.log(line);
+  }
+}