mr-memory 3.9.0 → 3.10.0

package/index.ts

@@ -65,7 +65,7 @@ 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)
+// ── Reflection debt nudge (one line, appended to prepare injections whenever the server suggests it)
 type ReflectionDebt = {
   suggestion?: string | null;
   unconsolidated?: {
@@ -75,15 +75,22 @@ type ReflectionDebt = {
   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.`;
+  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)
@@ -354,36 +361,6 @@ 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).
@@ -820,6 +797,7 @@ If setting up MemoryRouter for another agent:
             memory_tokens?: number;
             metrics?: Record<string, unknown>;
             reflection?: ReflectionDebt;
+            import?: ImportSuggestedState;
           };
 
           if (data.context) {
@@ -827,8 +805,10 @@ If setting up MemoryRouter for another agent:
             api.logger.info?.(`memoryrouter: injected ${data.memories_found || 0} memories (${data.memory_tokens || 0} tokens, ${elapsed}ms) [llm_input]`);
             if (elapsed > 2000 && data.metrics) log(`memoryrouter: prepare metrics ${JSON.stringify(data.metrics)}`);
             let contextText = data.context;
-            const nudge = await maybeDebtNudge(data.reflection);
+            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 };
           }
@@ -941,6 +921,7 @@ If setting up MemoryRouter for another agent:
             memory_tokens?: number;
             metrics?: Record<string, unknown>;
             reflection?: ReflectionDebt;
+            import?: ImportSuggestedState;
           };
 
           if (data.context) {
@@ -948,8 +929,10 @@ If setting up MemoryRouter for another agent:
             api.logger.info?.(`memoryrouter: injected ${data.memories_found || 0} memories (${data.memory_tokens || 0} tokens, ${elapsed}ms)`);
             if (elapsed > 2000 && data.metrics) log(`memoryrouter: prepare metrics ${JSON.stringify(data.metrics)}`);
             let contextText = data.context;
-            const nudge = await maybeDebtNudge(data.reflection);
+            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 };
           }
@@ -1682,6 +1665,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mr-memory",
-  "version": "3.9.0",
+  "version": "3.10.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,8 @@
     "upload.ts",
     "memoryrouter-api.js",
     "memoryrouter-api.ts",
+    "import-transport.js",
+    "import-transport.ts",
     "upload-api.js",
     "upload-api.ts",
     "openclaw.plugin.json"