mr-memory 3.7.10 → 3.9.0

package/index.js

@@ -8,10 +8,19 @@
  * BYOK — provider API keys never touch MemoryRouter.
  */
 import { readFile, lstat, writeFile, copyFile, mkdir } from "node:fs/promises";
-import { deleteMemories, getMemoryStats, ingestMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
+import { commitReflections, consolidateCheckout, dateSearch, deleteMemories, deleteMemoryIds, getMemoryStats, ingestMemory, inspectMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
 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;
@@ -46,6 +55,16 @@ function stripOldMemory(text) {
 function jsonToolResult(payload) {
     return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], details: payload };
 }
+const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1000; // at most one nudge per 24h
+function buildDebtNudgeLine(reflection) {
+    if (!reflection || !reflection.suggestion)
+        return null;
+    const rawTokens = reflection.unconsolidated?.raw?.est_tokens ?? 0;
+    const tier2Tokens = reflection.unconsolidated?.tier2?.est_tokens ?? 0;
+    const totalTokens = rawTokens + tier2Tokens;
+    const kTokens = Math.max(1, Math.round(totalTokens / 1000));
+    return `[MemoryRouter] Consolidation available: ${kTokens}k unconsolidated tokens. Use the memory_reflect tool when convenient.`;
+}
 // ── memory_get helpers (copied from OpenClaw source — pure filesystem, no embeddings)
 function isFileMissingError(err) {
     return Boolean(err && typeof err === "object" && "code" in err && err.code === "ENOENT");
@@ -292,6 +311,37 @@ async function writeOpenClawConfigFile(config) {
     await writeFile(configPath, `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
+// Nudge rate-limit state lives beside the OpenClaw config so it survives restarts
+// without churning the main config file.
+function nudgeStatePath() {
+    return join(dirname(openClawConfigPath()), "mr-memory-state.json");
+}
+async function consumeNudgeBudget() {
+    const now = Date.now();
+    let state = {};
+    try {
+        state = JSON.parse(await readFile(nudgeStatePath(), "utf8"));
+    }
+    catch { /* missing or unreadable state: treat as never nudged */ }
+    if (typeof state.lastNudgeAt === "number" && now - state.lastNudgeAt < NUDGE_INTERVAL_MS) {
+        return false;
+    }
+    try {
+        await writeFile(nudgeStatePath(), `${JSON.stringify({ ...state, lastNudgeAt: now }, null, 2)}\n`, "utf8");
+    }
+    catch { /* state write failure must never break prepare */ }
+    return true;
+}
+/** One-line, rate-limited debt nudge for prepare injections. Returns null when
+ *  there is no suggestion or the 24h budget is spent. */
+async function maybeDebtNudge(reflection) {
+    const line = buildDebtNudgeLine(reflection);
+    if (!line)
+        return null;
+    if (!(await consumeNudgeBudget()))
+        return null;
+    return line;
+}
 // ──────────────────────────────────────────────────────
 // Full-replace: disable OpenClaw's native memory search so MemoryRouter
 // owns the memory_search tool (no name conflict, no native embeddings 429).
@@ -299,37 +349,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 +522,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 +749,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,
@@ -649,7 +772,11 @@ If setting up MemoryRouter for another agent:
                         api.logger.info?.(`memoryrouter: injected ${data.memories_found || 0} memories (${data.memory_tokens || 0} tokens, ${elapsed}ms) [llm_input]`);
                         if (elapsed > 2000 && data.metrics)
                             log(`memoryrouter: prepare metrics ${JSON.stringify(data.metrics)}`);
-                        const wrapped = wrapForInjection(data.context);
+                        let contextText = data.context;
+                        const nudge = await maybeDebtNudge(data.reflection);
+                        if (nudge)
+                            contextText = `${contextText}\n\n${nudge}`;
+                        const wrapped = wrapForInjection(contextText);
                         return { appendSystemContext: wrapped };
                     }
                 }
@@ -728,6 +855,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,
@@ -752,7 +881,11 @@ If setting up MemoryRouter for another agent:
                         api.logger.info?.(`memoryrouter: injected ${data.memories_found || 0} memories (${data.memory_tokens || 0} tokens, ${elapsed}ms)`);
                         if (elapsed > 2000 && data.metrics)
                             log(`memoryrouter: prepare metrics ${JSON.stringify(data.metrics)}`);
-                        const wrapped = wrapForInjection(data.context);
+                        let contextText = data.context;
+                        const nudge = await maybeDebtNudge(data.reflection);
+                        if (nudge)
+                            contextText = `${contextText}\n\n${nudge}`;
+                        const wrapped = wrapForInjection(contextText);
                         return { appendSystemContext: wrapped };
                     }
                 }
@@ -834,6 +967,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,
@@ -877,6 +1012,17 @@ If setting up MemoryRouter for another agent:
                             query: { type: "string" },
                             maxResults: { type: "number" },
                             minScore: { type: "number" },
+                            tiers: {
+                                type: "array",
+                                items: { type: "integer", enum: [1, 2, 3] },
+                                description: "Restrict results to these memory tiers. 1 raw memories, 2 reflections, 3 high-level reflections. Omit to search all tiers blended.",
+                            },
+                            importance: {
+                                type: "integer",
+                                minimum: 1,
+                                maximum: 10,
+                                description: "Only return memories rated at least this important (1 to 10). Only reflections carry ratings, so this filters to tier 2 and 3 content.",
+                            },
                         },
                         required: ["query"],
                     },
@@ -887,8 +1033,20 @@ If setting up MemoryRouter for another agent:
                         if (!query)
                             return jsonToolResult({ results: [], error: "query required" });
                         const limit = typeof params.maxResults === "number" ? params.maxResults : 50;
+                        const tiers = Array.isArray(params.tiers)
+                            ? params.tiers.filter((t) => typeof t === "number" && [1, 2, 3].includes(t))
+                            : undefined;
+                        const importance = typeof params.importance === "number" && params.importance >= 1 && params.importance <= 10
+                            ? Math.floor(params.importance)
+                            : undefined;
                         try {
-                            const res = await searchMemory(endpoint, toolKey, { query, limit, embeddings });
+                            const res = await searchMemory(endpoint, toolKey, {
+                                query,
+                                limit,
+                                ...(tiers && tiers.length > 0 && { tiers }),
+                                ...(importance !== undefined && { importance }),
+                                embeddings,
+                            });
                             if (!res.ok) {
                                 const errBody = await res.text().catch(() => "");
                                 return jsonToolResult({ results: [], error: `Search failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
@@ -902,6 +1060,8 @@ If setting up MemoryRouter for another agent:
                                 role: m.role,
                                 window: m.window,
                                 date: m.timestampHuman,
+                                ...(m.tier !== undefined && { tier: m.tier }),
+                                ...(m.importance !== undefined && m.importance !== null && { importance: m.importance }),
                             }));
                             return jsonToolResult({
                                 results,
@@ -917,6 +1077,203 @@ If setting up MemoryRouter for another agent:
                     },
                 };
             });
+            // ==================================================================
+            // Tools: memory_reflect + memory_commit (consolidation, two-tool shape)
+            // Mirrors the MCP consolidate_memories / commit_reflections pair.
+            // Invariants: source_ids are stripped, the model never sees row IDs,
+            // and contract instructions are transmitted verbatim.
+            // ==================================================================
+            // memory_reflect: checkout wrapper (nothing is modified until memory_commit)
+            api.registerTool((ctx) => {
+                const toolKey = resolveKey(ctx);
+                return {
+                    label: "Memory Reflect",
+                    name: "memory_reflect",
+                    description: "Consolidate unconsolidated memories into reflections. Use when memory responses indicate consolidation is available, or when the user asks to organize or reflect on memory. Checks out a batch of memories under a 15 minute lease and returns their texts plus server instructions for writing reflection entries. Follow the instructions, then call memory_commit with the batch_id. Nothing is modified until commit.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            tier: {
+                                type: "integer",
+                                enum: [1, 2],
+                                description: "1 consolidates raw memories into reflections; 2 consolidates reflections into high-level reflections. Default 1.",
+                            },
+                            max_tokens: {
+                                type: "integer",
+                                minimum: 1000,
+                                description: "Token budget for the checked-out batch. Defaults to 50000. No connector-side cap.",
+                            },
+                        },
+                        required: [],
+                    },
+                    execute: async (_toolCallId, params) => {
+                        if (!toolKey)
+                            return jsonToolResult({ error: "No memory key configured for this agent" });
+                        const tier = params.tier === 2 ? 2 : 1;
+                        const maxTokens = typeof params.max_tokens === "number" && params.max_tokens >= 1000
+                            ? Math.floor(params.max_tokens)
+                            : 50000;
+                        try {
+                            const res = await consolidateCheckout(endpoint, toolKey, {
+                                tier: tier,
+                                max_tokens: maxTokens,
+                                ...(embeddings && { embeddings }),
+                            });
+                            if (!res.ok) {
+                                const errBody = await res.text().catch(() => "");
+                                return jsonToolResult({ error: `Checkout failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+                            }
+                            const data = await res.json();
+                            if (!data.batch_id) {
+                                return jsonToolResult({ batch_id: null, count: 0, message: "Nothing to consolidate at this tier right now." });
+                            }
+                            // Contract instructions are server-authored and passed through verbatim.
+                            // If neither contract form is present, refuse; never author a local prompt.
+                            const instructions = data.reflection_contract?.instructions ?? data.tier_definitions?.instruction;
+                            if (!instructions) {
+                                return jsonToolResult({ error: "Checkout response carried no reflection contract. Cannot consolidate without server instructions." });
+                            }
+                            // source_ids stripped: the model never sees memory row IDs.
+                            return jsonToolResult({
+                                batch_id: data.batch_id,
+                                lease_expires_at: data.lease_expires_at ?? null,
+                                count: data.count ?? 0,
+                                est_tokens: data.est_tokens ?? 0,
+                                instructions,
+                                memories: (data.memories || []).map((m) => ({ text: m.text, date: m.date })),
+                                message: `When your entries are ready, call memory_commit with batch_id ${data.batch_id} before ${data.lease_expires_at ?? "the lease expires"}.`,
+                            });
+                        }
+                        catch (err) {
+                            return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+                        }
+                    },
+                };
+            });
+            // memory_commit: commit wrapper (idempotent; 409 means the lease expired)
+            api.registerTool((ctx) => {
+                const toolKey = resolveKey(ctx);
+                return {
+                    label: "Memory Commit",
+                    name: "memory_commit",
+                    description: "Commit reflection entries for a batch checked out with memory_reflect. Each entry is standalone text plus an importance rating from 1 to 10. Safe to retry: committing the same batch twice reports success without duplicating.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            batch_id: { type: "string", description: "The batch_id returned by memory_reflect." },
+                            entries: {
+                                type: "array",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        text: { type: "string", description: "Standalone reflection prose, 1 to 8000 chars. No IDs or scores inline." },
+                                        importance: { type: "integer", minimum: 1, maximum: 10 },
+                                    },
+                                    required: ["text", "importance"],
+                                    additionalProperties: false,
+                                },
+                                minItems: 1,
+                                maxItems: 100,
+                            },
+                        },
+                        required: ["batch_id", "entries"],
+                    },
+                    execute: async (_toolCallId, params) => {
+                        if (!toolKey)
+                            return jsonToolResult({ error: "No memory key configured for this agent" });
+                        const batchId = typeof params.batch_id === "string" ? params.batch_id.trim() : "";
+                        if (!batchId)
+                            return jsonToolResult({ error: "batch_id required" });
+                        const rawEntries = Array.isArray(params.entries) ? params.entries : [];
+                        if (rawEntries.length < 1 || rawEntries.length > 100) {
+                            return jsonToolResult({ error: "entries must contain between 1 and 100 items" });
+                        }
+                        const entries = [];
+                        for (let i = 0; i < rawEntries.length; i++) {
+                            const e = rawEntries[i];
+                            if (!e || typeof e !== "object")
+                                return jsonToolResult({ error: `entry ${i + 1} is not an object` });
+                            const extraKeys = Object.keys(e).filter((k) => k !== "text" && k !== "importance");
+                            if (extraKeys.length > 0) {
+                                // Position-reference impossibility: entries are text plus importance only.
+                                return jsonToolResult({ error: `entry ${i + 1} has unsupported fields: ${extraKeys.join(", ")}. Entries are text plus importance only; coverage is always the whole batch.` });
+                            }
+                            const text = typeof e.text === "string" ? e.text : "";
+                            if (!text || text.length > 8000)
+                                return jsonToolResult({ error: `entry ${i + 1} text must be 1 to 8000 chars` });
+                            const importance = typeof e.importance === "number" && Number.isInteger(e.importance) && e.importance >= 1 && e.importance <= 10
+                                ? e.importance
+                                : null;
+                            if (importance === null)
+                                return jsonToolResult({ error: `entry ${i + 1} importance must be an integer 1 to 10` });
+                            entries.push({ text, importance });
+                        }
+                        try {
+                            const res = await commitReflections(endpoint, toolKey, {
+                                batch_id: batchId,
+                                entries,
+                                ...(embeddings && { embeddings }),
+                            });
+                            if (res.status === 409) {
+                                return jsonToolResult({ error: "lease expired, call memory_reflect again" });
+                            }
+                            if (!res.ok) {
+                                const errBody = await res.text().catch(() => "");
+                                return jsonToolResult({ error: `Commit failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+                            }
+                            const data = await res.json();
+                            // Created UUIDs dropped: the model never sees memory row IDs.
+                            return jsonToolResult({
+                                committed: data.committed ?? false,
+                                already_committed: data.already_committed ?? false,
+                                entries_created: data.created?.length ?? 0,
+                                sources_consolidated: data.sources_consolidated ?? 0,
+                                debt: data.reflection?.suggestion ?? null,
+                            });
+                        }
+                        catch (err) {
+                            return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+                        }
+                    },
+                };
+            });
+            // memory_inspect: read-only lineage drill-down (curation surface, ids allowed)
+            api.registerTool((ctx) => {
+                const toolKey = resolveKey(ctx);
+                return {
+                    label: "Memory Inspect",
+                    name: "memory_inspect",
+                    description: "Inspect a memory's consolidation lineage by memory_id: its tier, the batch it came from, the sources it consolidated, and what it was consolidated into. Read-only.",
+                    parameters: {
+                        type: "object",
+                        properties: {
+                            memory_id: { type: "string", description: "The memory id to inspect." },
+                        },
+                        required: ["memory_id"],
+                    },
+                    execute: async (_toolCallId, params) => {
+                        if (!toolKey)
+                            return jsonToolResult({ error: "No memory key configured for this agent" });
+                        const memoryId = typeof params.memory_id === "string" ? params.memory_id.trim() : "";
+                        if (!memoryId)
+                            return jsonToolResult({ error: "memory_id required" });
+                        try {
+                            const res = await inspectMemory(endpoint, toolKey, {
+                                memory_id: memoryId,
+                                ...(embeddings && { embeddings }),
+                            });
+                            if (!res.ok) {
+                                const errBody = await res.text().catch(() => "");
+                                return jsonToolResult({ error: `Inspect failed: HTTP ${res.status}`, details: errBody.slice(0, 200) });
+                            }
+                            return jsonToolResult(await res.json());
+                        }
+                        catch (err) {
+                            return jsonToolResult({ error: err instanceof Error ? err.message : String(err) });
+                        }
+                    },
+                };
+            });
             // memory_get — exact copy of OpenClaw's implementation (pure local file read)
             api.registerTool((ctx) => {
                 const workspaceDir = ctx.workspaceDir || "";
@@ -971,8 +1328,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 +1369,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).");
@@ -1188,7 +1549,9 @@ If setting up MemoryRouter for another agent:
                 }
             });
             mr.command("delete")
-                .description("Clear all memories from vault")
+                .description("Clear all memories from vault, or delete specific memories with --ids")
+                .option("--ids <ids>", "Comma-separated memory ids to delete (instead of the whole vault)")
+                .option("--yes", "Confirm deletion (required with --ids)")
                 .option("--key <key>", "Override memory key (for subagent vaults)")
                 .action(async (opts) => {
                 const effectiveKey = opts.key || memoryKey;
@@ -1196,6 +1559,34 @@ If setting up MemoryRouter for another agent:
                     console.error("Not configured. Run: openclaw mr <key> or pass --key <key>");
                     return;
                 }
+                if (opts.ids) {
+                    const ids = opts.ids.split(",").map((s) => s.trim()).filter(Boolean);
+                    if (ids.length === 0) {
+                        console.error("No ids provided.");
+                        return;
+                    }
+                    console.log(`The following ${ids.length} memor${ids.length === 1 ? "y" : "ies"} will be PERMANENTLY deleted:`);
+                    for (const id of ids)
+                        console.log(`  • ${id}`);
+                    if (!opts.yes) {
+                        console.error("\nRefusing to delete without --yes. Re-run with --yes to confirm.");
+                        return;
+                    }
+                    try {
+                        const res = await deleteMemoryIds(endpoint, effectiveKey, { ids, ...(embeddings && { embeddings }) });
+                        if (!res.ok) {
+                            const errBody = await res.text().catch(() => "");
+                            console.error(`Delete failed: HTTP ${res.status}${errBody ? `: ${errBody.slice(0, 200)}` : ""}`);
+                            return;
+                        }
+                        const data = (await res.json());
+                        console.log(`✓ Deleted ${data.deleted ?? 0} of ${data.requested ?? ids.length} (not found: ${data.not_found ?? 0})`);
+                    }
+                    catch (err) {
+                        console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    return;
+                }
                 try {
                     const res = await deleteMemories(endpoint, effectiveKey, embeddings);
                     const data = (await res.json());
@@ -1206,6 +1597,46 @@ If setting up MemoryRouter for another agent:
                     console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
                 }
             });
+            mr.command("reflect")
+                .description("Show reflection debt status (consolidation runs via the agent's memory_reflect tool)")
+                .option("--key <key>", "Override memory key (for subagent vaults)")
+                .action(async (opts) => {
+                const effectiveKey = opts.key || memoryKey;
+                if (!effectiveKey) {
+                    console.error("Not configured. Run: openclaw mr <key> or pass --key <key>");
+                    return;
+                }
+                try {
+                    // Debt probe: an empty-window date-search returns the reflection
+                    // debt block with zero results and zero retrieval billing.
+                    const from = new Date(Date.now() - 1000).toISOString();
+                    const res = await dateSearch(endpoint, effectiveKey, { from, max_tokens: 1000, ...(embeddings && { embeddings }) });
+                    if (!res.ok) {
+                        const errBody = await res.text().catch(() => "");
+                        console.error(`Debt check failed: HTTP ${res.status}${errBody ? `: ${errBody.slice(0, 200)}` : ""}`);
+                        return;
+                    }
+                    const data = (await res.json());
+                    const debt = data.reflection;
+                    console.log("Reflection Debt");
+                    console.log("───────────────────────────");
+                    const raw = debt?.unconsolidated?.raw;
+                    const tier2 = debt?.unconsolidated?.tier2;
+                    console.log(`Raw unconsolidated:    ${raw?.units ?? 0} memories (~${raw?.est_tokens ?? 0} tokens)`);
+                    console.log(`Tier 2 unconsolidated: ${tier2?.count ?? 0} reflections (~${tier2?.est_tokens ?? 0} tokens)`);
+                    console.log(`Threshold:             ${debt?.threshold_tokens ?? 0} tokens`);
+                    if (debt?.suggestion) {
+                        console.log(`\nStatus: ${debt.suggestion}`);
+                        console.log("Consolidation runs through the agent. Ask your agent to consolidate memories (it uses the memory_reflect and memory_commit tools).");
+                    }
+                    else {
+                        console.log("\nStatus: nothing to consolidate right now.");
+                    }
+                }
+                catch (err) {
+                    console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            });
         }, { commands: ["mr"] });
         // ==================================================================
         // Service
@@ -1215,17 +1646,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");
             },
         });