clawmem 0.10.3 → 0.10.4

package/AGENTS.md

@@ -742,6 +742,7 @@ 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, 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

@@ -742,6 +742,7 @@ 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, 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,7 +188,13 @@ 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:**
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.10.3",
+  "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/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/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);
+  }
+}