mr-memory 3.7.10 → 3.9.0

package/index.ts

@@ -9,7 +9,7 @@
  */
 
 import { readFile, readdir, stat, 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 path from "node:path";
 import os from "node:os";
@@ -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;
@@ -55,6 +65,27 @@ function jsonToolResult(payload: unknown) {
   return { content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }], details: payload };
 }
 
+// ── Reflection debt nudge (rate-limited, one line, appended to prepare injections)
+type ReflectionDebt = {
+  suggestion?: string | null;
+  unconsolidated?: {
+    raw?: { units?: number; est_tokens?: number };
+    tier2?: { count?: number; importance?: number; est_tokens?: number };
+  };
+  threshold_tokens?: number;
+};
+
+const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1000; // at most one nudge per 24h
+
+function buildDebtNudgeLine(reflection: ReflectionDebt | undefined): string | null {
+  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: unknown): boolean {
   return Boolean(err && typeof err === "object" && "code" in err && (err as any).code === "ENOENT");
@@ -282,6 +313,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;
 };
 
 // ──────────────────────────────────────────────────────
@@ -320,6 +354,36 @@ async function writeOpenClawConfigFile(config: JsonObject): Promise<void> {
 `, "utf8");
 }
 
+// Nudge rate-limit state lives beside the OpenClaw config so it survives restarts
+// without churning the main config file.
+function nudgeStatePath(): string {
+  return join(dirname(openClawConfigPath()), "mr-memory-state.json");
+}
+
+async function consumeNudgeBudget(): Promise<boolean> {
+  const now = Date.now();
+  let state: { lastNudgeAt?: number } = {};
+  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: ReflectionDebt | undefined): Promise<string | null> {
+  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).
@@ -501,7 +565,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 +606,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 +794,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,
@@ -706,13 +819,17 @@ If setting up MemoryRouter for another agent:
             tokens_billed?: number;
             memory_tokens?: number;
             metrics?: Record<string, unknown>;
+            reflection?: ReflectionDebt;
           };
 
           if (data.context) {
             const elapsed = Date.now() - startMs;
             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 };
           }
         } catch {
@@ -795,6 +912,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,
@@ -820,13 +940,17 @@ If setting up MemoryRouter for another agent:
             tokens_billed?: number;
             memory_tokens?: number;
             metrics?: Record<string, unknown>;
+            reflection?: ReflectionDebt;
           };
 
           if (data.context) {
             const elapsed = Date.now() - startMs;
             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 };
           }
         } catch (err) {
@@ -914,6 +1038,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,
@@ -957,6 +1084,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"],
           } as any,
@@ -965,14 +1103,26 @@ If setting up MemoryRouter for another agent:
             const query = typeof params.query === "string" ? params.query.trim() : "";
             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 as unknown[]).filter((t): t is number => 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) });
               }
               const data = await res.json() as {
-                memories?: Array<{ content: string; score: number; role: string; window: string; timestampHuman: string }>;
+                memories?: Array<{ content: string; score: number; role: string; window: string; timestampHuman: string; tier?: number; importance?: number }>;
                 totalMemories?: number;
                 tokenCount?: number;
               };
@@ -984,6 +1134,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,
@@ -999,6 +1151,211 @@ 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: [],
+          } as any,
+          execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+            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 as 1 | 2,
+                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() as {
+                batch_id?: string | null;
+                tier?: number;
+                count?: number;
+                est_tokens?: number;
+                lease_expires_at?: string | null;
+                memories?: Array<{ text: string; date: string }>;
+                reflection_contract?: { version?: number; instructions?: string };
+                tier_definitions?: { target_tier?: number; instruction?: string };
+              };
+              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"],
+          } as any,
+          execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+            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 as Array<Record<string, unknown>> : [];
+            if (rawEntries.length < 1 || rawEntries.length > 100) {
+              return jsonToolResult({ error: "entries must contain between 1 and 100 items" });
+            }
+            const entries: Array<{ text: string; importance: number }> = [];
+            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() as {
+                committed?: boolean;
+                already_committed?: boolean;
+                created?: Array<{ id: string; importance: number }>;
+                sources_consolidated?: number;
+                reflection?: ReflectionDebt;
+              };
+              // 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"],
+          } as any,
+          execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+            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 || "";
@@ -1285,11 +1642,36 @@ 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: { key?: string }) => {
+          .action(async (opts: { ids?: string; yes?: boolean; key?: string }) => {
             const effectiveKey = opts.key || memoryKey;
             if (!effectiveKey) { 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()) as { requested?: number; deleted?: number; not_found?: number };
+                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()) as { message?: string };
@@ -1299,6 +1681,42 @@ 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: { key?: string }) => {
+            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()) as { reflection?: ReflectionDebt };
+              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"] },
     );
@@ -1311,17 +1729,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");
       },
     });