mr-memory 3.9.0 → 3.10.0

package/import-transport.ts

@@ -0,0 +1,511 @@
+/**
+ * Agent-driven historical import: the transport half (OpenClaw lane).
+ *
+ * Division of labor (locked): the SERVER owns the extraction prompt
+ * (GET /v1/memory/imports/instructions, versioned like reflection_contract);
+ * the HOST AGENT executes that prompt locally and writes a JSONL extract; THIS
+ * MODULE owns transport only: local validation, deterministic identity math
+ * (byte-for-byte with workers/src/services/import-identity.ts), create and
+ * approve, idempotent batch upload with resume, and the receipt. The agent
+ * never touches HTTP for upload and this module never parses history.
+ *
+ * The Memory Key never appears in the prompt or the extract file; it rides
+ * only in the Authorization header.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import readline from "node:readline";
+import {
+  importInstructions,
+  importCreate,
+  importApprove,
+  importBatch,
+  importStatus,
+  importReceipt,
+  importDismiss,
+} from "./memoryrouter-api.js";
+
+export const PLATFORM = "openclaw";
+export const PARSER_VERSION = 1;
+export const CHUNK_VERSION = 1;
+const BATCH_SIZE = 2000;
+const MAX_CONTENT_CHARS = 1000000;
+const MAX_UPLOAD_ATTEMPTS = 5;
+const INITIAL_BACKOFF_MS = 2000;
+const MAX_BACKOFF_MS = 30000;
+
+// ── identity math (mirrors the server byte-for-byte) ─────────────────────────
+
+function sha256hex(input: string): string {
+  return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      out[key] = sortKeys((value as Record<string, unknown>)[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function canonicalJson(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+export function normalizeText(input: string): string {
+  return input.normalize("NFC").replace(/\r\n?/g, "\n").trim();
+}
+
+export function vaultFingerprint(memoryKey: string): string {
+  return `mrvault_${sha256hex(memoryKey).slice(0, 16)}`;
+}
+
+function unescapeIdPart(s: string): string {
+  return s.replace(/%3A/g, ":").replace(/%25/g, "%");
+}
+
+export function parseExternalId(id: string): { platform: string; conversationId: string; messageId: string; parserVersion: number } | null {
+  const parts = id.split(":");
+  if (parts.length !== 4) return null;
+  const [platform, conv, msg, ver] = parts;
+  if (!/^v\d+$/.test(ver)) return null;
+  return {
+    platform,
+    conversationId: unescapeIdPart(conv),
+    messageId: unescapeIdPart(msg),
+    parserVersion: parseInt(ver.slice(1), 10),
+  };
+}
+
+export function recordHash(fields: { conversationId: string; messageId: string; role: string; text: string; timestamp: number }): string {
+  return sha256hex(
+    canonicalJson({
+      conversationId: fields.conversationId,
+      messageId: fields.messageId,
+      role: fields.role,
+      text: normalizeText(fields.text),
+      timestamp: fields.timestamp,
+      v: PARSER_VERSION,
+    }),
+  ).slice(0, 32);
+}
+
+export function conversationContentHash(fields: {
+  conversationId: string;
+  canonicalPolicy: string;
+  canonicalLeaf: string | null;
+  records: Array<{ externalId: string; recordHash: string; role: string; timestamp: number }>;
+}): string {
+  return sha256hex(canonicalJson(fields)).slice(0, 32);
+}
+
+export function archiveContentId(conversationContentHashes: string[]): string {
+  const canonical = [...conversationContentHashes].sort().join("\n");
+  return `arc_${sha256hex(`v${PARSER_VERSION}\n${canonical}`).slice(0, 24)}`;
+}
+
+export function deriveImportId(archiveId: string, fingerprint: string): string {
+  return `imp_${sha256hex(`${archiveId}|${fingerprint}|p${PARSER_VERSION}|c${CHUNK_VERSION}`).slice(0, 24)}`;
+}
+
+export function previewDigest(preview: unknown): string {
+  return `pvd_${sha256hex(canonicalJson(preview)).slice(0, 32)}`;
+}
+
+// ── extract validation ───────────────────────────────────────────────────────
+
+export interface ExtractRecord {
+  externalId: string;
+  conversationId: string;
+  messageId: string;
+  content: string;
+  role: "user" | "assistant";
+  timestamp: number;
+  recordSha256?: string;
+}
+
+export function readExtract(filePath: string, platform: string = PLATFORM): { records?: ExtractRecord[]; error?: string } {
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (err) {
+    return { error: `could not read ${filePath}: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  const records: ExtractRecord[] = [];
+  const seen = new Set<string>();
+  const lines = raw.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    const lineNo = i + 1;
+    let p: Record<string, unknown>;
+    try {
+      p = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      return { error: `line ${lineNo}: not valid JSON` };
+    }
+    if (!p || typeof p !== "object" || Array.isArray(p)) return { error: `line ${lineNo}: record is not an object` };
+    const extras = Object.keys(p).filter((k) => !["external_id", "content", "timestamp", "role"].includes(k));
+    if (extras.length) return { error: `line ${lineNo}: unexpected fields: ${extras.join(", ")}` };
+    if (typeof p.external_id !== "string" || !p.external_id) return { error: `line ${lineNo}: external_id must be a string` };
+    const parsed = parseExternalId(p.external_id);
+    if (!parsed) return { error: `line ${lineNo}: malformed external_id (expected ${platform}:<conversation>:<message>:v${PARSER_VERSION})` };
+    if (parsed.platform !== platform) return { error: `line ${lineNo}: external_id platform must be ${platform}, got ${parsed.platform}` };
+    if (parsed.parserVersion !== PARSER_VERSION) return { error: `line ${lineNo}: external_id version must be v${PARSER_VERSION}` };
+    if (typeof p.content !== "string" || p.content.length === 0) return { error: `line ${lineNo}: content must be a non-empty string` };
+    if (p.content.length > MAX_CONTENT_CHARS) return { error: `line ${lineNo}: content exceeds ${MAX_CONTENT_CHARS} chars` };
+    if (typeof p.timestamp !== "number" || !Number.isFinite(p.timestamp) || p.timestamp <= 0) {
+      return { error: `line ${lineNo}: timestamp must be a positive epoch-milliseconds number` };
+    }
+    if (p.timestamp < 1000000000000) return { error: `line ${lineNo}: timestamp looks like seconds, not milliseconds (${p.timestamp})` };
+    if (p.role !== "user" && p.role !== "assistant") return { error: `line ${lineNo}: role must be "user" or "assistant"` };
+    if (seen.has(p.external_id)) return { error: `line ${lineNo}: duplicate external_id ${p.external_id}` };
+    seen.add(p.external_id);
+    records.push({
+      externalId: p.external_id,
+      conversationId: parsed.conversationId,
+      messageId: parsed.messageId,
+      content: p.content,
+      role: p.role,
+      timestamp: p.timestamp,
+    });
+  }
+  if (records.length === 0) return { error: "the extract file contains no records" };
+  return { records };
+}
+
+// ── identity + preview ───────────────────────────────────────────────────────
+
+export function computeIdentity(records: ExtractRecord[], memoryKey: string, platform: string = PLATFORM) {
+  const byConversation = new Map<string, ExtractRecord[]>();
+  for (const r of records) {
+    r.recordSha256 = recordHash({
+      conversationId: r.conversationId,
+      messageId: r.messageId,
+      role: r.role,
+      text: r.content,
+      timestamp: r.timestamp,
+    });
+    if (!byConversation.has(r.conversationId)) byConversation.set(r.conversationId, []);
+    byConversation.get(r.conversationId)!.push(r);
+  }
+  const convHashes: string[] = [];
+  for (const [conversationId, convRecords] of byConversation) {
+    convHashes.push(conversationContentHash({
+      conversationId,
+      canonicalPolicy: `agent-extract-${platform}`,
+      canonicalLeaf: null,
+      records: convRecords.map((r) => ({
+        externalId: r.externalId,
+        recordHash: r.recordSha256!,
+        role: r.role,
+        timestamp: r.timestamp,
+      })),
+    }));
+  }
+  const archiveId = archiveContentId(convHashes);
+  const fingerprint = vaultFingerprint(memoryKey);
+  const importId = deriveImportId(archiveId, fingerprint);
+  return { archiveId, fingerprint, importId, conversations: byConversation.size };
+}
+
+export function estimateTokens(records: ExtractRecord[]): number {
+  let total = 0;
+  for (const r of records) total += Math.ceil(r.content.length / 4);
+  return total;
+}
+
+export function buildPreviewSummary(records: ExtractRecord[]) {
+  let earliest = Number.POSITIVE_INFINITY;
+  let latest = 0;
+  let user = 0;
+  for (const r of records) {
+    if (r.role === "user") user++;
+    if (r.timestamp < earliest) earliest = r.timestamp;
+    if (r.timestamp > latest) latest = r.timestamp;
+  }
+  return {
+    records: records.length,
+    userRecords: user,
+    assistantRecords: records.length - user,
+    earliestMs: Number.isFinite(earliest) ? earliest : 0,
+    latestMs: latest,
+    estimatedTokens: estimateTokens(records),
+  };
+}
+
+export function toWireRecord(r: ExtractRecord, platform: string = PLATFORM): string {
+  return JSON.stringify({
+    external_id: r.externalId,
+    record_sha256: r.recordSha256,
+    content: r.content,
+    role: r.role,
+    timestamp: r.timestamp,
+    source_platform: platform,
+    parser_version: PARSER_VERSION,
+    chunk_version: CHUNK_VERSION,
+  });
+}
+
+// ── flows ────────────────────────────────────────────────────────────────────
+
+type Fetchers = {
+  importInstructions: typeof importInstructions;
+  importCreate: typeof importCreate;
+  importApprove: typeof importApprove;
+  importBatch: typeof importBatch;
+  importStatus: typeof importStatus;
+  importReceipt: typeof importReceipt;
+  importDismiss: typeof importDismiss;
+};
+
+const defaultFetchers: Fetchers = {
+  importInstructions,
+  importCreate,
+  importApprove,
+  importBatch,
+  importStatus,
+  importReceipt,
+  importDismiss,
+};
+
+export interface ImportOptions {
+  endpoint: string;
+  key: string;
+  platform?: string;
+  file?: string;
+  yes?: boolean;
+  nonInteractive?: boolean;
+  batchSize?: number;
+  log?: (...args: unknown[]) => void;
+  fetchers?: Partial<Fetchers>;
+}
+
+function fmtDate(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "unknown";
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+function fmtTokens(n: number): string {
+  if (n >= 1000000) return `${(n / 1000000).toFixed(1)}M`;
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}K`;
+  return String(n);
+}
+
+async function jsonOf(res: Response): Promise<Record<string, any>> {
+  try {
+    return (await res.json()) as Record<string, any>;
+  } catch {
+    return {};
+  }
+}
+
+function errorDetail(status: number, body: Record<string, unknown>): string {
+  const parts = [body.error, body.message].filter(Boolean);
+  return parts.length ? parts.join(": ") : `HTTP ${status}`;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function ask(question: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (answer) => {
+    rl.close();
+    resolve(answer.trim().toLowerCase());
+  }));
+}
+
+/** Fetch and print the server-side extraction prompt for the host agent. */
+export async function runInstructions(options: ImportOptions): Promise<{ version: number }> {
+  const f = { ...defaultFetchers, ...(options.fetchers || {}) };
+  const log = options.log || ((...args: unknown[]) => console.log(...args));
+  const res = await f.importInstructions(options.endpoint, options.key, options.platform || PLATFORM);
+  const body = await jsonOf(res);
+  if (!res.ok) throw new Error(`could not fetch import instructions (${errorDetail(res.status, body)})`);
+  if (!body.prompt) throw new Error("instructions response carried no prompt");
+  log(body.prompt);
+  return { version: Number(body.import_prompt_version) || 0 };
+}
+
+/** Call the dismiss endpoint so the server-side nudge stops permanently. */
+export async function runDismiss(options: ImportOptions): Promise<void> {
+  const f = { ...defaultFetchers, ...(options.fetchers || {}) };
+  const log = options.log || ((...args: unknown[]) => console.log(...args));
+  const res = await f.importDismiss(options.endpoint, options.key, options.platform || PLATFORM);
+  const body = await jsonOf(res);
+  if (!res.ok) throw new Error(`dismiss failed (${errorDetail(res.status, body)})`);
+  log("Import suggestion dismissed permanently for this vault.");
+}
+
+/** The transport: validate, create, quote, approve, upload, receipt. */
+export async function runImportFile(options: ImportOptions): Promise<{
+  aborted?: boolean;
+  importId?: string;
+  totals?: Record<string, number>;
+  complete?: boolean;
+  receipt?: unknown;
+}> {
+  const f = { ...defaultFetchers, ...(options.fetchers || {}) };
+  const log = options.log || ((...args: unknown[]) => console.log(...args));
+  const platform = options.platform || PLATFORM;
+  if (!options.file) throw new Error("--file <path> is required");
+
+  const parsed = readExtract(options.file, platform);
+  if (parsed.error) throw new Error(`invalid extract: ${parsed.error}`);
+  const records = parsed.records!;
+  const identity = computeIdentity(records, options.key, platform);
+  const preview = buildPreviewSummary(records);
+
+  const clientPreviewDigest = previewDigest({
+    importId: identity.importId,
+    archiveId: identity.archiveId,
+    fingerprint: identity.fingerprint,
+    parserVersion: PARSER_VERSION,
+    chunkVersion: CHUNK_VERSION,
+    expectedRecords: preview.records,
+    expectedChunks: preview.records,
+    estimatedTokens: preview.estimatedTokens,
+    selection: null,
+    categories: [],
+  });
+  const createRes = await f.importCreate(options.endpoint, options.key, {
+    import_id: identity.importId,
+    archive_content_id: identity.archiveId,
+    archive_sha256: null,
+    parser_version: PARSER_VERSION,
+    chunk_version: CHUNK_VERSION,
+    source_platform: platform,
+    vault_fingerprint: identity.fingerprint,
+    preview_digest: clientPreviewDigest,
+    expected_records: preview.records,
+    expected_chunks: preview.records,
+    estimated_tokens: preview.estimatedTokens,
+    selection: null,
+    categories: [],
+  });
+  const created = await jsonOf(createRes);
+  if (!createRes.ok) throw new Error(`import preflight failed (${errorDetail(createRes.status, created)})`);
+  if (created.preview_digest && created.preview_digest !== clientPreviewDigest) {
+    throw new Error("client/server preview digest mismatch (fail closed)");
+  }
+  const quote = (created.cost_quote || {}) as Record<string, any>;
+
+  log("");
+  log("Import preview");
+  log("----------------------------");
+  log(`Platform:          ${platform}`);
+  log(`Destination vault: ${identity.fingerprint} (opaque fingerprint)`);
+  log(`Conversations:     ${identity.conversations}`);
+  log(`Records:           ${preview.records} (user ${preview.userRecords}, assistant ${preview.assistantRecords})`);
+  log(`Date range:        ${fmtDate(preview.earliestMs)} to ${fmtDate(preview.latestMs)}`);
+  log(`Estimated tokens:  ${fmtTokens(preview.estimatedTokens)}`);
+  if (quote.available) {
+    log(`Estimated cost:    $${((quote.estimated_cost_cents || 0) / 100).toFixed(2)} (rate $${quote.rate_per_million_usd}/1M paid tokens, free remaining ${fmtTokens(quote.free_tokens_remaining || 0)})`);
+  } else {
+    log(`Estimated cost:    unavailable (${quote.reason || "unknown"}); the server will refuse approval (fail closed)`);
+  }
+  log(`Import id:         ${identity.importId}`);
+  log("");
+  log("Re-running this command is always safe: committed batches replay for free and duplicates are never re-billed.");
+  log("");
+
+  if (!options.yes) {
+    if (options.nonInteractive || !process.stdin.isTTY) {
+      throw new Error("approval required: re-run with --yes to confirm the upload");
+    }
+    const answer = await ask("Proceed with the upload? [y/N]: ");
+    if (answer !== "y" && answer !== "yes") {
+      log("Aborted. Nothing was uploaded.");
+      return { aborted: true };
+    }
+  }
+
+  const approveRes = await f.importApprove(options.endpoint, options.key, identity.importId, String(created.approval_digest));
+  if (!approveRes.ok) {
+    const body = await jsonOf(approveRes);
+    // A completed import cannot be re-approved; that is the fully-settled
+    // resume case. Print the receipt instead of failing.
+    if (body.error === "import_completed") {
+      const receiptRes = await f.importReceipt(options.endpoint, options.key, identity.importId);
+      let receipt: unknown = null;
+      if (receiptRes.ok) {
+        const receiptBody = await jsonOf(receiptRes);
+        receipt = receiptBody.receipt ?? null;
+      }
+      log("This exact extract was already fully imported into this vault. Nothing to upload.");
+      if (receipt) {
+        log("Receipt:");
+        log(JSON.stringify(receipt, null, 2));
+      }
+      return { importId: identity.importId, complete: true, receipt };
+    }
+    throw new Error(`approval refused (${errorDetail(approveRes.status, body)})`);
+  }
+
+  const batches: ExtractRecord[][] = [];
+  const size = options.batchSize || BATCH_SIZE;
+  for (let i = 0; i < records.length; i += size) batches.push(records.slice(i, i + size));
+  const totals = { stored: 0, duplicate: 0, skipped: 0, failed: 0, conflict: 0 };
+  log(`Uploading ${records.length} record(s) in ${batches.length} batch(es)...`);
+  for (let i = 0; i < batches.length; i++) {
+    const jsonl = batches[i].map((r) => toWireRecord(r, platform)).join("\n");
+    const idempotencyKey = `${identity.importId}:b${i}`;
+    let res: Response | null = null;
+    let backoff = INITIAL_BACKOFF_MS;
+    for (let attempt = 1; attempt <= MAX_UPLOAD_ATTEMPTS; attempt++) {
+      try {
+        res = await f.importBatch(options.endpoint, options.key, identity.importId, i, jsonl, idempotencyKey);
+      } catch (err) {
+        res = null;
+        if (attempt === MAX_UPLOAD_ATTEMPTS) {
+          throw new Error(`batch ${i} failed after ${MAX_UPLOAD_ATTEMPTS} attempts: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+      if (res && (res.ok || (res.status < 500 && res.status !== 429))) break;
+      if (attempt === MAX_UPLOAD_ATTEMPTS) break;
+      await sleep(backoff);
+      backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+    }
+    if (!res) throw new Error(`batch ${i} received no response`);
+    const body = await jsonOf(res);
+    if (res.status === 402) {
+      throw new Error("payment required: out of tokens/credits. Add credits at https://app.memoryrouter.ai and re-run to resume.");
+    }
+    if (!res.ok) throw new Error(`batch ${i} failed (${errorDetail(res.status, body)}). Re-run to resume; committed batches replay for free.`);
+    const s = (body.summary || {}) as Record<string, number>;
+    totals.stored += s.stored || 0;
+    totals.duplicate += s.duplicate || 0;
+    totals.skipped += s.skipped || 0;
+    totals.failed += s.failed || 0;
+    totals.conflict += s.conflict || 0;
+    log(`  batch ${i + 1}/${batches.length}${body.replayed ? " (replayed, free)" : ""}: stored ${s.stored || 0}, duplicate ${s.duplicate || 0}, failed ${s.failed || 0}`);
+  }
+
+  const statusRes = await f.importStatus(options.endpoint, options.key, identity.importId);
+  const statusBody = await jsonOf(statusRes);
+  const complete = Boolean(statusRes.ok && statusBody.complete);
+  let receipt: unknown = null;
+  if (complete) {
+    const receiptRes = await f.importReceipt(options.endpoint, options.key, identity.importId);
+    if (receiptRes.ok) {
+      const receiptBody = await jsonOf(receiptRes);
+      receipt = receiptBody.receipt ?? null;
+    }
+  }
+  log("");
+  log(`Done. stored=${totals.stored} duplicate=${totals.duplicate} skipped=${totals.skipped} failed=${totals.failed} conflict=${totals.conflict}`);
+  if (receipt) {
+    log("Receipt:");
+    log(JSON.stringify(receipt, null, 2));
+  } else if (!complete) {
+    log("The import is not fully settled yet; re-run this command to resume/reconcile.");
+  }
+  return { importId: identity.importId, totals, complete, receipt };
+}

package/index.js

@@ -55,7 +55,6 @@ function stripOldMemory(text) {
 function jsonToolResult(payload) {
     return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], details: payload };
 }
-const NUDGE_INTERVAL_MS = 24 * 60 * 60 * 1000; // at most one nudge per 24h
 function buildDebtNudgeLine(reflection) {
     if (!reflection || !reflection.suggestion)
         return null;
@@ -63,7 +62,12 @@ function buildDebtNudgeLine(reflection) {
     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.`;
+}
+function buildImportNudgeLine(importState) {
+    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) {
@@ -311,37 +315,6 @@ async function writeOpenClawConfigFile(config) {
     await writeFile(configPath, `${JSON.stringify(config, null, 2)}
 `, "utf8");
 }
-// Nudge rate-limit state lives beside the OpenClaw config so it survives restarts
-// without churning the main config file.
-function nudgeStatePath() {
-    return join(dirname(openClawConfigPath()), "mr-memory-state.json");
-}
-async function consumeNudgeBudget() {
-    const now = Date.now();
-    let state = {};
-    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) {
-    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).
@@ -773,9 +746,12 @@ If setting up MemoryRouter for another agent:
                         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 };
                     }
@@ -882,9 +858,12 @@ If setting up MemoryRouter for another agent:
                         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 };
                     }
@@ -1597,6 +1576,44 @@ If setting up MemoryRouter for another agent:
                     console.error(`Failed: ${err instanceof Error ? err.message : String(err)}`);
                 }
             });
+            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) => {
+                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)")