mr-memory 3.9.1 → 3.11.0

package/README.md

@@ -40,6 +40,19 @@ openclaw mr upload --workspace <dir>   # Custom workspace directory
 openclaw mr upload --brain <dir>       # Custom state dir (sessions from another agent)
 ```
 
+## Historical Import (agent-driven)
+
+Import existing OpenClaw conversation history with a strict division of labor: the server owns the extraction prompt (versioned, fetched at import time), your agent owns discovery/parsing of the local session files, and the CLI owns transport. The agent never uploads; the CLI never parses history.
+
+```bash
+openclaw mr import --instructions        # print the server's extraction prompt for your agent
+openclaw mr import --file extract.jsonl  # validate, preview, price quote, approve, upload
+openclaw mr import --file extract.jsonl --yes   # non-interactive approval
+openclaw mr import --dismiss             # permanently silence the import nudge
+```
+
+Guarantees: the extract is validated locally (four fields per record, `openclaw:` prefixed ids, epoch-ms timestamps); the CLI shows record count, date range, estimated tokens, and the server price quote and requires explicit approval before any write; the import id is content-derived and every batch carries an Idempotency-Key, so re-running after any interruption replays committed batches for free and resumes. Duplicates are never re-billed. The memory key never appears in the prompt or the extract file. When a vault is new, injected context includes a one-line import suggestion until an import completes or you `--dismiss`.
+
 ## How It Works
 
 When enabled, relay hooks retrieve memory before agent/model input and capture the direct user-to-assistant conversation at `agent_end`. Inference and provider API keys remain inside OpenClaw; the plugin does not route provider calls through MemoryRouter and is not a provider-key proxy.
@@ -56,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,292 @@
+/**
+ * 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,
+                });
+                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,279 @@
+/**
+ * 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 }) => 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,
+        });
+        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;
+  }
+}