mr-memory 3.7.9 → 3.8.0

package/README.md

@@ -9,10 +9,10 @@ Use it when you want OpenClaw memory that does not restart from zero every sessi
 ## Install
 
 ```bash
-openclaw plugins install npm:mr-memory@3.7.9
+openclaw plugins install npm:mr-memory@3.8.0
 ```
 
-The explicit `npm:` source and version make the audited install deterministic. `mr-memory@3.7.9` is published on npm. A ClawHub listing has not been verified and is not required for this path.
+The explicit `npm:` source and version make the audited install deterministic. `mr-memory@3.8.0` is published on npm. A ClawHub listing has not been verified and is not required for this path.
 
 ## Setup
 
@@ -46,6 +46,16 @@ When enabled, relay hooks retrieve memory before agent/model input and capture t
 
 Only direct user-to-AI conversation is stored. Tool use, subagent work, and internal processing are excluded. Historical workspace/session upload is a separate explicit `openclaw mr upload` operation; installing or enabling the relay does not imply an import already happened.
 
+### Keep-warm
+
+Retrieval is fastest against a warm vault, so the plugin keeps yours warm for **3 minutes after each message**. Every message re-opens that window; once it lapses with no new activity the warmup timer is cleared entirely, so an idle agent sends **no** background warmup traffic. There is no startup ping and no always-on keepalive.
+
+Tune it with `keepWarmMs` (milliseconds, default `180000`; `0` disables warmup pings):
+
+```json
+{ "plugins": { "entries": { "mr-memory": { "config": { "keepWarmMs": 180000 } } } } }
+```
+
 ## Config
 
 After `openclaw mr <key>`, config is stored at:

package/index.js

@@ -12,6 +12,15 @@ import { deleteMemories, getMemoryStats, ingestMemory, prepareMemory, searchMemo
 import { join, resolve, relative, isAbsolute, sep, dirname } from "node:path";
 import os from "node:os";
 const DEFAULT_ENDPOINT = "https://api.memoryrouter.ai";
+/** Keep-warm defaults.
+ *
+ *  Warmth only matters in the minutes right after real activity, so warmup
+ *  pings are activity-scoped instead of always-on: every message opens a
+ *  KEEP_WARM window, pings fire at KEEP_WARM_PING_INTERVAL_MS inside it, and
+ *  the timer is cleared completely once the window closes. An idle gateway
+ *  sends zero warmup traffic. */
+const DEFAULT_KEEP_WARM_MS = 3 * 60 * 1000; // 3 minutes after the last message
+const KEEP_WARM_PING_INTERVAL_MS = 60 * 1000; // cadence inside the window
 /** Strip media-attached references and OpenClaw media instruction text so
  *  old screenshots/photos/audio don't get stored and re-injected forever. */
 const MEDIA_ATTACHED_RE = /\[media attached[^\]]*\]/gi;
@@ -299,37 +308,34 @@ async function writeOpenClawConfigFile(config) {
 // 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;
+    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;
 }
-
 // 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>`).
 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.",
-      );
+    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)}`);
     }
-  } catch (err) {
-    api.logger.info?.(
-      `memoryrouter: self-heal skipped — ${err instanceof Error ? err.message : String(err)}`,
-    );
-  }
 }
-
 async function updateOpenClawPluginEntry(api, patch) {
     const config = await readOpenClawConfigFile();
     config.plugins ??= {};
@@ -475,6 +481,80 @@ const memoryRouterPlugin = {
             return memoryKey;
         }
         const hasAnyKey = !!(memoryKey || (agentKeys && Object.keys(agentKeys).length > 0));
+        // Keep-warm window: 0 (or negative) disables warmup pings entirely.
+        const keepWarmMs = typeof cfg?.keepWarmMs === "number" && cfg.keepWarmMs >= 0
+            ? cfg.keepWarmMs
+            : DEFAULT_KEEP_WARM_MS;
+        let warmupTimer;
+        // undefined = no activity yet (never compare against 0; a 0 timestamp is a
+        // valid clock value and must not read as "no activity").
+        let lastActivityAt;
+        // Starts true so keep-warm works even if the host never calls service.start();
+        // service.stop() flips it off so no timer can outlive the plugin.
+        let serviceRunning = true;
+        function configuredKeys() {
+            const keys = new Set();
+            if (memoryKey)
+                keys.add(memoryKey);
+            if (agentKeys) {
+                for (const key of Object.values(agentKeys)) {
+                    if (key)
+                        keys.add(key);
+                }
+            }
+            return Array.from(keys);
+        }
+        function pingWarmup(reason) {
+            for (const key of configuredKeys()) {
+                warmupMemory(endpoint, key, embeddings)
+                    .then(async (res) => {
+                    if (!res.ok) {
+                        log(`memoryrouter: warmup ${reason} failed (${res.status})`);
+                        return;
+                    }
+                    const data = await res.json().catch(() => null);
+                    log(`memoryrouter: warmup ${reason} ok (${data?.totalVectors ?? 0} vectors, ${data?.warmupTimeMs ?? "?"}ms)`);
+                })
+                    .catch((err) => {
+                    log(`memoryrouter: warmup ${reason} error — ${err instanceof Error ? err.message : String(err)}`);
+                });
+            }
+        }
+        function stopWarmLoop() {
+            if (warmupTimer) {
+                clearInterval(warmupTimer);
+                warmupTimer = undefined;
+            }
+        }
+        /** True while we're still inside the post-message keep-warm window. */
+        function withinWarmWindow() {
+            if (keepWarmMs <= 0 || lastActivityAt === undefined)
+                return false;
+            return Date.now() - lastActivityAt <= keepWarmMs;
+        }
+        /** Called on every message-driven activity (prepare / ingest).
+         *  Opens (or extends) the keep-warm window and makes sure the loop runs.
+         *  Once the window lapses with no new activity the interval is cleared, so
+         *  an idle gateway sends no warmup traffic at all. */
+        function noteActivity() {
+            if (!hasAnyKey || keepWarmMs <= 0 || !serviceRunning)
+                return;
+            lastActivityAt = Date.now();
+            if (warmupTimer)
+                return; // window extended; existing loop keeps running
+            // No immediate ping: the prepare/ingest request that triggered this call
+            // already warmed the vault server-side. Pings only cover the idle gaps
+            // inside the window.
+            warmupTimer = setInterval(() => {
+                if (!withinWarmWindow()) {
+                    log("memoryrouter: keep-warm window elapsed — pings stopped until next message");
+                    stopWarmLoop();
+                    return;
+                }
+                pingWarmup("keepalive");
+            }, KEEP_WARM_PING_INTERVAL_MS);
+            warmupTimer.unref?.();
+        }
         void (async () => {
             await ensureDoctorSafePluginEntry(api);
             if (hasAnyKey)
@@ -628,6 +708,8 @@ If setting up MemoryRouter for another agent:
                             contextPayload.push({ role: "user", content: taskPrompt });
                         }
                     }
+                    // Message activity — open/extend the keep-warm window.
+                    noteActivity();
                     const res = await prepareMemory(endpoint, activeKey, {
                         messages: contextPayload,
                         density,
@@ -728,6 +810,8 @@ If setting up MemoryRouter for another agent:
                         }
                     }
                     // 4. Call /v1/memory/prepare (no session_id — always search core vault)
+                    // Message activity — open/extend the keep-warm window.
+                    noteActivity();
                     const res = await prepareMemory(endpoint, activeKey, {
                         messages: contextPayload,
                         density,
@@ -834,6 +918,8 @@ If setting up MemoryRouter for another agent:
                         log("memoryrouter: skipped ingest — system noise filtered out");
                         return;
                     }
+                    // Message activity — open/extend the keep-warm window.
+                    noteActivity();
                     // Fire and forget — don't block message delivery waiting for ingest
                     ingestMemory(endpoint, activeKey, {
                         messages: toStore,
@@ -971,8 +1057,10 @@ If setting up MemoryRouter for another agent:
                     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) {
+                        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)}`);
                     }
                     console.log(`✓ MemoryRouter enabled. Key: ${key.slice(0, 6)}...${key.slice(-3)}`);
@@ -1010,8 +1098,10 @@ If setting up MemoryRouter for another agent:
                     // Restore native memory search so the user isn't left with NO memory search.
                     try {
                         const changed = await setNativeMemorySearchEnabled(true);
-                        if (changed) console.log("  • Native memory search restored");
-                    } catch (err) {
+                        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)}`);
                     }
                     console.log("✓ MemoryRouter disabled (key cleared).");
@@ -1215,17 +1305,19 @@ If setting up MemoryRouter for another agent:
             start: () => {
                 if (memoryKey)
                     api.logger.info?.(`memoryrouter: active (key: ${memoryKey.slice(0, 6)}...)`);
-                if (hasAnyKey && !warmupTimer) {
-                    pingWarmup("startup");
-                    warmupTimer = setInterval(() => pingWarmup("keepalive"), 4 * 60 * 1000);
-                    warmupTimer.unref?.();
+                serviceRunning = true;
+                // No startup ping and no always-on keepalive: warmth is driven by real
+                // activity. The first message opens the keep-warm window.
+                if (hasAnyKey) {
+                    log(keepWarmMs > 0
+                        ? `memoryrouter: keep-warm armed (${Math.round(keepWarmMs / 1000)}s after each message)`
+                        : "memoryrouter: keep-warm disabled (keepWarmMs: 0)");
                 }
             },
             stop: () => {
-                if (warmupTimer) {
-                    clearInterval(warmupTimer);
-                    warmupTimer = undefined;
-                }
+                serviceRunning = false;
+                lastActivityAt = undefined;
+                stopWarmLoop();
                 api.logger.info?.("memoryrouter: stopped");
             },
         });

package/index.ts

@@ -17,6 +17,16 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 
 const DEFAULT_ENDPOINT = "https://api.memoryrouter.ai";
 
+/** Keep-warm defaults.
+ *
+ *  Warmth only matters in the minutes right after real activity, so warmup
+ *  pings are activity-scoped instead of always-on: every message opens a
+ *  KEEP_WARM window, pings fire at KEEP_WARM_PING_INTERVAL_MS inside it, and
+ *  the timer is cleared completely once the window closes. An idle gateway
+ *  sends zero warmup traffic. */
+const DEFAULT_KEEP_WARM_MS = 3 * 60 * 1000; // 3 minutes after the last message
+const KEEP_WARM_PING_INTERVAL_MS = 60 * 1000; // cadence inside the window
+
 /** Strip media-attached references and OpenClaw media instruction text so
  *  old screenshots/photos/audio don't get stored and re-injected forever. */
 const MEDIA_ATTACHED_RE = /\[media attached[^\]]*\]/gi;
@@ -282,6 +292,9 @@ type MemoryRouterConfig = {
   logging?: boolean;
   embeddings?: string;
   agentKeys?: Record<string, string>;
+  /** How long to keep the vault warm after the last message, in ms.
+   *  Default 180000 (3 minutes). Set 0 to disable warmup pings entirely. */
+  keepWarmMs?: number;
 };
 
 // ──────────────────────────────────────────────────────
@@ -501,7 +514,18 @@ const memoryRouterPlugin = {
     }
 
     const hasAnyKey = !!(memoryKey || (agentKeys && Object.keys(agentKeys).length > 0));
+
+    // Keep-warm window: 0 (or negative) disables warmup pings entirely.
+    const keepWarmMs = typeof cfg?.keepWarmMs === "number" && cfg.keepWarmMs >= 0
+      ? cfg.keepWarmMs
+      : DEFAULT_KEEP_WARM_MS;
     let warmupTimer: ReturnType<typeof setInterval> | undefined;
+    // undefined = no activity yet (never compare against 0; a 0 timestamp is a
+    // valid clock value and must not read as "no activity").
+    let lastActivityAt: number | undefined;
+    // Starts true so keep-warm works even if the host never calls service.start();
+    // service.stop() flips it off so no timer can outlive the plugin.
+    let serviceRunning = true;
 
     function configuredKeys(): string[] {
       const keys = new Set<string>();
@@ -531,6 +555,41 @@ const memoryRouterPlugin = {
       }
     }
 
+    function stopWarmLoop(): void {
+      if (warmupTimer) {
+        clearInterval(warmupTimer);
+        warmupTimer = undefined;
+      }
+    }
+
+    /** True while we're still inside the post-message keep-warm window. */
+    function withinWarmWindow(): boolean {
+      if (keepWarmMs <= 0 || lastActivityAt === undefined) return false;
+      return Date.now() - lastActivityAt <= keepWarmMs;
+    }
+
+    /** Called on every message-driven activity (prepare / ingest).
+     *  Opens (or extends) the keep-warm window and makes sure the loop runs.
+     *  Once the window lapses with no new activity the interval is cleared, so
+     *  an idle gateway sends no warmup traffic at all. */
+    function noteActivity(): void {
+      if (!hasAnyKey || keepWarmMs <= 0 || !serviceRunning) return;
+      lastActivityAt = Date.now();
+      if (warmupTimer) return; // window extended; existing loop keeps running
+      // No immediate ping: the prepare/ingest request that triggered this call
+      // already warmed the vault server-side. Pings only cover the idle gaps
+      // inside the window.
+      warmupTimer = setInterval(() => {
+        if (!withinWarmWindow()) {
+          log("memoryrouter: keep-warm window elapsed — pings stopped until next message");
+          stopWarmLoop();
+          return;
+        }
+        pingWarmup("keepalive");
+      }, KEEP_WARM_PING_INTERVAL_MS);
+      warmupTimer.unref?.();
+    }
+
     void (async () => {
       await ensureDoctorSafePluginEntry(api);
       if (hasAnyKey) await selfHealNativeMemorySearch(api);
@@ -684,6 +743,9 @@ If setting up MemoryRouter for another agent:
           }
 
 
+          // Message activity — open/extend the keep-warm window.
+          noteActivity();
+
           const res = await prepareMemory(endpoint, activeKey, {
             messages: contextPayload,
             density,
@@ -795,6 +857,9 @@ If setting up MemoryRouter for another agent:
 
           // 4. Call /v1/memory/prepare (no session_id — always search core vault)
 
+          // Message activity — open/extend the keep-warm window.
+          noteActivity();
+
           const res = await prepareMemory(endpoint, activeKey, {
             messages: contextPayload,
             density,
@@ -914,6 +979,9 @@ If setting up MemoryRouter for another agent:
             return;
           }
 
+          // Message activity — open/extend the keep-warm window.
+          noteActivity();
+
           // Fire and forget — don't block message delivery waiting for ingest
           ingestMemory(endpoint, activeKey, {
             messages: toStore,
@@ -1311,17 +1379,19 @@ If setting up MemoryRouter for another agent:
       id: "mr-memory",
       start: () => {
         if (memoryKey) api.logger.info?.(`memoryrouter: active (key: ${memoryKey.slice(0, 6)}...)`);
-        if (hasAnyKey && !warmupTimer) {
-          pingWarmup("startup");
-          warmupTimer = setInterval(() => pingWarmup("keepalive"), 4 * 60 * 1000);
-          warmupTimer.unref?.();
+        serviceRunning = true;
+        // No startup ping and no always-on keepalive: warmth is driven by real
+        // activity. The first message opens the keep-warm window.
+        if (hasAnyKey) {
+          log(keepWarmMs > 0
+            ? `memoryrouter: keep-warm armed (${Math.round(keepWarmMs / 1000)}s after each message)`
+            : "memoryrouter: keep-warm disabled (keepWarmMs: 0)");
         }
       },
       stop: () => {
-        if (warmupTimer) {
-          clearInterval(warmupTimer);
-          warmupTimer = undefined;
-        }
+        serviceRunning = false;
+        lastActivityAt = undefined;
+        stopWarmLoop();
         api.logger.info?.("memoryrouter: stopped");
       },
     });

package/openclaw.plugin.json

@@ -1,5 +1,8 @@
 {
   "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",
@@ -18,6 +21,12 @@
       "placeholder": "high",
       "advanced": true,
       "help": "Amount of memory to inject: low (40), high (80), xhigh (160)"
+    },
+    "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."
     }
   },
   "configSchema": {
@@ -47,6 +56,11 @@
         "enum": ["bge", "qwen"],
         "description": "Embedding model: bge (1024d, default) or qwen (4096d)"
       },
+      "keepWarmMs": {
+        "type": "integer",
+        "minimum": 0,
+        "description": "Keep the vault warm for this many ms after each message. Default 180000 (3 minutes). 0 disables warmup pings entirely."
+      },
       "agentKeys": {
         "type": "object",
         "additionalProperties": {

package/package.json

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