mr-memory 3.9.1 → 3.11.0

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";
@@ -84,6 +85,15 @@ function buildDebtNudgeLine(reflection: ReflectionDebt | undefined): string | nu
   return `[MemoryRouter] Consolidation suggested: ${kTokens}k unconsolidated tokens. Use the memory_reflect tool to consolidate them now.`;
 }
 
+// ── Historical import nudge (server-owned import.suggested block; additive,
+// no rate limit, clears server-side on import completion or dismiss)
+type ImportSuggestedState = { suggested?: boolean; platform_hint?: string | null; suggestion?: string };
+
+function buildImportNudgeLine(importState: ImportSuggestedState | undefined): string | null {
+  if (!importState || !importState.suggested) return null;
+  return `[MemoryRouter] Historical import suggested: this machine has local conversation history not yet in your vault. Run: openclaw mr import --instructions`;
+}
+
 // ── 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");
@@ -314,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;
 };
 
 // ──────────────────────────────────────────────────────
@@ -516,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.
@@ -712,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) {
@@ -788,8 +825,11 @@ If setting up MemoryRouter for another agent:
             memory_tokens?: number;
             metrics?: Record<string, unknown>;
             reflection?: ReflectionDebt;
+            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]`);
@@ -797,6 +837,8 @@ If setting up MemoryRouter for another agent:
             let contextText = data.context;
             const nudge = buildDebtNudgeLine(data.reflection);
             if (nudge) contextText = `${contextText}\n\n${nudge}`;
+            const importNudge = buildImportNudgeLine(data.import);
+            if (importNudge) contextText = `${contextText}\n\n${importNudge}`;
             const wrapped = wrapForInjection(contextText);
             return { appendSystemContext: wrapped };
           }
@@ -807,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
@@ -909,8 +952,11 @@ If setting up MemoryRouter for another agent:
             memory_tokens?: number;
             metrics?: Record<string, unknown>;
             reflection?: ReflectionDebt;
+            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)`);
@@ -918,6 +964,8 @@ If setting up MemoryRouter for another agent:
             let contextText = data.context;
             const nudge = buildDebtNudgeLine(data.reflection);
             if (nudge) contextText = `${contextText}\n\n${nudge}`;
+            const importNudge = buildImportNudgeLine(data.import);
+            if (importNudge) contextText = `${contextText}\n\n${importNudge}`;
             const wrapped = wrapForInjection(contextText);
             return { appendSystemContext: wrapped };
           }
@@ -933,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 {
@@ -1650,6 +1700,38 @@ If setting up MemoryRouter for another agent:
             }
           });
 
+        mr.command("import")
+          .description("Import historical OpenClaw conversations into your vault (agent-driven extraction + CLI transport)")
+          .option("--instructions", "Fetch and print the server's extraction prompt for the host agent to execute")
+          .option("--file <path>", "Upload a JSONL extract: preview, price quote, explicit approval, idempotent batches, resume")
+          .option("--dismiss", "Permanently silence the import suggestion for this vault")
+          .option("--yes", "Skip the interactive approval prompt (required for non-interactive --file runs)")
+          .option("--key <key>", "Override memory key (for subagent vaults)")
+          .action(async (opts: { instructions?: boolean; file?: string; dismiss?: boolean; yes?: boolean; key?: string }) => {
+            const effectiveKey = opts.key || process.env.MEMORYROUTER_API_KEY || memoryKey;
+            if (!effectiveKey) { console.error("Not configured. Run: openclaw mr <key> or pass --key <key>"); return; }
+            const modes = [Boolean(opts.instructions), opts.file !== undefined, Boolean(opts.dismiss)].filter(Boolean).length;
+            if (modes > 1) { console.error("Choose one of --instructions, --file <path>, or --dismiss"); return; }
+            try {
+              const transport = await import("./import-transport.js");
+              if (opts.dismiss) {
+                await transport.runDismiss({ endpoint, key: effectiveKey });
+                return;
+              }
+              if (opts.file) {
+                await transport.runImportFile({ endpoint, key: effectiveKey, file: opts.file, yes: Boolean(opts.yes) });
+                return;
+              }
+              await transport.runInstructions({ endpoint, key: effectiveKey });
+              console.log("");
+              console.log("Execute the prompt above with your agent, then upload the extract:");
+              console.log("  openclaw mr import --file <path>");
+            } catch (err) {
+              console.error(`Import failed: ${err instanceof Error ? err.message : String(err)}`);
+              process.exitCode = 1;
+            }
+          });
+
         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)")

package/memoryrouter-api.js

@@ -115,6 +115,57 @@ export async function deleteMemories(endpoint, key, embeddings) {
         headers: { Authorization: `Bearer ${key}` },
     });
 }
+// ── Historical import wrappers (agent-driven import) ────────────────────────
+// The server owns the extraction prompt; the CLI owns transport. The imports
+// API is fully idempotent: create/approve/batches are safe to re-run.
+export async function importInstructions(endpoint, key, platform, outputPath) {
+    const query = `platform=${encodeURIComponent(platform)}` + (outputPath ? `&output_path=${encodeURIComponent(outputPath)}` : "");
+    return fetch(`${endpoint}/v1/memory/imports/instructions?${query}`, {
+        headers: { Authorization: `Bearer ${key}` },
+    });
+}
+export async function importCreate(endpoint, key, body) {
+    return fetch(`${endpoint}/v1/memory/imports`, {
+        method: "POST",
+        headers: { ...JSON_HEADERS, Authorization: `Bearer ${key}` },
+        body: JSON.stringify(body),
+    });
+}
+export async function importApprove(endpoint, key, importId, approvalDigest) {
+    return fetch(`${endpoint}/v1/memory/imports/${encodeURIComponent(importId)}/approve`, {
+        method: "POST",
+        headers: { ...JSON_HEADERS, Authorization: `Bearer ${key}` },
+        body: JSON.stringify({ approval_digest: approvalDigest }),
+    });
+}
+export async function importBatch(endpoint, key, importId, batchIndex, jsonl, idempotencyKey) {
+    return fetch(`${endpoint}/v1/memory/imports/${encodeURIComponent(importId)}/batches/${batchIndex}`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${key}`,
+            "Content-Type": "application/x-ndjson",
+            "Idempotency-Key": idempotencyKey,
+        },
+        body: jsonl,
+    });
+}
+export async function importStatus(endpoint, key, importId) {
+    return fetch(`${endpoint}/v1/memory/imports/${encodeURIComponent(importId)}`, {
+        headers: { Authorization: `Bearer ${key}` },
+    });
+}
+export async function importReceipt(endpoint, key, importId) {
+    return fetch(`${endpoint}/v1/memory/imports/${encodeURIComponent(importId)}/receipt`, {
+        headers: { Authorization: `Bearer ${key}` },
+    });
+}
+export async function importDismiss(endpoint, key, platform) {
+    return fetch(`${endpoint}/v1/memory/imports/dismiss-suggestion`, {
+        method: "POST",
+        headers: { ...JSON_HEADERS, Authorization: `Bearer ${key}` },
+        body: JSON.stringify({ platform }),
+    });
+}
 export async function warmupMemory(endpoint, key, embeddings) {
     return fetch(`${endpoint}/v1/memory/warmup`, {
         method: "POST",

package/memoryrouter-api.ts

@@ -132,6 +132,65 @@ export async function deleteMemories(endpoint: string, key: string, embeddings?:
   });
 }
 
+// ── Historical import wrappers (agent-driven import) ────────────────────────
+// The server owns the extraction prompt; the CLI owns transport. The imports
+// API is fully idempotent: create/approve/batches are safe to re-run.
+
+export async function importInstructions(endpoint: string, key: string, platform: string, outputPath?: string): Promise<Response> {
+  const query = `platform=${encodeURIComponent(platform)}` + (outputPath ? `&output_path=${encodeURIComponent(outputPath)}` : "");
+  return fetch(`${endpoint}/v1/memory/imports/instructions?${query}`, {
+    headers: { Authorization: `Bearer ${key}` },
+  });
+}
+
+export async function importCreate(endpoint: string, key: string, body: Record<string, unknown>): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/imports`, {
+    method: "POST",
+    headers: { ...JSON_HEADERS, Authorization: `Bearer ${key}` },
+    body: JSON.stringify(body),
+  });
+}
+
+export async function importApprove(endpoint: string, key: string, importId: string, approvalDigest: string): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/imports/${encodeURIComponent(importId)}/approve`, {
+    method: "POST",
+    headers: { ...JSON_HEADERS, Authorization: `Bearer ${key}` },
+    body: JSON.stringify({ approval_digest: approvalDigest }),
+  });
+}
+
+export async function importBatch(endpoint: string, key: string, importId: string, batchIndex: number, jsonl: string, idempotencyKey: string): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/imports/${encodeURIComponent(importId)}/batches/${batchIndex}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${key}`,
+      "Content-Type": "application/x-ndjson",
+      "Idempotency-Key": idempotencyKey,
+    },
+    body: jsonl,
+  });
+}
+
+export async function importStatus(endpoint: string, key: string, importId: string): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/imports/${encodeURIComponent(importId)}`, {
+    headers: { Authorization: `Bearer ${key}` },
+  });
+}
+
+export async function importReceipt(endpoint: string, key: string, importId: string): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/imports/${encodeURIComponent(importId)}/receipt`, {
+    headers: { Authorization: `Bearer ${key}` },
+  });
+}
+
+export async function importDismiss(endpoint: string, key: string, platform: string): Promise<Response> {
+  return fetch(`${endpoint}/v1/memory/imports/dismiss-suggestion`, {
+    method: "POST",
+    headers: { ...JSON_HEADERS, Authorization: `Bearer ${key}` },
+    body: JSON.stringify({ platform }),
+  });
+}
+
 export async function warmupMemory(endpoint: string, key: string, embeddings?: string): Promise<Response> {
   return fetch(`${endpoint}/v1/memory/warmup`, {
     method: "POST",

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.9.1",
+  "version": "3.11.0",
   "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,10 @@
     "upload.ts",
     "memoryrouter-api.js",
     "memoryrouter-api.ts",
+    "auto-consolidate.js",
+    "auto-consolidate.ts",
+    "import-transport.js",
+    "import-transport.ts",
     "upload-api.js",
     "upload-api.ts",
     "openclaw.plugin.json"