mr-memory 3.10.0 → 3.11.1

package/README.md

@@ -69,6 +69,22 @@ Tune it with `keepWarmMs` (milliseconds, default `180000`; `0` disables warmup p
 { "plugins": { "entries": { "mr-memory": { "config": { "keepWarmMs": 180000 } } } } }
 ```
 
+### Automatic consolidation (default on)
+
+MemoryRouter's Reflection Hierarchy consolidates raw memories into higher-tier reflections. The server tracks consolidation debt per vault; when a retrieval response reports debt above the server's threshold, this plugin consolidates automatically:
+
+- It starts a dedicated isolated agent turn through the OpenClaw gateway (a background subagent session, never your main conversation) whose only instruction is to call the plugin's `memory_reflect` and `memory_commit` tools. Your agent's model writes the reflections, so the inference is your own model spend; MemoryRouter never calls a provider.
+- At most 3 batches per trigger, with a fresh debt check between batches; the run stops when debt drops below the threshold. The threshold always comes from the server response.
+- A machine-wide lockfile (`~/.memoryrouter/consolidate.lock`, stale after 20 minutes) prevents double-firing across sessions and across other MemoryRouter connectors on the same machine, and a 30 minute cooldown follows each completed run.
+- The consolidation session is excluded from memory capture/injection and its transcript is deleted afterward. Failures never surface in your conversation; everything is logged to `~/.memoryrouter/consolidate.log`.
+- MemoryRouter bills the consolidation checkout/commit tokens at the normal 1x raw rate.
+
+Opt out with `"autoConsolidate": false` in the plugin config (restart the gateway to apply). The in-context consolidation hint and the `memory_reflect`/`memory_commit` agent tools keep working; only the automatic background trigger is disabled:
+
+```json
+{ "plugins": { "entries": { "mr-memory": { "config": { "autoConsolidate": false } } } } }
+```
+
 ## Config
 
 After `openclaw mr <key>`, config is stored at:

package/auto-consolidate.js

@@ -0,0 +1,296 @@
+/**
+ * Automatic threshold-activated consolidation for the OpenClaw plugin.
+ *
+ * The injected suggestion nudge depends on main-session model discipline,
+ * which is a proven failure mode: the model can ignore it forever. This
+ * module instead drives consolidation deterministically from plugin code
+ * running inside the gateway, using the plugin runtime's subagent capability
+ * (api.runtime.subagent.run), which executes a dedicated isolated agent turn.
+ * That isolated turn is OpenClaw's equivalent of the headless model runs the
+ * claude-code and codex connectors use (claude -p / codex exec): the host's
+ * own model does the reflecting in a session whose only instruction is to
+ * consolidate, the user pays their own inference, and MemoryRouter never
+ * calls a provider.
+ *
+ * Reliability rails (shared with the other MemoryRouter connectors on this
+ * machine via the same files):
+ * - Lockfile ~/.memoryrouter/consolidate.lock (pid + timestamp, stale after
+ *   20 minutes) so concurrent sessions/connectors never double-fire.
+ * - Bounded: at most 3 batches per trigger, re-checking debt via the API
+ *   between batches and stopping once the server reports no suggestion.
+ * - Cooldown: no re-trigger within 30 minutes of the last completed run,
+ *   nor within 10 minutes of the last attempt.
+ * - The threshold always comes from the server's reflection debt block;
+ *   nothing is hardcoded client-side.
+ * - Failures are silent to the user's session and logged to
+ *   ~/.memoryrouter/consolidate.log.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { dateSearch } from "./memoryrouter-api.js";
+export const AUTO_SESSION_MARKER = "mrconsolidate";
+export const LOCK_STALE_MS = 20 * 60 * 1000;
+export const COOLDOWN_MS = 30 * 60 * 1000;
+export const ATTEMPT_COOLDOWN_MS = 10 * 60 * 1000;
+export const MAX_BATCHES_PER_TRIGGER = 3;
+const RUN_TIMEOUT_MS = 12 * 60 * 1000; // inside the server's 15 minute lease
+export function autoDir(env = process.env) {
+    return env.MEMORYROUTER_AUTO_DIR || path.join(os.homedir(), ".memoryrouter");
+}
+function lockPath(env) { return path.join(autoDir(env), "consolidate.lock"); }
+function statePath(env) { return path.join(autoDir(env), "consolidate-state.json"); }
+function logPath(env) { return path.join(autoDir(env), "consolidate.log"); }
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+export function appendAutoLog(line, env = process.env) {
+    try {
+        ensureDir(autoDir(env));
+        const file = logPath(env);
+        try {
+            if (fs.statSync(file).size > 1024 * 1024)
+                fs.renameSync(file, `${file}.1`);
+        }
+        catch { /* new file */ }
+        fs.appendFileSync(file, `[${new Date().toISOString()}] ${line}\n`, { mode: 0o600 });
+    }
+    catch { /* logging never throws */ }
+}
+export function readAutoState(env = process.env) {
+    try {
+        return JSON.parse(fs.readFileSync(statePath(env), "utf8")) || {};
+    }
+    catch {
+        return {};
+    }
+}
+export function writeAutoState(patch, env = process.env) {
+    try {
+        ensureDir(autoDir(env));
+        const next = { ...readAutoState(env), ...patch };
+        fs.writeFileSync(statePath(env), JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    }
+    catch { /* state is best-effort */ }
+}
+export function lockFresh(env = process.env, now = Date.now()) {
+    try {
+        const info = JSON.parse(fs.readFileSync(lockPath(env), "utf8"));
+        return now - Number(info.at) <= LOCK_STALE_MS;
+    }
+    catch (err) {
+        if (err?.code === "ENOENT")
+            return false;
+        try {
+            return now - fs.statSync(lockPath(env)).mtimeMs <= LOCK_STALE_MS;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export function acquireLock(env = process.env, now = Date.now()) {
+    ensureDir(autoDir(env));
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = fs.openSync(lockPath(env), "wx", 0o600);
+            fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, at: now }) + "\n");
+            fs.closeSync(fd);
+            return true;
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                return false;
+            if (lockFresh(env, now))
+                return false;
+            try {
+                fs.unlinkSync(lockPath(env));
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    return false;
+}
+export function releaseLock(env = process.env) {
+    try {
+        fs.unlinkSync(lockPath(env));
+    }
+    catch { /* already gone */ }
+}
+export function cooldownActive(env = process.env, now = Date.now()) {
+    const state = readAutoState(env);
+    const completed = Number(state.lastCompletedAt);
+    if (Number.isFinite(completed) && now - completed < COOLDOWN_MS)
+        return true;
+    const attempted = Number(state.lastAttemptAt);
+    if (Number.isFinite(attempted) && now - attempted < ATTEMPT_COOLDOWN_MS)
+        return true;
+    return false;
+}
+/** Tier choice comes entirely from the server's debt block. */
+export function pickTier(debt) {
+    const threshold = Number(debt?.threshold_importance);
+    const rawEquiv = Number(debt?.unconsolidated?.raw?.importance_equiv);
+    const tier2 = Number(debt?.unconsolidated?.tier2?.importance);
+    if (Number.isFinite(threshold) && threshold > 0) {
+        if (Number.isFinite(rawEquiv) && rawEquiv >= threshold)
+            return 1;
+        if (Number.isFinite(tier2) && tier2 >= threshold)
+            return 2;
+    }
+    return /tier 2/i.test(String(debt?.suggestion || "")) ? 2 : 1;
+}
+/** True for sessions created by this module; hooks skip them entirely. */
+export function isAutoConsolidationSession(sessionKey) {
+    return typeof sessionKey === "string" && sessionKey.includes(AUTO_SESSION_MARKER);
+}
+async function probeDebt(endpoint, key, embeddings) {
+    // Sanctioned zero-billing debt read: an empty-window date-search returns
+    // the reflection debt block with zero results.
+    const from = new Date(Date.now() - 1000).toISOString();
+    const res = await dateSearch(endpoint, key, { from, max_tokens: 1000, ...(embeddings && { embeddings }) });
+    if (!res.ok)
+        return null;
+    const data = await res.json().catch(() => null);
+    return data?.reflection ?? null;
+}
+// The isolated turn's message is connector transport mechanics (which tools
+// to call, in what order). Every reflection semantic comes from the server
+// contract that the memory_reflect tool returns verbatim.
+function consolidationMessage(tier) {
+    return [
+        "MemoryRouter automatic consolidation run. Complete exactly one consolidation batch:",
+        `1. Call the memory_reflect tool with tier: ${tier}.`,
+        "2. If it returns batch_id null or an error, reply \"nothing to consolidate\" and stop.",
+        "3. Otherwise follow the instructions it returns to write reflection entries, then call memory_commit with that batch_id and your entries.",
+        "4. Reply \"done\" once the commit succeeds.",
+        "Do not call any other tools. Do not check out more than one batch.",
+    ].join("\n");
+}
+/**
+ * The full bounded run: lock -> up to 3 (probe debt -> isolated agent turn)
+ * cycles -> record completion -> release. Never throws.
+ */
+export async function runAutoConsolidate(options) {
+    const env = options.env || process.env;
+    const now = options.now || (() => Date.now());
+    const log = options.log || ((line) => appendAutoLog(line, env));
+    const bound = Math.min(options.maxBatches ?? MAX_BATCHES_PER_TRIGGER, MAX_BATCHES_PER_TRIGGER);
+    if (cooldownActive(env, now())) {
+        log("auto: cooldown active; skipping");
+        return { committed: 0, reason: "cooldown" };
+    }
+    if (!acquireLock(env, now())) {
+        log("auto: another consolidation run holds the lock; skipping");
+        return { committed: 0, reason: "locked" };
+    }
+    writeAutoState({ lastAttemptAt: now() }, env);
+    let committed = 0;
+    try {
+        for (let batch = 0; batch < bound; batch++) {
+            let debt = null;
+            try {
+                debt = await probeDebt(options.endpoint, options.key, options.embeddings);
+            }
+            catch (err) {
+                log(`auto: debt probe failed: ${err?.message}`);
+                break;
+            }
+            if (!debt || !debt.suggestion) {
+                log(`auto: debt below threshold after ${committed} batch(es); stopping`);
+                break;
+            }
+            const tier = pickTier(debt);
+            const sessionKey = `agent:${options.agentId}:subagent:${AUTO_SESSION_MARKER}-${randomUUID()}`;
+            log(`auto: batch ${batch + 1}/${bound} starting (tier ${tier}; ${debt.suggestion})`);
+            let status = "error";
+            try {
+                const { runId } = await options.runtime.run({
+                    sessionKey,
+                    message: consolidationMessage(tier),
+                    deliver: false,
+                    // The gateway's `agent` method requires idempotencyKey on some
+                    // deployments (and auto-generates it on others); always send a
+                    // fresh one per run attempt so both validate.
+                    idempotencyKey: randomUUID(),
+                });
+                const waited = await options.runtime.waitForRun({ runId, timeoutMs: RUN_TIMEOUT_MS });
+                status = waited.status;
+                if (waited.status !== "ok")
+                    log(`auto: isolated run ${waited.status}${waited.error ? `: ${waited.error}` : ""}`);
+            }
+            catch (err) {
+                log(`auto: isolated run failed: ${err?.message}`);
+                break;
+            }
+            finally {
+                try {
+                    await options.runtime.deleteSession({ sessionKey, deleteTranscript: true });
+                }
+                catch { /* cleanup best-effort */ }
+            }
+            if (status !== "ok")
+                break;
+            // Verify a commit actually happened: the server-side debt must move.
+            let after = null;
+            try {
+                after = await probeDebt(options.endpoint, options.key, options.embeddings);
+            }
+            catch { /* treated as no movement */ }
+            const before = JSON.stringify(debt.unconsolidated ?? {});
+            const current = JSON.stringify(after?.unconsolidated ?? {});
+            if (after && before !== current) {
+                committed++;
+            }
+            else {
+                log("auto: run finished but debt did not move; stopping (no commit detected)");
+                break;
+            }
+        }
+        if (committed > 0) {
+            writeAutoState({ lastCompletedAt: now() }, env);
+            log(`auto: run complete, ${committed} batch(es) committed`);
+        }
+    }
+    finally {
+        releaseLock(env);
+    }
+    return { committed };
+}
+/**
+ * Trigger check called from the hook path with the reflection debt block the
+ * prepare response already carried. Fire-and-forget; never blocks the hook,
+ * never throws.
+ */
+export function maybeTriggerAutoConsolidate(reflection, options) {
+    const env = options.env || process.env;
+    try {
+        if (env.MEMORYROUTER_DISABLE === "1")
+            return false;
+        if (options.autoConsolidate === false)
+            return false;
+        if (!reflection || !reflection.suggestion)
+            return false;
+        if (isAutoConsolidationSession(options.sessionKey))
+            return false;
+        const now = options.now ? options.now() : Date.now();
+        if (cooldownActive(env, now))
+            return false;
+        if (lockFresh(env, now))
+            return false;
+        if (!options.runtime || typeof options.runtime.run !== "function")
+            return false;
+        appendAutoLog(`trigger: starting auto consolidation (suggestion: ${reflection.suggestion})`, env);
+        void runAutoConsolidate(options).catch((err) => {
+            appendAutoLog(`auto: unexpected error: ${err?.message}`, env);
+        });
+        return true;
+    }
+    catch (err) {
+        appendAutoLog(`trigger error: ${err?.message}`, env);
+        return false;
+    }
+}

package/auto-consolidate.ts

@@ -0,0 +1,283 @@
+/**
+ * Automatic threshold-activated consolidation for the OpenClaw plugin.
+ *
+ * The injected suggestion nudge depends on main-session model discipline,
+ * which is a proven failure mode: the model can ignore it forever. This
+ * module instead drives consolidation deterministically from plugin code
+ * running inside the gateway, using the plugin runtime's subagent capability
+ * (api.runtime.subagent.run), which executes a dedicated isolated agent turn.
+ * That isolated turn is OpenClaw's equivalent of the headless model runs the
+ * claude-code and codex connectors use (claude -p / codex exec): the host's
+ * own model does the reflecting in a session whose only instruction is to
+ * consolidate, the user pays their own inference, and MemoryRouter never
+ * calls a provider.
+ *
+ * Reliability rails (shared with the other MemoryRouter connectors on this
+ * machine via the same files):
+ * - Lockfile ~/.memoryrouter/consolidate.lock (pid + timestamp, stale after
+ *   20 minutes) so concurrent sessions/connectors never double-fire.
+ * - Bounded: at most 3 batches per trigger, re-checking debt via the API
+ *   between batches and stopping once the server reports no suggestion.
+ * - Cooldown: no re-trigger within 30 minutes of the last completed run,
+ *   nor within 10 minutes of the last attempt.
+ * - The threshold always comes from the server's reflection debt block;
+ *   nothing is hardcoded client-side.
+ * - Failures are silent to the user's session and logged to
+ *   ~/.memoryrouter/consolidate.log.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { dateSearch } from "./memoryrouter-api.js";
+
+export const AUTO_SESSION_MARKER = "mrconsolidate";
+export const LOCK_STALE_MS = 20 * 60 * 1000;
+export const COOLDOWN_MS = 30 * 60 * 1000;
+export const ATTEMPT_COOLDOWN_MS = 10 * 60 * 1000;
+export const MAX_BATCHES_PER_TRIGGER = 3;
+const RUN_TIMEOUT_MS = 12 * 60 * 1000; // inside the server's 15 minute lease
+
+export type ReflectionDebtBlock = {
+  suggestion?: string | null;
+  threshold_importance?: number;
+  unconsolidated?: {
+    raw?: { units?: number; est_tokens?: number; importance_equiv?: number };
+    tier2?: { count?: number; importance?: number; est_tokens?: number };
+  };
+};
+
+type SubagentRuntime = {
+  run: (params: { sessionKey: string; message: string; deliver?: boolean; lane?: string; idempotencyKey?: string }) => Promise<{ runId: string }>;
+  waitForRun: (params: { runId: string; timeoutMs?: number }) => Promise<{ status: string; error?: string }>;
+  deleteSession: (params: { sessionKey: string; deleteTranscript?: boolean }) => Promise<void>;
+};
+
+export function autoDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env.MEMORYROUTER_AUTO_DIR || path.join(os.homedir(), ".memoryrouter");
+}
+
+function lockPath(env?: NodeJS.ProcessEnv): string { return path.join(autoDir(env), "consolidate.lock"); }
+function statePath(env?: NodeJS.ProcessEnv): string { return path.join(autoDir(env), "consolidate-state.json"); }
+function logPath(env?: NodeJS.ProcessEnv): string { return path.join(autoDir(env), "consolidate.log"); }
+
+function ensureDir(dir: string): void {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+
+export function appendAutoLog(line: string, env: NodeJS.ProcessEnv = process.env): void {
+  try {
+    ensureDir(autoDir(env));
+    const file = logPath(env);
+    try {
+      if (fs.statSync(file).size > 1024 * 1024) fs.renameSync(file, `${file}.1`);
+    } catch { /* new file */ }
+    fs.appendFileSync(file, `[${new Date().toISOString()}] ${line}\n`, { mode: 0o600 });
+  } catch { /* logging never throws */ }
+}
+
+export function readAutoState(env: NodeJS.ProcessEnv = process.env): Record<string, unknown> {
+  try { return JSON.parse(fs.readFileSync(statePath(env), "utf8")) || {}; } catch { return {}; }
+}
+
+export function writeAutoState(patch: Record<string, unknown>, env: NodeJS.ProcessEnv = process.env): void {
+  try {
+    ensureDir(autoDir(env));
+    const next = { ...readAutoState(env), ...patch };
+    fs.writeFileSync(statePath(env), JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+  } catch { /* state is best-effort */ }
+}
+
+export function lockFresh(env: NodeJS.ProcessEnv = process.env, now: number = Date.now()): boolean {
+  try {
+    const info = JSON.parse(fs.readFileSync(lockPath(env), "utf8"));
+    return now - Number(info.at) <= LOCK_STALE_MS;
+  } catch (err: any) {
+    if (err?.code === "ENOENT") return false;
+    try { return now - fs.statSync(lockPath(env)).mtimeMs <= LOCK_STALE_MS; } catch { return false; }
+  }
+}
+
+export function acquireLock(env: NodeJS.ProcessEnv = process.env, now: number = Date.now()): boolean {
+  ensureDir(autoDir(env));
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = fs.openSync(lockPath(env), "wx", 0o600);
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, at: now }) + "\n");
+      fs.closeSync(fd);
+      return true;
+    } catch (err: any) {
+      if (err?.code !== "EEXIST") return false;
+      if (lockFresh(env, now)) return false;
+      try { fs.unlinkSync(lockPath(env)); } catch { return false; }
+    }
+  }
+  return false;
+}
+
+export function releaseLock(env: NodeJS.ProcessEnv = process.env): void {
+  try { fs.unlinkSync(lockPath(env)); } catch { /* already gone */ }
+}
+
+export function cooldownActive(env: NodeJS.ProcessEnv = process.env, now: number = Date.now()): boolean {
+  const state = readAutoState(env);
+  const completed = Number(state.lastCompletedAt);
+  if (Number.isFinite(completed) && now - completed < COOLDOWN_MS) return true;
+  const attempted = Number(state.lastAttemptAt);
+  if (Number.isFinite(attempted) && now - attempted < ATTEMPT_COOLDOWN_MS) return true;
+  return false;
+}
+
+/** Tier choice comes entirely from the server's debt block. */
+export function pickTier(debt: ReflectionDebtBlock | null | undefined): 1 | 2 {
+  const threshold = Number(debt?.threshold_importance);
+  const rawEquiv = Number(debt?.unconsolidated?.raw?.importance_equiv);
+  const tier2 = Number(debt?.unconsolidated?.tier2?.importance);
+  if (Number.isFinite(threshold) && threshold > 0) {
+    if (Number.isFinite(rawEquiv) && rawEquiv >= threshold) return 1;
+    if (Number.isFinite(tier2) && tier2 >= threshold) return 2;
+  }
+  return /tier 2/i.test(String(debt?.suggestion || "")) ? 2 : 1;
+}
+
+/** True for sessions created by this module; hooks skip them entirely. */
+export function isAutoConsolidationSession(sessionKey: string | undefined): boolean {
+  return typeof sessionKey === "string" && sessionKey.includes(AUTO_SESSION_MARKER);
+}
+
+async function probeDebt(endpoint: string, key: string, embeddings?: string): Promise<ReflectionDebtBlock | null> {
+  // Sanctioned zero-billing debt read: an empty-window date-search returns
+  // the reflection debt block with zero results.
+  const from = new Date(Date.now() - 1000).toISOString();
+  const res = await dateSearch(endpoint, key, { from, max_tokens: 1000, ...(embeddings && { embeddings }) });
+  if (!res.ok) return null;
+  const data = await res.json().catch(() => null) as { reflection?: ReflectionDebtBlock } | null;
+  return data?.reflection ?? null;
+}
+
+// The isolated turn's message is connector transport mechanics (which tools
+// to call, in what order). Every reflection semantic comes from the server
+// contract that the memory_reflect tool returns verbatim.
+function consolidationMessage(tier: 1 | 2): string {
+  return [
+    "MemoryRouter automatic consolidation run. Complete exactly one consolidation batch:",
+    `1. Call the memory_reflect tool with tier: ${tier}.`,
+    "2. If it returns batch_id null or an error, reply \"nothing to consolidate\" and stop.",
+    "3. Otherwise follow the instructions it returns to write reflection entries, then call memory_commit with that batch_id and your entries.",
+    "4. Reply \"done\" once the commit succeeds.",
+    "Do not call any other tools. Do not check out more than one batch.",
+  ].join("\n");
+}
+
+export type AutoConsolidateOptions = {
+  runtime: SubagentRuntime;
+  agentId: string;
+  endpoint: string;
+  key: string;
+  embeddings?: string;
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+  log?: (line: string) => void;
+  maxBatches?: number;
+};
+
+/**
+ * The full bounded run: lock -> up to 3 (probe debt -> isolated agent turn)
+ * cycles -> record completion -> release. Never throws.
+ */
+export async function runAutoConsolidate(options: AutoConsolidateOptions): Promise<{ committed: number; reason?: string }> {
+  const env = options.env || process.env;
+  const now = options.now || (() => Date.now());
+  const log = options.log || ((line: string) => appendAutoLog(line, env));
+  const bound = Math.min(options.maxBatches ?? MAX_BATCHES_PER_TRIGGER, MAX_BATCHES_PER_TRIGGER);
+
+  if (cooldownActive(env, now())) { log("auto: cooldown active; skipping"); return { committed: 0, reason: "cooldown" }; }
+  if (!acquireLock(env, now())) { log("auto: another consolidation run holds the lock; skipping"); return { committed: 0, reason: "locked" }; }
+
+  writeAutoState({ lastAttemptAt: now() }, env);
+  let committed = 0;
+  try {
+    for (let batch = 0; batch < bound; batch++) {
+      let debt: ReflectionDebtBlock | null = null;
+      try { debt = await probeDebt(options.endpoint, options.key, options.embeddings); }
+      catch (err: any) { log(`auto: debt probe failed: ${err?.message}`); break; }
+      if (!debt || !debt.suggestion) {
+        log(`auto: debt below threshold after ${committed} batch(es); stopping`);
+        break;
+      }
+      const tier = pickTier(debt);
+      const sessionKey = `agent:${options.agentId}:subagent:${AUTO_SESSION_MARKER}-${randomUUID()}`;
+      log(`auto: batch ${batch + 1}/${bound} starting (tier ${tier}; ${debt.suggestion})`);
+      let status = "error";
+      try {
+        const { runId } = await options.runtime.run({
+          sessionKey,
+          message: consolidationMessage(tier),
+          deliver: false,
+          // The gateway's `agent` method requires idempotencyKey on some
+          // deployments (and auto-generates it on others); always send a
+          // fresh one per run attempt so both validate.
+          idempotencyKey: randomUUID(),
+        });
+        const waited = await options.runtime.waitForRun({ runId, timeoutMs: RUN_TIMEOUT_MS });
+        status = waited.status;
+        if (waited.status !== "ok") log(`auto: isolated run ${waited.status}${waited.error ? `: ${waited.error}` : ""}`);
+      } catch (err: any) {
+        log(`auto: isolated run failed: ${err?.message}`);
+        break;
+      } finally {
+        try { await options.runtime.deleteSession({ sessionKey, deleteTranscript: true }); } catch { /* cleanup best-effort */ }
+      }
+      if (status !== "ok") break;
+      // Verify a commit actually happened: the server-side debt must move.
+      let after: ReflectionDebtBlock | null = null;
+      try { after = await probeDebt(options.endpoint, options.key, options.embeddings); } catch { /* treated as no movement */ }
+      const before = JSON.stringify(debt.unconsolidated ?? {});
+      const current = JSON.stringify(after?.unconsolidated ?? {});
+      if (after && before !== current) {
+        committed++;
+      } else {
+        log("auto: run finished but debt did not move; stopping (no commit detected)");
+        break;
+      }
+    }
+    if (committed > 0) {
+      writeAutoState({ lastCompletedAt: now() }, env);
+      log(`auto: run complete, ${committed} batch(es) committed`);
+    }
+  } finally {
+    releaseLock(env);
+  }
+  return { committed };
+}
+
+/**
+ * Trigger check called from the hook path with the reflection debt block the
+ * prepare response already carried. Fire-and-forget; never blocks the hook,
+ * never throws.
+ */
+export function maybeTriggerAutoConsolidate(
+  reflection: ReflectionDebtBlock | null | undefined,
+  options: Omit<AutoConsolidateOptions, "now"> & { autoConsolidate?: boolean; sessionKey?: string; now?: () => number },
+): boolean {
+  const env = options.env || process.env;
+  try {
+    if (env.MEMORYROUTER_DISABLE === "1") return false;
+    if (options.autoConsolidate === false) return false;
+    if (!reflection || !reflection.suggestion) return false;
+    if (isAutoConsolidationSession(options.sessionKey)) return false;
+    const now = options.now ? options.now() : Date.now();
+    if (cooldownActive(env, now)) return false;
+    if (lockFresh(env, now)) return false;
+    if (!options.runtime || typeof options.runtime.run !== "function") return false;
+    appendAutoLog(`trigger: starting auto consolidation (suggestion: ${reflection.suggestion})`, env);
+    void runAutoConsolidate(options).catch((err: any) => {
+      appendAutoLog(`auto: unexpected error: ${err?.message}`, env);
+    });
+    return true;
+  } catch (err: any) {
+    appendAutoLog(`trigger error: ${err?.message}`, env);
+    return false;
+  }
+}

package/index.js

@@ -9,6 +9,7 @@
  */
 import { readFile, lstat, writeFile, copyFile, mkdir } from "node:fs/promises";
 import { commitReflections, consolidateCheckout, dateSearch, deleteMemories, deleteMemoryIds, getMemoryStats, ingestMemory, inspectMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
+import { isAutoConsolidationSession, maybeTriggerAutoConsolidate } from "./auto-consolidate.js";
 import { join, resolve, relative, isAbsolute, sep, dirname } from "node:path";
 import os from "node:os";
 const DEFAULT_ENDPOINT = "https://api.memoryrouter.ai";
@@ -478,8 +479,27 @@ const memoryRouterPlugin = {
         const logging = cfg?.logging ?? false;
         const embeddings = cfg?.embeddings; // undefined = bge (default), "qwen" = qwen3-8b
         const agentKeys = cfg?.agentKeys;
+        const autoConsolidate = cfg?.autoConsolidate !== false; // default true
         const log = (msg) => { if (logging)
             api.logger.info?.(msg); };
+        // Automatic consolidation trigger: deterministic plugin-side automation
+        // driving an isolated agent turn via the gateway's subagent runtime.
+        // Fire-and-forget; all rails (lock, cooldown, 3-batch bound) live in
+        // auto-consolidate.ts. Failures never propagate into the hook path.
+        function triggerAutoConsolidation(reflection, ctx, activeKey) {
+            try {
+                maybeTriggerAutoConsolidate(reflection ?? null, {
+                    autoConsolidate,
+                    sessionKey: ctx?.sessionKey,
+                    runtime: api.runtime?.subagent,
+                    agentId: ctx?.agentId || "main",
+                    endpoint,
+                    key: activeKey,
+                    embeddings,
+                });
+            }
+            catch { /* never blocks or crashes the host */ }
+        }
         // Resolve the correct memory key for a given agent context.
         // Multi-agent gateways: each agent gets its own key via agentKeys map.
         // Single-agent: falls back to the global key.
@@ -669,6 +689,11 @@ If setting up MemoryRouter for another agent:
             // When PR #24122 merges, OpenClaw will use the returned prependContext.
             // This gives forward compatibility — no plugin update needed.
             api.on("llm_input", async (event, ctx) => {
+                // Auto-consolidation runs are single-purpose tool sessions: no memory
+                // injection (their prompt must stay exactly the consolidation
+                // mission) and no re-trigger loops.
+                if (isAutoConsolidationSession(ctx?.sessionKey))
+                    return;
                 // Skip the first call — before_prompt_build already handled it
                 // (before_prompt_build includes workspace+tools+skills for accurate billing)
                 if (promptBuildFiredThisRun) {
@@ -740,6 +765,7 @@ If setting up MemoryRouter for another agent:
                         return;
                     }
                     const data = (await res.json());
+                    triggerAutoConsolidation(data.reflection, ctx, activeKey);
                     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]`);
@@ -762,6 +788,8 @@ If setting up MemoryRouter for another agent:
             });
             // ── before_prompt_build: fires once per run (primary, includes full billing context)
             api.on("before_prompt_build", async (event, ctx) => {
+                if (isAutoConsolidationSession(ctx?.sessionKey))
+                    return;
                 promptBuildFiredThisRun = true;
                 const activeKey = resolveKey(ctx);
                 if (!activeKey)
@@ -852,6 +880,7 @@ If setting up MemoryRouter for another agent:
                         return;
                     }
                     const data = (await res.json());
+                    triggerAutoConsolidation(data.reflection, ctx, activeKey);
                     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)`);
@@ -876,6 +905,9 @@ If setting up MemoryRouter for another agent:
             // Core: agent_end — store this turn's conversation
             // ==================================================================
             api.on("agent_end", async (event, ctx) => {
+                // Never store the auto-consolidation session's own chatter as memory.
+                if (isAutoConsolidationSession(ctx?.sessionKey))
+                    return;
                 const activeKey = resolveKey(ctx);
                 if (!activeKey)
                     return; // No key for this agent

package/index.ts

@@ -10,6 +10,7 @@
 
 import { readFile, readdir, stat, lstat, writeFile, copyFile, mkdir } from "node:fs/promises";
 import { commitReflections, consolidateCheckout, dateSearch, deleteMemories, deleteMemoryIds, getMemoryStats, ingestMemory, inspectMemory, prepareMemory, searchMemory, warmupMemory } from "./memoryrouter-api.js";
+import { isAutoConsolidationSession, maybeTriggerAutoConsolidate } from "./auto-consolidate.js";
 import { join, resolve, relative, isAbsolute, sep, dirname } from "node:path";
 import path from "node:path";
 import os from "node:os";
@@ -323,6 +324,10 @@ type MemoryRouterConfig = {
   /** 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;
+  /** Automatic consolidation when the server reports debt above its
+   *  threshold. Default true. Set false to opt out (the injected suggestion
+   *  nudge remains). */
+  autoConsolidate?: boolean;
 };
 
 // ──────────────────────────────────────────────────────
@@ -525,8 +530,27 @@ const memoryRouterPlugin = {
     const logging = cfg?.logging ?? false;
     const embeddings = cfg?.embeddings; // undefined = bge (default), "qwen" = qwen3-8b
     const agentKeys = cfg?.agentKeys;
+    const autoConsolidate = cfg?.autoConsolidate !== false; // default true
     const log = (msg: string) => { if (logging) api.logger.info?.(msg); };
 
+    // Automatic consolidation trigger: deterministic plugin-side automation
+    // driving an isolated agent turn via the gateway's subagent runtime.
+    // Fire-and-forget; all rails (lock, cooldown, 3-batch bound) live in
+    // auto-consolidate.ts. Failures never propagate into the hook path.
+    function triggerAutoConsolidation(reflection: ReflectionDebt | undefined, ctx: any, activeKey: string): void {
+      try {
+        maybeTriggerAutoConsolidate(reflection ?? null, {
+          autoConsolidate,
+          sessionKey: ctx?.sessionKey,
+          runtime: (api as any).runtime?.subagent,
+          agentId: ctx?.agentId || "main",
+          endpoint,
+          key: activeKey,
+          embeddings,
+        });
+      } catch { /* never blocks or crashes the host */ }
+    }
+
     // Resolve the correct memory key for a given agent context.
     // Multi-agent gateways: each agent gets its own key via agentKeys map.
     // Single-agent: falls back to the global key.
@@ -721,6 +745,10 @@ If setting up MemoryRouter for another agent:
       // When PR #24122 merges, OpenClaw will use the returned prependContext.
       // This gives forward compatibility — no plugin update needed.
       api.on("llm_input", async (event, ctx) => {
+        // Auto-consolidation runs are single-purpose tool sessions: no memory
+        // injection (their prompt must stay exactly the consolidation
+        // mission) and no re-trigger loops.
+        if (isAutoConsolidationSession(ctx?.sessionKey)) return;
         // Skip the first call — before_prompt_build already handled it
         // (before_prompt_build includes workspace+tools+skills for accurate billing)
         if (promptBuildFiredThisRun) {
@@ -800,6 +828,8 @@ If setting up MemoryRouter for another agent:
             import?: ImportSuggestedState;
           };
 
+          triggerAutoConsolidation(data.reflection, ctx, activeKey);
+
           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]`);
@@ -819,6 +849,7 @@ If setting up MemoryRouter for another agent:
 
       // ── before_prompt_build: fires once per run (primary, includes full billing context)
       api.on("before_prompt_build", async (event, ctx) => {
+        if (isAutoConsolidationSession(ctx?.sessionKey)) return;
         promptBuildFiredThisRun = true;
         const activeKey = resolveKey(ctx);
         if (!activeKey) return; // No key for this agent
@@ -924,6 +955,8 @@ If setting up MemoryRouter for another agent:
             import?: ImportSuggestedState;
           };
 
+          triggerAutoConsolidation(data.reflection, ctx, activeKey);
+
           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)`);
@@ -948,6 +981,8 @@ If setting up MemoryRouter for another agent:
       // ==================================================================
 
       api.on("agent_end", async (event, ctx) => {
+        // Never store the auto-consolidation session's own chatter as memory.
+        if (isAutoConsolidationSession(ctx?.sessionKey)) return;
         const activeKey = resolveKey(ctx);
         if (!activeKey) return; // No key for this agent
         try {

package/openclaw.plugin.json

@@ -27,6 +27,12 @@
       "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."
     }
   },
   "configSchema": {
@@ -61,6 +67,10 @@
         "minimum": 0,
         "description": "Keep the vault warm for this many ms after each message. Default 180000 (3 minutes). 0 disables warmup pings entirely."
       },
+      "autoConsolidate": {
+        "type": "boolean",
+        "description": "Automatically consolidate memories in an isolated background agent turn when the server reports debt above its threshold. Default true. Set false to opt out (the in-context suggestion nudge remains)."
+      },
       "agentKeys": {
         "type": "object",
         "additionalProperties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-memory",
-  "version": "3.10.0",
+  "version": "3.11.1",
   "description": "Persistent memory for OpenClaw, powered by MemoryRouter. Relay-based AI agent memory across sessions, compaction, and model changes.",
   "type": "module",
   "files": [
@@ -11,6 +11,8 @@
     "upload.ts",
     "memoryrouter-api.js",
     "memoryrouter-api.ts",
+    "auto-consolidate.js",
+    "auto-consolidate.ts",
     "import-transport.js",
     "import-transport.ts",
     "upload-api.js",