mr-memory 3.13.2 → 3.14.0

package/README.md

@@ -9,10 +9,14 @@ Use it when you want OpenClaw memory that does not restart from zero every sessi
 ## Install
 
 ```bash
-openclaw plugins install npm:mr-memory@3.13.2
+openclaw plugins install --force --accept-capabilities npm:mr-memory
 ```
 
-The explicit `npm:` source and version make the audited install deterministic. `mr-memory@3.13.2` is published on npm. A ClawHub listing has not been verified and is not required for this path.
+For OpenClaw 2026.9.x and later, use a supported Node version (24.16+ on Node 24 LTS, or 26.1+ on Node 26; Node 25 is not supported). The flags explicitly approve the npm trust and capability prompts.
+
+The explicit `npm:` source installs the latest published `mr-memory` release from npm. A ClawHub listing has not been verified and is not required for this path.
+
+OpenClaw prints `OpenClaw can't verify where this plugin came from ... reason=provenance-invalid` for every plugin that is not an official OpenClaw package. That line is informational: the plugin is installed and loads.
 
 ## Setup
 
@@ -24,6 +28,7 @@ openclaw mr upload               # Upload workspace + session history
 ## Commands
 
 ```bash
+openclaw mr doctor           # Repair plugin registration + native memory-search settings
 openclaw mr status           # Vault stats
 openclaw mr upload           # Upload workspace + sessions
 openclaw mr upload --brain ~/.notopenclaw   # Upload from a different agent
@@ -35,6 +40,16 @@ openclaw mr medium           # Up to 43 memories (25 + 12 + 6), balanced default
 openclaw mr high             # Up to 87 memories (50 + 25 + 12)
 ```
 
+Loading the plugin never writes your OpenClaw config. Setup (`openclaw mr <key>`) and `openclaw mr doctor` explicitly repair its enabled entry and allowlist membership, disable native memory search when a memory key is configured, and on OpenClaw 2026.10+ grant `plugins.entries.mr-memory.hooks.allowConversationAccess` (without that grant OpenClaw silently drops the `before_prompt_build`, `llm_input` and `agent_end` hooks of every non-bundled plugin, so no memory would be injected or captured). Existing users who see a config-repair hint should run `openclaw mr doctor`, then restart their gateway. On current OpenClaw this uses the host’s locked config mutation API and `memory.search.enabled`; older OpenClaw and John’s Harness use `agents.defaults.memorySearch.enabled`. Repairs never restart the gateway automatically. Native memory flush is left untouched.
+
+The plugin declares no OpenClaw version floor on purpose. OpenClaw evaluates `openclaw.compat.pluginApi` and `openclaw.install.minHostVersion` against its own version string, and when that string is not semver (for example `OPENCLAW_VERSION=latest` exported in the shell, as the official installer documents) a declared floor makes OpenClaw skip the plugin and the install fails with `package owner "mr-memory" has no authoritative runtime child list`. mr-memory detects host capabilities at runtime instead.
+
+On OpenClaw 2026.10 and later, non-bundled plugins only receive conversation hooks (`before_prompt_build`, `llm_input`, `agent_end`) when `plugins.entries.mr-memory.hooks.allowConversationAccess` is `true`. Setup and `doctor` grant it on those hosts; without it the plugin loads but never injects or captures memory. Run `openclaw plugins doctor` to confirm no hooks are blocked. The `provenance-invalid` warning from `openclaw plugins doctor` is informational: it applies to every npm plugin that is not in OpenClaw’s official catalog.
+
+### Compatibility (3.14.0)
+
+`mr-memory` no longer declares a host version floor (`openclaw.compat.pluginApi` / `install.minHostVersion`). OpenClaw 2026.10 reads the host version from `OPENCLAW_VERSION` when it is exported, and the official install instructions export `OPENCLAW_VERSION=latest`; a non-semver string made the host skip the plugin and fail the install with `no authoritative runtime child list`. The plugin detects host capabilities at runtime instead. The manifest now declares its six tools under `contracts.tools` (2026.10 rejects undeclared tool registrations) and asks for gateway startup activation.
+
 ## Memory Density
 
 The current density choices are `low`, `medium`, and `high`. New installs and configs without an explicit density use `medium`, the balanced default. Existing explicit `low` or `high` settings are unchanged. Legacy `xhigh` configs remain valid so upgrades do not break the gateway, but the plugin normalizes `xhigh` to `high` and no longer advertises it as a current option.
@@ -111,19 +126,24 @@ After `openclaw mr <key>`, config is stored at:
 ```json
 {
   "plugins": {
+    "allow": ["mr-memory"],
     "entries": {
-      "memoryrouter": {
+      "mr-memory": {
         "enabled": true,
+        "hooks": { "allowConversationAccess": true },
         "config": {
           "key": "mk_xxx",
           "endpoint": "https://api.memoryrouter.ai"
         }
       }
     }
-  }
+  },
+  "memory": { "search": { "enabled": false } }
 }
 ```
 
+`plugins.allow` is only extended when it already exists, and the `hooks` grant is only written on OpenClaw builds whose schema accepts it.
+
 ## Cross-AI and MCP Memory
 
 The OpenClaw plugin uses relay hooks. Separately, the same MemoryRouter vault can connect to supported ChatGPT, Claude, Claude Code, Codex, and compatible MCP clients. Each host follows its own integration contract. Hosted ChatGPT and Claude connectors are model-directed, do not passively capture every conversation, and do not import old conversations just by connecting.

package/index.js

@@ -312,7 +312,33 @@ function normalizeMemoryDensity(value) {
 function openClawConfigPath() {
     return process.env.OPENCLAW_CONFIG_PATH || process.env.OPENCLAW_CONFIG || join(os.homedir(), ".openclaw", "openclaw.json");
 }
-async function readOpenClawConfigFile() {
+function hostConfigApi(api) {
+    return api.runtime?.config;
+}
+// OpenClaw's current()/mutateConfigFile API accompanies the canonical memory
+// owner schema (memory.search). Older OpenClaw and John's Harness retain
+// agents.defaults.memorySearch. Do not use the host version: forks version
+// independently of their upstream config schema.
+function usesCanonicalMemorySearch(api) {
+    return typeof hostConfigApi(api)?.current === "function";
+}
+function nativeMemorySearchDisabled(api) {
+    const config = api.config;
+    // Metadata-only registration may deliberately throw on api.runtime access.
+    // Read the provided config only; runtime capability detection belongs in CLI actions.
+    return config?.memory?.search?.enabled === false
+        || config?.agents?.defaults?.memorySearch?.enabled === false;
+}
+// Only explicit CLI actions call these helpers. Loading/registering the plugin
+// must never mutate the host config (including fire-and-forget writes).
+async function readOpenClawConfigFile(api) {
+    const runtimeConfig = hostConfigApi(api);
+    if (typeof runtimeConfig?.current === "function") {
+        return structuredClone(runtimeConfig.current());
+    }
+    if (typeof runtimeConfig?.loadConfig === "function") {
+        return structuredClone(runtimeConfig.loadConfig());
+    }
     try {
         return JSON.parse(await readFile(openClawConfigPath(), "utf8"));
     }
@@ -322,7 +348,13 @@ async function readOpenClawConfigFile() {
         throw err;
     }
 }
-async function writeOpenClawConfigFile(config) {
+async function writeOpenClawConfigFile(api, config) {
+    const runtimeConfig = hostConfigApi(api);
+    if (typeof runtimeConfig?.writeConfigFile === "function") {
+        await runtimeConfig.writeConfigFile(config);
+        return;
+    }
+    // Legacy hosts only: no native config writer is exposed.
     const configPath = openClawConfigPath();
     await mkdir(dirname(configPath), { recursive: true });
     try {
@@ -335,51 +367,74 @@ async function writeOpenClawConfigFile(config) {
     await writeFile(configPath, `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
+async function mutateOpenClawConfigFile(api, mutate) {
+    const runtimeConfig = hostConfigApi(api);
+    if (typeof runtimeConfig?.mutateConfigFile === "function") {
+        // The host rewrites the file on every mutation call, even a no-op one.
+        // Probe a snapshot first so repeated `mr doctor` runs stay write-free.
+        if (typeof runtimeConfig.current === "function") {
+            const probe = structuredClone(runtimeConfig.current());
+            if (!mutate(probe))
+                return false;
+        }
+        // Let the host acquire its lock and supply the latest authored config.
+        // Never auto-restart a gateway as a side effect of a plugin CLI command.
+        const result = await runtimeConfig.mutateConfigFile({
+            base: "source",
+            afterWrite: { mode: "none", reason: "MemoryRouter explicit CLI configuration; restart manually to apply" },
+            mutate,
+        });
+        return result.result === true;
+    }
+    const config = await readOpenClawConfigFile(api);
+    if (!mutate(config))
+        return false;
+    await writeOpenClawConfigFile(api, config);
+    return true;
+}
 // ──────────────────────────────────────────────────────
 // Full-replace: disable OpenClaw's native memory search so MemoryRouter
 // owns the memory_search tool (no name conflict, no native embeddings 429).
 // memoryFlush (durable MEMORY.md writes) is intentionally left untouched.
-// Global + subagents: writes agents.defaults.memorySearch.enabled.
-// ──────────────────────────────────────────────────────
-async function setNativeMemorySearchEnabled(enabled) {
-    const config = await readOpenClawConfigFile();
-    config.agents ??= {};
-    config.agents.defaults ??= {};
-    config.agents.defaults.memorySearch ??= {};
-    if (config.agents.defaults.memorySearch.enabled === enabled)
-        return false; // no-op
-    config.agents.defaults.memorySearch.enabled = enabled;
-    await writeOpenClawConfigFile(config);
-    return true;
+// Global defaults cover subagents unless the user explicitly overrides them.
+async function setNativeMemorySearchEnabled(api, enabled) {
+    return mutateOpenClawConfigFile(api, (config) => {
+        let search;
+        if (usesCanonicalMemorySearch(api)) {
+            config.memory ??= {};
+            config.memory.search ??= {};
+            search = config.memory.search;
+        }
+        else {
+            config.agents ??= {};
+            config.agents.defaults ??= {};
+            config.agents.defaults.memorySearch ??= {};
+            search = config.agents.defaults.memorySearch;
+        }
+        if (search.enabled === enabled)
+            return false;
+        search.enabled = enabled;
+        return true;
+    });
 }
-// Boot-time self-heal: if a key is configured but native search is still on,
-// flip it off so already-installed users are fixed on restart after updating
-// (no need to re-run `openclaw mr <key>`).
+// Explicit setup/doctor repair only. With no key, leave native search available.
 async function selfHealNativeMemorySearch(api) {
-    try {
-        const config = await readOpenClawConfigFile();
-        const ms = config?.agents?.defaults?.memorySearch;
-        if (ms?.enabled === false)
-            return; // already disabled — nothing to do
-        const changed = await setNativeMemorySearchEnabled(false);
-        if (changed) {
-            api.logger.info?.("memoryrouter: disabled native memory search (full-replace). Restart gateway to apply.");
-        }
-    }
-    catch (err) {
-        api.logger.info?.(`memoryrouter: self-heal skipped — ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const changed = await setNativeMemorySearchEnabled(api, false);
+    if (changed)
+        console.log("  • Native memory search disabled — MemoryRouter now owns memory_search");
 }
-async function updateOpenClawPluginEntry(api, patch) {
-    const config = await readOpenClawConfigFile();
-    config.plugins ??= {};
-    config.plugins.entries ??= {};
-    config.plugins.entries[api.id] ??= {};
-    config.plugins.entries[api.id] = {
-        ...config.plugins.entries[api.id],
-        ...patch,
-    };
-    await writeOpenClawConfigFile(config);
+async function updateOpenClawPluginEntry(api, patch, mergeConfig = false) {
+    await mutateOpenClawConfigFile(api, (config) => {
+        config.plugins ??= {};
+        config.plugins.entries ??= {};
+        config.plugins.entries[api.id] ??= { enabled: true };
+        const entry = config.plugins.entries[api.id];
+        if (patch.config)
+            entry.config = mergeConfig ? { ...(entry.config || {}), ...patch.config } : patch.config;
+        if (typeof patch.enabled === "boolean")
+            entry.enabled = patch.enabled;
+        return true;
+    });
 }
 async function setPluginConfig(api, config) {
     const compat = api;
@@ -398,45 +453,65 @@ async function setPluginEnabled(api, enabled) {
     await updateOpenClawPluginEntry(api, { enabled });
 }
 async function mergePluginConfig(api, patch) {
-    const current = await readOpenClawConfigFile();
+    if (typeof api.updatePluginConfig !== "function") {
+        // Merge the focused patch inside the host's transaction, not into a stale
+        // runtime snapshot which could overwrite another command's latest changes.
+        await updateOpenClawPluginEntry(api, { config: patch }, true);
+        return;
+    }
+    const current = await readOpenClawConfigFile(api);
     const existing = current.plugins?.entries?.[api.id]?.config;
     await setPluginConfig(api, {
         ...(existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {}),
         ...patch,
     });
 }
-// Keep mr-memory as a first-class plugin config entry without clobbering user settings.
-// OpenClaw doctor validates plugin entries against discoverable manifests, so the entry
-// must be present, enabled, and allowlisted when an allowlist exists.
+// OpenClaw 2026.10+ drops every conversation hook (before_prompt_build,
+// llm_input, agent_end) from a non-bundled plugin unless the user grants
+// plugins.entries.<id>.hooks.allowConversationAccess. Without it mr-memory
+// loads but never injects or captures a single memory. The grant is only
+// written by the explicit CLI actions, on hosts whose schema accepts it
+// (the same hosts that expose current()/mutateConfigFile). Older hosts and
+// John's Harness reject unknown keys under hooks, so they are left alone.
+function hostGatesConversationHooks(api) {
+    return usesCanonicalMemorySearch(api);
+}
+function conversationAccessGranted(config, pluginId) {
+    return config?.plugins?.entries?.[pluginId]?.hooks?.allowConversationAccess === true;
+}
+async function ensureConversationHookAccess(api) {
+    if (!hostGatesConversationHooks(api))
+        return false;
+    return mutateOpenClawConfigFile(api, (config) => {
+        config.plugins ??= {};
+        config.plugins.entries ??= {};
+        config.plugins.entries[api.id] ??= { enabled: true };
+        const entry = config.plugins.entries[api.id];
+        if (entry.hooks?.allowConversationAccess === true)
+            return false;
+        entry.hooks = { ...(entry.hooks && typeof entry.hooks === "object" ? entry.hooks : {}), allowConversationAccess: true };
+        return true;
+    });
+}
+// Explicit setup/doctor repair; preserve all config, use native plugin APIs first.
+// Never call this from register(), a hook, or service.start().
 async function ensureDoctorSafePluginEntry(api) {
-    try {
-        const config = await readOpenClawConfigFile();
-        const plugins = config.plugins ?? {};
-        const entries = plugins.entries ?? {};
-        const existingEntry = entries[api.id] && typeof entries[api.id] === "object" && !Array.isArray(entries[api.id])
-            ? entries[api.id]
-            : {};
-        const nextPlugins = {
-            ...plugins,
-            entries: {
-                ...entries,
-                [api.id]: {
-                    ...existingEntry,
-                    enabled: true,
-                },
-            },
-        };
-        if (Array.isArray(plugins.allow) && !plugins.allow.includes(api.id)) {
-            nextPlugins.allow = [...plugins.allow, api.id];
-        }
-        const next = { ...config, plugins: nextPlugins };
-        if (JSON.stringify(next.plugins) === JSON.stringify(config.plugins))
-            return;
-        await writeOpenClawConfigFile(next);
-    }
-    catch (err) {
-        api.logger.info?.(`memoryrouter: doctor-safe registration skipped — ${err instanceof Error ? err.message : String(err)}`);
+    const config = await readOpenClawConfigFile(api);
+    if (config.plugins?.entries?.[api.id]?.enabled !== true) {
+        await setPluginEnabled(api, true);
     }
+    // Plugin-enable APIs do not necessarily maintain plugins.allow. Re-read after
+    // enabling so a host API's config update cannot be overwritten by a stale copy.
+    await mutateOpenClawConfigFile(api, (current) => {
+        const allow = current.plugins?.allow;
+        if (!Array.isArray(allow) || allow.includes(api.id))
+            return false;
+        current.plugins.allow = [...allow, api.id];
+        return true;
+    });
+    const granted = await ensureConversationHookAccess(api);
+    if (granted)
+        console.log("  • Conversation hook access granted — MemoryRouter can inject and capture memory");
 }
 /**
  * Read all workspace files and return as a single text blob for token counting.
@@ -608,11 +683,24 @@ const memoryRouterPlugin = {
             }, KEEP_WARM_PING_INTERVAL_MS);
             warmupTimer.unref?.();
         }
-        void (async () => {
-            await ensureDoctorSafePluginEntry(api);
-            if (hasAnyKey)
-                await selfHealNativeMemorySearch(api);
-        })();
+        // Host install/update/doctor may load plugins inside a guarded config
+        // transaction. Even an unawaited write here races its base-hash check.
+        // Configuration repair is owned exclusively by the explicit CLI actions.
+        // Hook gating is a runtime capability check; metadata-only registration may
+        // throw on api.runtime access, so read the plugin entry from api.config only.
+        const hookGrantMissing = hasAnyKey && !conversationAccessGranted(api.config, api.id)
+            && (() => { try {
+                return hostGatesConversationHooks(api);
+            }
+            catch {
+                return false;
+            } })();
+        if (hasAnyKey && (!nativeMemorySearchDisabled(api)
+            || api.config?.plugins?.entries?.[api.id]?.enabled !== true
+            || (Array.isArray(api.config?.plugins?.allow) && !api.config.plugins.allow.includes(api.id))
+            || hookGrantMissing)) {
+            api.logger.info?.("memoryrouter: config repair available — run: openclaw mr doctor");
+        }
         if (hasAnyKey) {
             if (memoryKey)
                 api.logger.info?.(`memoryrouter: active (key: ${memoryKey.slice(0, 6)}...)`);
@@ -1108,7 +1196,7 @@ If setting up MemoryRouter for another agent:
                         }
                     },
                 };
-            });
+            }, { name: "memory_search" });
             // memory_date_search: calls MR /v1/memory/date-search (time-window retrieval)
             api.registerTool((ctx) => {
                 const toolKey = resolveKey(ctx);
@@ -1206,7 +1294,7 @@ If setting up MemoryRouter for another agent:
                         }
                     },
                 };
-            });
+            }, { name: "memory_date_search" });
             // ==================================================================
             // Tools: memory_reflect + memory_commit (consolidation, two-tool shape)
             // Mirrors the MCP consolidate_memories / commit_reflections pair.
@@ -1279,7 +1367,7 @@ If setting up MemoryRouter for another agent:
                         }
                     },
                 };
-            });
+            }, { name: "memory_reflect" });
             // memory_commit: commit wrapper (idempotent; 409 means the lease expired)
             api.registerTool((ctx) => {
                 const toolKey = resolveKey(ctx);
@@ -1366,7 +1454,7 @@ If setting up MemoryRouter for another agent:
                         }
                     },
                 };
-            });
+            }, { name: "memory_commit" });
             // memory_inspect: read-only lineage drill-down (curation surface, ids allowed)
             api.registerTool((ctx) => {
                 const toolKey = resolveKey(ctx);
@@ -1403,7 +1491,7 @@ If setting up MemoryRouter for another agent:
                         }
                     },
                 };
-            });
+            }, { name: "memory_inspect" });
             // memory_get — exact copy of OpenClaw's implementation (pure local file read)
             api.registerTool((ctx) => {
                 const workspaceDir = ctx.workspaceDir || "";
@@ -1442,7 +1530,7 @@ If setting up MemoryRouter for another agent:
                         }
                     },
                 };
-            });
+            }, { name: "memory_get" });
         } // end if (hasAnyKey)
         // ==================================================================
         // CLI Commands
@@ -1455,22 +1543,17 @@ If setting up MemoryRouter for another agent:
                 }
                 try {
                     await mergePluginConfig(api, { key });
-                    await setPluginEnabled(api, true);
-                    try {
-                        const changed = await setNativeMemorySearchEnabled(false);
-                        if (changed)
-                            console.log(`  • Native memory search disabled — MemoryRouter now owns memory_search`);
-                    }
-                    catch (err) {
-                        console.error(`  ⚠ Could not disable native memory search: ${err instanceof Error ? err.message : String(err)}`);
-                    }
+                    await ensureDoctorSafePluginEntry(api);
+                    await selfHealNativeMemorySearch(api);
                     console.log(`✓ MemoryRouter enabled. Key: ${key.slice(0, 6)}...${key.slice(-3)}`);
                     console.log(`  • memory_search + memory_date_search + memory_get tools registered via plugin`);
+                    console.log(`  • Restart the gateway to apply: openclaw gateway restart`);
                     console.log(`\nRun: openclaw mr upload    to upload your memories`);
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);
                     console.error(`Failed to enable MemoryRouter: ${message}`);
+                    process.exitCode = 1;
                 }
             };
             const mr = program
@@ -1488,6 +1571,25 @@ If setting up MemoryRouter for another agent:
                 .description("Enable MemoryRouter with a memory key (alias)")
                 .argument("<key>", "Your MemoryRouter memory key (mk_xxx)")
                 .action(async (key) => { await applyKey(key); });
+            mr.command("doctor")
+                .description("Repair MemoryRouter plugin registration and native memory-search settings")
+                .action(async () => {
+                try {
+                    await ensureDoctorSafePluginEntry(api);
+                    const current = await readOpenClawConfigFile(api);
+                    const saved = current.plugins?.entries?.[api.id]?.config;
+                    const hasSavedKey = !!(saved?.key || Object.values(saved?.agentKeys ?? {}).some(Boolean));
+                    if (hasSavedKey)
+                        await selfHealNativeMemorySearch(api);
+                    console.log("✓ MemoryRouter config repaired. Restart gateway to apply changed settings.");
+                    if (!hasSavedKey)
+                        console.log("  • No key configured — run: openclaw mr <key>");
+                }
+                catch (err) {
+                    console.error(`MemoryRouter doctor failed: ${err instanceof Error ? err.message : String(err)}`);
+                    process.exitCode = 1;
+                }
+            });
             mr.command("off")
                 .description("Disable MemoryRouter (removes key, keeps CLI available)")
                 .action(async () => {
@@ -1498,7 +1600,7 @@ If setting up MemoryRouter for another agent:
                     // Note: we intentionally do NOT call setPluginEnabled(api, false)
                     // Restore native memory search so the user isn't left with NO memory search.
                     try {
-                        const changed = await setNativeMemorySearchEnabled(true);
+                        const changed = await setNativeMemorySearchEnabled(api, true);
                         if (changed)
                             console.log("  • Native memory search restored");
                     }

package/index.ts

@@ -363,7 +363,47 @@ function openClawConfigPath(): string {
   return process.env.OPENCLAW_CONFIG_PATH || process.env.OPENCLAW_CONFIG || join(os.homedir(), ".openclaw", "openclaw.json");
 }
 
-async function readOpenClawConfigFile(): Promise<JsonObject> {
+type HostConfigApi = {
+  loadConfig?: () => JsonObject;
+  writeConfigFile?: (config: JsonObject) => Promise<unknown>;
+  current?: () => JsonObject;
+  mutateConfigFile?: (params: {
+    base: "source";
+    afterWrite: { mode: "none"; reason: string };
+    mutate: (draft: JsonObject) => boolean;
+  }) => Promise<{ result?: boolean }>;
+};
+
+function hostConfigApi(api: OpenClawPluginApi): HostConfigApi | undefined {
+  return api.runtime?.config as unknown as HostConfigApi | undefined;
+}
+
+// OpenClaw's current()/mutateConfigFile API accompanies the canonical memory
+// owner schema (memory.search). Older OpenClaw and John's Harness retain
+// agents.defaults.memorySearch. Do not use the host version: forks version
+// independently of their upstream config schema.
+function usesCanonicalMemorySearch(api: OpenClawPluginApi): boolean {
+  return typeof hostConfigApi(api)?.current === "function";
+}
+
+function nativeMemorySearchDisabled(api: OpenClawPluginApi): boolean {
+  const config = api.config as JsonObject;
+  // Metadata-only registration may deliberately throw on api.runtime access.
+  // Read the provided config only; runtime capability detection belongs in CLI actions.
+  return config?.memory?.search?.enabled === false
+    || config?.agents?.defaults?.memorySearch?.enabled === false;
+}
+
+// Only explicit CLI actions call these helpers. Loading/registering the plugin
+// must never mutate the host config (including fire-and-forget writes).
+async function readOpenClawConfigFile(api: OpenClawPluginApi): Promise<JsonObject> {
+  const runtimeConfig = hostConfigApi(api);
+  if (typeof runtimeConfig?.current === "function") {
+    return structuredClone(runtimeConfig.current());
+  }
+  if (typeof runtimeConfig?.loadConfig === "function") {
+    return structuredClone(runtimeConfig.loadConfig());
+  }
   try {
     return JSON.parse(await readFile(openClawConfigPath(), "utf8"));
   } catch (err: any) {
@@ -372,7 +412,13 @@ async function readOpenClawConfigFile(): Promise<JsonObject> {
   }
 }
 
-async function writeOpenClawConfigFile(config: JsonObject): Promise<void> {
+async function writeOpenClawConfigFile(api: OpenClawPluginApi, config: JsonObject): Promise<void> {
+  const runtimeConfig = hostConfigApi(api);
+  if (typeof runtimeConfig?.writeConfigFile === "function") {
+    await runtimeConfig.writeConfigFile(config);
+    return;
+  }
+  // Legacy hosts only: no native config writer is exposed.
   const configPath = openClawConfigPath();
   await mkdir(dirname(configPath), { recursive: true });
   try {
@@ -384,54 +430,70 @@ async function writeOpenClawConfigFile(config: JsonObject): Promise<void> {
 `, "utf8");
 }
 
+async function mutateOpenClawConfigFile(api: OpenClawPluginApi, mutate: (draft: JsonObject) => boolean): Promise<boolean> {
+  const runtimeConfig = hostConfigApi(api);
+  if (typeof runtimeConfig?.mutateConfigFile === "function") {
+    // The host rewrites the file on every mutation call, even a no-op one.
+    // Probe a snapshot first so repeated `mr doctor` runs stay write-free.
+    if (typeof runtimeConfig.current === "function") {
+      const probe = structuredClone(runtimeConfig.current());
+      if (!mutate(probe)) return false;
+    }
+    // Let the host acquire its lock and supply the latest authored config.
+    // Never auto-restart a gateway as a side effect of a plugin CLI command.
+    const result = await runtimeConfig.mutateConfigFile({
+      base: "source",
+      afterWrite: { mode: "none", reason: "MemoryRouter explicit CLI configuration; restart manually to apply" },
+      mutate,
+    });
+    return result.result === true;
+  }
+  const config = await readOpenClawConfigFile(api);
+  if (!mutate(config)) return false;
+  await writeOpenClawConfigFile(api, config);
+  return true;
+}
+
 // ──────────────────────────────────────────────────────
 // Full-replace: disable OpenClaw's native memory search so MemoryRouter
 // owns the memory_search tool (no name conflict, no native embeddings 429).
 // memoryFlush (durable MEMORY.md writes) is intentionally left untouched.
-// Global + subagents: writes agents.defaults.memorySearch.enabled.
-// ──────────────────────────────────────────────────────
-async function setNativeMemorySearchEnabled(enabled: boolean): Promise<boolean> {
-  const config = await readOpenClawConfigFile();
-  config.agents ??= {};
-  config.agents.defaults ??= {};
-  config.agents.defaults.memorySearch ??= {};
-  if (config.agents.defaults.memorySearch.enabled === enabled) return false; // no-op
-  config.agents.defaults.memorySearch.enabled = enabled;
-  await writeOpenClawConfigFile(config);
-  return true;
+// Global defaults cover subagents unless the user explicitly overrides them.
+async function setNativeMemorySearchEnabled(api: OpenClawPluginApi, enabled: boolean): Promise<boolean> {
+  return mutateOpenClawConfigFile(api, (config) => {
+    let search: JsonObject;
+    if (usesCanonicalMemorySearch(api)) {
+      config.memory ??= {};
+      config.memory.search ??= {};
+      search = config.memory.search;
+    } else {
+      config.agents ??= {};
+      config.agents.defaults ??= {};
+      config.agents.defaults.memorySearch ??= {};
+      search = config.agents.defaults.memorySearch;
+    }
+    if (search.enabled === enabled) return false;
+    search.enabled = enabled;
+    return true;
+  });
 }
 
-// Boot-time self-heal: if a key is configured but native search is still on,
-// flip it off so already-installed users are fixed on restart after updating
-// (no need to re-run `openclaw mr <key>`).
+// Explicit setup/doctor repair only. With no key, leave native search available.
 async function selfHealNativeMemorySearch(api: OpenClawPluginApi): Promise<void> {
-  try {
-    const config = await readOpenClawConfigFile();
-    const ms = config?.agents?.defaults?.memorySearch;
-    if (ms?.enabled === false) return; // already disabled — nothing to do
-    const changed = await setNativeMemorySearchEnabled(false);
-    if (changed) {
-      api.logger.info?.(
-        "memoryrouter: disabled native memory search (full-replace). Restart gateway to apply.",
-      );
-    }
-  } catch (err) {
-    api.logger.info?.(
-      `memoryrouter: self-heal skipped — ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
+  const changed = await setNativeMemorySearchEnabled(api, false);
+  if (changed) console.log("  • Native memory search disabled — MemoryRouter now owns memory_search");
 }
 
-async function updateOpenClawPluginEntry(api: OpenClawPluginApi, patch: JsonObject): Promise<void> {
-  const config = await readOpenClawConfigFile();
-  config.plugins ??= {};
-  config.plugins.entries ??= {};
-  config.plugins.entries[api.id] ??= {};
-  config.plugins.entries[api.id] = {
-    ...config.plugins.entries[api.id],
-    ...patch,
-  };
-  await writeOpenClawConfigFile(config);
+async function updateOpenClawPluginEntry(api: OpenClawPluginApi, patch: JsonObject, mergeConfig = false): Promise<void> {
+  await mutateOpenClawConfigFile(api, (config) => {
+    config.plugins ??= {};
+    config.plugins.entries ??= {};
+    config.plugins.entries[api.id] ??= { enabled: true };
+    const entry = config.plugins.entries[api.id];
+    if (patch.config) entry.config = mergeConfig ? { ...(entry.config || {}), ...patch.config } : patch.config;
+    if (typeof patch.enabled === "boolean") entry.enabled = patch.enabled;
+    return true;
+  });
 }
 
 async function setPluginConfig(api: OpenClawPluginApi, config: Record<string, unknown>): Promise<void> {
@@ -453,7 +515,13 @@ async function setPluginEnabled(api: OpenClawPluginApi, enabled: boolean): Promi
 }
 
 async function mergePluginConfig(api: OpenClawPluginApi, patch: Record<string, unknown>): Promise<void> {
-  const current = await readOpenClawConfigFile();
+  if (typeof (api as CompatApi).updatePluginConfig !== "function") {
+    // Merge the focused patch inside the host's transaction, not into a stale
+    // runtime snapshot which could overwrite another command's latest changes.
+    await updateOpenClawPluginEntry(api, { config: patch }, true);
+    return;
+  }
+  const current = await readOpenClawConfigFile(api);
   const existing = current.plugins?.entries?.[api.id]?.config;
   await setPluginConfig(api, {
     ...(existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {}),
@@ -461,36 +529,51 @@ async function mergePluginConfig(api: OpenClawPluginApi, patch: Record<string, u
   });
 }
 
-// Keep mr-memory as a first-class plugin config entry without clobbering user settings.
-// OpenClaw doctor validates plugin entries against discoverable manifests, so the entry
-// must be present, enabled, and allowlisted when an allowlist exists.
+// OpenClaw 2026.10+ drops every conversation hook (before_prompt_build,
+// llm_input, agent_end) from a non-bundled plugin unless the user grants
+// plugins.entries.<id>.hooks.allowConversationAccess. Without it mr-memory
+// loads but never injects or captures a single memory. The grant is only
+// written by the explicit CLI actions, on hosts whose schema accepts it
+// (the same hosts that expose current()/mutateConfigFile). Older hosts and
+// John's Harness reject unknown keys under hooks, so they are left alone.
+function hostGatesConversationHooks(api: OpenClawPluginApi): boolean {
+  return usesCanonicalMemorySearch(api);
+}
+
+function conversationAccessGranted(config: JsonObject, pluginId: string): boolean {
+  return config?.plugins?.entries?.[pluginId]?.hooks?.allowConversationAccess === true;
+}
+
+async function ensureConversationHookAccess(api: OpenClawPluginApi): Promise<boolean> {
+  if (!hostGatesConversationHooks(api)) return false;
+  return mutateOpenClawConfigFile(api, (config) => {
+    config.plugins ??= {};
+    config.plugins.entries ??= {};
+    config.plugins.entries[api.id] ??= { enabled: true };
+    const entry = config.plugins.entries[api.id];
+    if (entry.hooks?.allowConversationAccess === true) return false;
+    entry.hooks = { ...(entry.hooks && typeof entry.hooks === "object" ? entry.hooks : {}), allowConversationAccess: true };
+    return true;
+  });
+}
+
+// Explicit setup/doctor repair; preserve all config, use native plugin APIs first.
+// Never call this from register(), a hook, or service.start().
 async function ensureDoctorSafePluginEntry(api: OpenClawPluginApi): Promise<void> {
-  try {
-    const config = await readOpenClawConfigFile();
-    const plugins = config.plugins ?? {};
-    const entries = plugins.entries ?? {};
-    const existingEntry = entries[api.id] && typeof entries[api.id] === "object" && !Array.isArray(entries[api.id])
-      ? entries[api.id]
-      : {};
-    const nextPlugins: JsonObject = {
-      ...plugins,
-      entries: {
-        ...entries,
-        [api.id]: {
-          ...existingEntry,
-          enabled: true,
-        },
-      },
-    };
-    if (Array.isArray(plugins.allow) && !plugins.allow.includes(api.id)) {
-      nextPlugins.allow = [...plugins.allow, api.id];
-    }
-    const next = { ...config, plugins: nextPlugins };
-    if (JSON.stringify(next.plugins) === JSON.stringify(config.plugins)) return;
-    await writeOpenClawConfigFile(next);
-  } catch (err) {
-    api.logger.info?.(`memoryrouter: doctor-safe registration skipped — ${err instanceof Error ? err.message : String(err)}`);
+  const config = await readOpenClawConfigFile(api);
+  if (config.plugins?.entries?.[api.id]?.enabled !== true) {
+    await setPluginEnabled(api, true);
   }
+  // Plugin-enable APIs do not necessarily maintain plugins.allow. Re-read after
+  // enabling so a host API's config update cannot be overwritten by a stale copy.
+  await mutateOpenClawConfigFile(api, (current) => {
+    const allow = current.plugins?.allow;
+    if (!Array.isArray(allow) || allow.includes(api.id)) return false;
+    current.plugins.allow = [...allow, api.id];
+    return true;
+  });
+  const granted = await ensureConversationHookAccess(api);
+  if (granted) console.log("  • Conversation hook access granted — MemoryRouter can inject and capture memory");
 }
 
 /**
@@ -660,10 +743,19 @@ const memoryRouterPlugin = {
       warmupTimer.unref?.();
     }
 
-    void (async () => {
-      await ensureDoctorSafePluginEntry(api);
-      if (hasAnyKey) await selfHealNativeMemorySearch(api);
-    })();
+    // Host install/update/doctor may load plugins inside a guarded config
+    // transaction. Even an unawaited write here races its base-hash check.
+    // Configuration repair is owned exclusively by the explicit CLI actions.
+    // Hook gating is a runtime capability check; metadata-only registration may
+    // throw on api.runtime access, so read the plugin entry from api.config only.
+    const hookGrantMissing = hasAnyKey && !conversationAccessGranted(api.config as JsonObject, api.id)
+      && (() => { try { return hostGatesConversationHooks(api); } catch { return false; } })();
+    if (hasAnyKey && (!nativeMemorySearchDisabled(api)
+      || api.config?.plugins?.entries?.[api.id]?.enabled !== true
+      || (Array.isArray(api.config?.plugins?.allow) && !api.config.plugins.allow.includes(api.id))
+      || hookGrantMissing)) {
+      api.logger.info?.("memoryrouter: config repair available — run: openclaw mr doctor");
+    }
 
     if (hasAnyKey) {
       if (memoryKey) api.logger.info?.(`memoryrouter: active (key: ${memoryKey.slice(0, 6)}...)`);
@@ -1187,7 +1279,7 @@ If setting up MemoryRouter for another agent:
             }
           },
         };
-      });
+      }, { name: "memory_search" });
 
       // memory_date_search: calls MR /v1/memory/date-search (time-window retrieval)
       api.registerTool((ctx) => {
@@ -1290,7 +1382,7 @@ If setting up MemoryRouter for another agent:
             }
           },
         };
-      });
+      }, { name: "memory_date_search" });
 
       // ==================================================================
       // Tools: memory_reflect + memory_commit (consolidation, two-tool shape)
@@ -1372,7 +1464,7 @@ If setting up MemoryRouter for another agent:
             }
           },
         };
-      });
+      }, { name: "memory_reflect" });
 
       // memory_commit: commit wrapper (idempotent; 409 means the lease expired)
       api.registerTool((ctx) => {
@@ -1460,7 +1552,7 @@ If setting up MemoryRouter for another agent:
             }
           },
         };
-      });
+      }, { name: "memory_commit" });
 
       // memory_inspect: read-only lineage drill-down (curation surface, ids allowed)
       api.registerTool((ctx) => {
@@ -1495,7 +1587,7 @@ If setting up MemoryRouter for another agent:
             }
           },
         };
-      });
+      }, { name: "memory_inspect" });
 
       // memory_get — exact copy of OpenClaw's implementation (pure local file read)
       api.registerTool((ctx) => {
@@ -1533,7 +1625,7 @@ If setting up MemoryRouter for another agent:
             }
           },
         };
-      });
+      }, { name: "memory_get" });
     } // end if (hasAnyKey)
 
     // ==================================================================
@@ -1549,19 +1641,16 @@ If setting up MemoryRouter for another agent:
           }
           try {
             await mergePluginConfig(api, { key });
-            await setPluginEnabled(api, true);
-            try {
-              const changed = await setNativeMemorySearchEnabled(false);
-              if (changed) console.log(`  • Native memory search disabled — MemoryRouter now owns memory_search`);
-            } catch (err) {
-              console.error(`  ⚠ Could not disable native memory search: ${err instanceof Error ? err.message : String(err)}`);
-            }
+            await ensureDoctorSafePluginEntry(api);
+            await selfHealNativeMemorySearch(api);
             console.log(`✓ MemoryRouter enabled. Key: ${key.slice(0, 6)}...${key.slice(-3)}`);
             console.log(`  • memory_search + memory_date_search + memory_get tools registered via plugin`);
+            console.log(`  • Restart the gateway to apply: openclaw gateway restart`);
             console.log(`\nRun: openclaw mr upload    to upload your memories`);
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             console.error(`Failed to enable MemoryRouter: ${message}`);
+            process.exitCode = 1;
           }
         };
 
@@ -1579,6 +1668,23 @@ If setting up MemoryRouter for another agent:
           .argument("<key>", "Your MemoryRouter memory key (mk_xxx)")
           .action(async (key: string) => { await applyKey(key); });
 
+        mr.command("doctor")
+          .description("Repair MemoryRouter plugin registration and native memory-search settings")
+          .action(async () => {
+            try {
+              await ensureDoctorSafePluginEntry(api);
+              const current = await readOpenClawConfigFile(api);
+              const saved = current.plugins?.entries?.[api.id]?.config;
+              const hasSavedKey = !!(saved?.key || Object.values(saved?.agentKeys ?? {}).some(Boolean));
+              if (hasSavedKey) await selfHealNativeMemorySearch(api);
+              console.log("✓ MemoryRouter config repaired. Restart gateway to apply changed settings.");
+              if (!hasSavedKey) console.log("  • No key configured — run: openclaw mr <key>");
+            } catch (err) {
+              console.error(`MemoryRouter doctor failed: ${err instanceof Error ? err.message : String(err)}`);
+              process.exitCode = 1;
+            }
+          });
+
         mr.command("off")
           .description("Disable MemoryRouter (removes key, keeps CLI available)")
           .action(async () => {
@@ -1589,7 +1695,7 @@ If setting up MemoryRouter for another agent:
               // Note: we intentionally do NOT call setPluginEnabled(api, false)
               // Restore native memory search so the user isn't left with NO memory search.
               try {
-                const changed = await setNativeMemorySearchEnabled(true);
+                const changed = await setNativeMemorySearchEnabled(api, true);
                 if (changed) console.log("  • Native memory search restored");
               } catch (err) {
                 console.error(`  ⚠ Could not restore native memory search: ${err instanceof Error ? err.message : String(err)}`);

package/openclaw.plugin.json

@@ -2,37 +2,43 @@
   "id": "mr-memory",
   "name": "MemoryRouter Memory",
   "description": "Persistent memory for OpenClaw, powered by MemoryRouter. Memory that survives sessions, compaction, and model changes.",
-  "icon": "https://memoryrouter.ai/logo.png",
-  "uiHints": {
-    "key": {
-      "label": "Memory Key",
-      "sensitive": true,
-      "placeholder": "mk_xxx",
-      "help": "Your MemoryRouter API key (get one at memoryrouter.ai)"
-    },
-    "endpoint": {
-      "label": "API Endpoint",
-      "placeholder": "https://api.memoryrouter.ai/v1",
-      "advanced": true,
-      "help": "Override for self-hosted MemoryRouter"
-    },
-    "density": {
-      "label": "Memory Density",
-      "placeholder": "medium",
-      "advanced": true,
-      "help": "Current choices: low, up to 21 memories (12 raw + 6 tier 2 + 3 tier 3); medium, up to 43 (25 + 12 + 6), balanced default; high, up to 87 (50 + 25 + 12)."
+  "version": "3.14.0",
+  "activation": {
+    "onStartup": true,
+    "onCommands": [
+      "mr"
+    ],
+    "onCapabilities": [
+      "hook",
+      "tool"
+    ]
+  },
+  "cliCommands": [
+    {
+      "name": "mr",
+      "description": "MemoryRouter memory commands",
+      "hasSubcommands": true
+    }
+  ],
+  "contracts": {
+    "tools": [
+      "memory_search",
+      "memory_date_search",
+      "memory_get",
+      "memory_reflect",
+      "memory_commit",
+      "memory_inspect"
+    ]
+  },
+  "toolMetadata": {
+    "memory_get": {
+      "replaySafe": true
     },
-    "keepWarmMs": {
-      "label": "Keep Warm Window (ms)",
-      "placeholder": "180000",
-      "advanced": true,
-      "help": "How long to keep your vault warm after each message. Default 180000 (3 min). Set 0 to disable warmup pings."
+    "memory_inspect": {
+      "replaySafe": true
     },
-    "autoConsolidate": {
-      "label": "Automatic Consolidation",
-      "placeholder": "true",
-      "advanced": true,
-      "help": "Automatically consolidate memories in the background when debt crosses the server threshold. Default true."
+    "memory_commit": {
+      "sideEffecting": true
     }
   },
   "configSchema": {
@@ -57,11 +63,17 @@
       },
       "mode": {
         "type": "string",
-        "enum": ["relay", "proxy"]
+        "enum": [
+          "relay",
+          "proxy"
+        ]
       },
       "embeddings": {
         "type": "string",
-        "enum": ["bge", "qwen"],
+        "enum": [
+          "bge",
+          "qwen"
+        ],
         "description": "Embedding model: bge (1024d, default) or qwen (4096d)"
       },
       "keepWarmMs": {
@@ -83,5 +95,38 @@
       }
     },
     "required": []
-  }
+  },
+  "uiHints": {
+    "key": {
+      "label": "Memory Key",
+      "sensitive": true,
+      "placeholder": "mk_xxx",
+      "help": "Your MemoryRouter API key (get one at memoryrouter.ai)"
+    },
+    "endpoint": {
+      "label": "API Endpoint",
+      "placeholder": "https://api.memoryrouter.ai/v1",
+      "advanced": true,
+      "help": "Override for self-hosted MemoryRouter"
+    },
+    "density": {
+      "label": "Memory Density",
+      "placeholder": "medium",
+      "advanced": true,
+      "help": "Current choices: low, up to 21 memories (12 raw + 6 tier 2 + 3 tier 3); medium, up to 43 (25 + 12 + 6), balanced default; high, up to 87 (50 + 25 + 12)."
+    },
+    "keepWarmMs": {
+      "label": "Keep Warm Window (ms)",
+      "placeholder": "180000",
+      "advanced": true,
+      "help": "How long to keep your vault warm after each message. Default 180000 (3 min). Set 0 to disable warmup pings."
+    },
+    "autoConsolidate": {
+      "label": "Automatic Consolidation",
+      "placeholder": "true",
+      "advanced": true,
+      "help": "Automatically consolidate memories in the background when debt crosses the server threshold. Default true."
+    }
+  },
+  "icon": "https://memoryrouter.ai/logo.png"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-memory",
-  "version": "3.13.2",
+  "version": "3.14.0",
   "description": "Persistent memory for OpenClaw, powered by MemoryRouter. Relay-based AI agent memory across sessions, compaction, and model changes.",
   "type": "module",
   "files": [
@@ -49,12 +49,8 @@
     "extensions": [
       "./index.js"
     ],
-    "compat": {
-      "pluginApi": ">=2026.3.7"
-    },
     "install": {
-      "npmSpec": "mr-memory",
-      "minHostVersion": ">=2026.3.7"
+      "npmSpec": "mr-memory"
     }
   },
   "main": "./index.js",