@joshuaswarren/openclaw-engram 8.3.28 → 8.3.30

package/dist/index.js

@@ -10733,6 +10733,81 @@ var GraphIndex = class {
   }
 };
 
+// src/replay/types.ts
+var VALID_SOURCES = /* @__PURE__ */ new Set(["openclaw", "claude", "chatgpt"]);
+var VALID_ROLES = /* @__PURE__ */ new Set(["user", "assistant"]);
+var ISO_UTC_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+var REPLAY_UNKNOWN_SESSION_KEY = "replay:unknown";
+function normalizeIsoForComparison(value) {
+  return value.includes(".") ? value : value.replace("Z", ".000Z");
+}
+function isReplaySource(value) {
+  return typeof value === "string" && VALID_SOURCES.has(value);
+}
+function isReplayRole(value) {
+  return typeof value === "string" && VALID_ROLES.has(value);
+}
+function normalizeReplaySessionKey(value) {
+  if (typeof value !== "string") return REPLAY_UNKNOWN_SESSION_KEY;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : REPLAY_UNKNOWN_SESSION_KEY;
+}
+function parseIsoTimestamp(value) {
+  if (typeof value !== "string" || !ISO_UTC_TIMESTAMP_RE.test(value)) return null;
+  const ts = Date.parse(value);
+  if (!Number.isFinite(ts)) return null;
+  const roundTrip = new Date(ts).toISOString();
+  if (roundTrip !== normalizeIsoForComparison(value)) return null;
+  return ts;
+}
+function validateReplayTurn(turn, index) {
+  const issues = [];
+  if (!turn || typeof turn !== "object") {
+    issues.push({
+      code: "turn.invalid",
+      message: "Replay turn must be an object.",
+      index
+    });
+    return issues;
+  }
+  if (!isReplayRole(turn.role)) {
+    issues.push({
+      code: "turn.role.invalid",
+      message: `Replay role must be 'user' or 'assistant', received '${String(turn.role)}'.`,
+      index
+    });
+  }
+  if (!isReplaySource(turn.source)) {
+    issues.push({
+      code: "turn.source.invalid",
+      message: `Replay source must be 'openclaw', 'claude', or 'chatgpt', received '${String(turn.source)}'.`,
+      index
+    });
+  }
+  if (!turn.sessionKey || typeof turn.sessionKey !== "string" || turn.sessionKey.trim().length === 0) {
+    issues.push({
+      code: "turn.sessionKey.invalid",
+      message: "Replay sessionKey is required.",
+      index
+    });
+  }
+  if (!turn.content || typeof turn.content !== "string" || turn.content.trim().length === 0) {
+    issues.push({
+      code: "turn.content.invalid",
+      message: "Replay content must be a non-empty string.",
+      index
+    });
+  }
+  if (!turn.timestamp || typeof turn.timestamp !== "string" || parseIsoTimestamp(turn.timestamp) === null) {
+    issues.push({
+      code: "turn.timestamp.invalid",
+      message: `Replay timestamp must be a valid ISO timestamp, received '${String(turn.timestamp)}'.`,
+      index
+    });
+  }
+  return issues;
+}
+
 // src/conversation-index/chunker.ts
 function chunkTranscriptEntries(sessionKey, entries, opts) {
   const maxChars = Math.max(500, opts.maxChars);
@@ -12056,10 +12131,22 @@ var Orchestrator = class _Orchestrator {
     while (this.queueProcessing || this.extractionQueue.length > 0) {
       if (Date.now() - started > timeoutMs) {
         log.warn(`waitForExtractionIdle timed out after ${timeoutMs}ms`);
-        return;
+        return false;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    return true;
+  }
+  async waitForConsolidationIdle(timeoutMs = 6e4) {
+    const started = Date.now();
+    while (this.consolidationInFlight) {
+      if (Date.now() - started > timeoutMs) {
+        log.warn(`waitForConsolidationIdle timed out after ${timeoutMs}ms`);
+        return false;
       }
       await new Promise((resolve) => setTimeout(resolve, 50));
     }
+    return true;
   }
   async getStorage(namespace) {
     const ns = namespace && namespace.length > 0 ? namespace : this.config.defaultNamespace;
@@ -13120,6 +13207,46 @@ _Context: ${topQuestion.context}_`);
     if (decision === "keep_buffering") return;
     await this.queueBufferedExtraction(this.buffer.getTurns(), "trigger_mode");
   }
+  async ingestReplayBatch(turns, options = {}) {
+    if (!Array.isArray(turns) || turns.length === 0) return;
+    const bySession = /* @__PURE__ */ new Map();
+    for (const turn of turns) {
+      if (turn.role !== "user" && turn.role !== "assistant") continue;
+      const key = normalizeReplaySessionKey(turn.sessionKey);
+      const list = bySession.get(key) ?? [];
+      list.push({
+        role: turn.role,
+        content: turn.content,
+        timestamp: turn.timestamp,
+        sessionKey: key
+      });
+      bySession.set(key, list);
+    }
+    const replayTasks = [];
+    for (const sessionTurns of bySession.values()) {
+      if (sessionTurns.length === 0) continue;
+      replayTasks.push(
+        new Promise((resolve, reject) => {
+          void this.queueBufferedExtraction(sessionTurns, "trigger_mode", {
+            skipDedupeCheck: true,
+            clearBufferAfterExtraction: false,
+            skipCharThreshold: true,
+            extractionDeadlineMs: options.deadlineMs,
+            onTaskSettled: (err) => err ? reject(err) : resolve()
+          }).catch(reject);
+        })
+      );
+    }
+    if (replayTasks.length > 0) {
+      const settled = await Promise.allSettled(replayTasks);
+      const firstRejected = settled.find(
+        (result) => result.status === "rejected"
+      );
+      if (firstRejected) {
+        throw firstRejected.reason;
+      }
+    }
+  }
   async observeSessionHeartbeat(sessionKey) {
     if (this.config.sessionObserverEnabled !== true) return;
     if (!sessionKey || sessionKey.length === 0) return;
@@ -13160,10 +13287,21 @@ _Context: ${topQuestion.context}_`);
   async queueBufferedExtraction(turnsToExtract, reason, options = {}) {
     if (!options.skipDedupeCheck && !this.shouldQueueExtraction(turnsToExtract)) {
       log.debug(`extraction dedupe skip: preserving buffer (${reason})`);
+      options.onTaskSettled?.();
       return;
     }
     this.extractionQueue.push(async () => {
-      await this.runExtraction(turnsToExtract);
+      try {
+        await this.runExtraction(turnsToExtract, {
+          clearBufferAfterExtraction: options.clearBufferAfterExtraction ?? true,
+          skipCharThreshold: options.skipCharThreshold ?? false,
+          deadlineMs: options.extractionDeadlineMs
+        });
+        options.onTaskSettled?.();
+      } catch (err) {
+        options.onTaskSettled?.(err);
+        throw err;
+      }
     });
     if (!this.queueProcessing) {
       this.queueProcessing = true;
@@ -13217,25 +13355,41 @@ _Context: ${topQuestion.context}_`);
     }
     this.queueProcessing = false;
   }
-  async runExtraction(turns) {
+  async runExtraction(turns, options = {}) {
     log.debug(`running extraction on ${turns.length} turns`);
+    const clearBufferAfterExtraction = options.clearBufferAfterExtraction ?? true;
+    const skipCharThreshold = options.skipCharThreshold ?? false;
+    const deadlineMs = typeof options.deadlineMs === "number" && Number.isFinite(options.deadlineMs) ? options.deadlineMs : void 0;
+    const throwIfDeadlineExceeded = (stage) => {
+      if (typeof deadlineMs === "number" && Date.now() > deadlineMs) {
+        throw new Error(`replay extraction deadline exceeded (${stage})`);
+      }
+    };
+    const clearBuffer = async () => {
+      if (clearBufferAfterExtraction) {
+        await this.buffer.clearAfterExtraction();
+      }
+    };
     const sessionKey = turns[0]?.sessionKey ?? "";
     if (sessionKey.includes(":cron:")) {
       log.debug(`skipping extraction for cron session: ${sessionKey}`);
-      await this.buffer.clearAfterExtraction();
+      await clearBuffer();
       return;
     }
     const normalizedTurns = turns.filter((t) => (t.role === "user" || t.role === "assistant") && typeof t.content === "string").map((t) => ({
       ...t,
       content: t.content.trim().slice(0, this.config.extractionMaxTurnChars)
     })).filter((t) => t.content.length > 0);
+    throwIfDeadlineExceeded("before_extract");
     const userTurns = normalizedTurns.filter((t) => t.role === "user");
     const totalChars = normalizedTurns.reduce((sum, t) => sum + t.content.length, 0);
-    if (totalChars < this.config.extractionMinChars || userTurns.length < this.config.extractionMinUserTurns) {
+    const belowCharThreshold = totalChars < this.config.extractionMinChars;
+    const belowUserTurnThreshold = userTurns.length < this.config.extractionMinUserTurns;
+    if (!skipCharThreshold && belowCharThreshold || belowUserTurnThreshold) {
       log.debug(
         `skipping extraction: below threshold (totalChars=${totalChars}, userTurns=${userTurns.length})`
       );
-      await this.buffer.clearAfterExtraction();
+      await clearBuffer();
       return;
     }
     const principal = resolvePrincipal(sessionKey, this.config);
@@ -13243,19 +13397,20 @@ _Context: ${topQuestion.context}_`);
     const storage = await this.storageRouter.storageFor(selfNamespace);
     const existingEntities = await storage.listEntityNames();
     const result = await this.extraction.extract(normalizedTurns, existingEntities);
+    throwIfDeadlineExceeded("before_persist");
     if (!result) {
       log.warn("runExtraction: extraction returned null/undefined");
-      await this.buffer.clearAfterExtraction();
+      await clearBuffer();
       return;
     }
     if (!Array.isArray(result.facts)) {
       log.warn("runExtraction: extraction returned invalid facts (not an array)", { factsType: typeof result.facts, resultKeys: Object.keys(result) });
-      await this.buffer.clearAfterExtraction();
+      await clearBuffer();
       return;
     }
     if (result.facts.length === 0 && result.entities.length === 0 && result.questions.length === 0 && result.profileUpdates.length === 0) {
       log.debug("runExtraction: extraction produced no durable outputs; skipping persistence");
-      await this.buffer.clearAfterExtraction();
+      await clearBuffer();
       return;
     }
     let threadIdForExtraction = null;
@@ -13268,7 +13423,7 @@ _Context: ${topQuestion.context}_`);
       }
     }
     const persistedIds = await this.persistExtraction(result, storage, threadIdForExtraction);
-    await this.buffer.clearAfterExtraction();
+    await clearBuffer();
     if (this.config.memoryBoxesEnabled && persistedIds.length > 0) {
       const extractionTopics = deriveTopicsFromExtraction(result);
       await this.boxBuilderFor(storage).onExtraction({
@@ -16666,6 +16821,471 @@ async function detectImportFormat(fromPath) {
   return null;
 }
 
+// src/replay/runner.ts
+function clampNonNegativeInt(value, defaultValue) {
+  if (!Number.isFinite(value)) return defaultValue;
+  return Math.max(0, Math.floor(value));
+}
+function clampBatchSize(value) {
+  const parsed = clampNonNegativeInt(value, 100);
+  if (parsed < 1) return 1;
+  return Math.min(parsed, 1e3);
+}
+function toWarning(issue) {
+  return {
+    code: issue.code,
+    message: issue.message,
+    index: issue.index
+  };
+}
+function inDateRange(turn, fromTs, toTs) {
+  const turnTs = parseIsoTimestamp(turn.timestamp);
+  if (turnTs === null) return false;
+  if (fromTs !== null && turnTs < fromTs) return false;
+  if (toTs !== null && turnTs > toTs) return false;
+  return true;
+}
+function buildReplayNormalizerRegistry(normalizers) {
+  const registry = {};
+  for (const normalizer of normalizers) {
+    if (!normalizer?.source) {
+      throw new Error("replay normalizer source is required");
+    }
+    if (registry[normalizer.source]) {
+      throw new Error(`duplicate replay normalizer for source '${normalizer.source}'`);
+    }
+    registry[normalizer.source] = normalizer;
+  }
+  return registry;
+}
+async function runReplay(source, input, registry, handlers = {}, options = {}) {
+  const normalizer = registry[source];
+  if (!normalizer) {
+    throw new Error(`missing replay normalizer for source '${source}'`);
+  }
+  return runReplayWithNormalizer(normalizer, input, handlers, options);
+}
+async function runReplayWithNormalizer(normalizer, input, handlers = {}, options = {}) {
+  const parseResult = await normalizer.parse(input, options);
+  if (!parseResult || typeof parseResult !== "object") {
+    throw new Error(`replay normalizer '${normalizer.source}' returned invalid parse result object`);
+  }
+  if (!Array.isArray(parseResult.turns)) {
+    throw new Error(`replay normalizer '${normalizer.source}' returned invalid parse result: turns must be an array`);
+  }
+  if (parseResult.warnings != null && !Array.isArray(parseResult.warnings)) {
+    throw new Error(`replay normalizer '${normalizer.source}' returned invalid parse result: warnings must be an array`);
+  }
+  const warnings = [...parseResult.warnings ?? []];
+  const parsedTurns = parseResult.turns;
+  const validTurns = [];
+  let invalidTurns = 0;
+  for (let i = 0; i < parsedTurns.length; i += 1) {
+    const turn = parsedTurns[i];
+    const issues = validateReplayTurn(turn, i);
+    if (issues.length === 0 && turn.source !== normalizer.source) {
+      issues.push({
+        code: "turn.source.mismatch",
+        message: `Replay turn source '${turn.source}' does not match normalizer source '${normalizer.source}'.`,
+        index: i
+      });
+    }
+    if (issues.length > 0) {
+      invalidTurns += 1;
+      for (const issue of issues) warnings.push(toWarning(issue));
+      continue;
+    }
+    validTurns.push(turn);
+  }
+  const sorted = [...validTurns].sort((a, b) => {
+    const left = parseIsoTimestamp(a.timestamp) ?? 0;
+    const right = parseIsoTimestamp(b.timestamp) ?? 0;
+    return left - right;
+  });
+  const fromTs = options.from ? parseIsoTimestamp(options.from) : null;
+  const toTs = options.to ? parseIsoTimestamp(options.to) : null;
+  if (options.from && fromTs === null) {
+    throw new Error(`invalid replay --from timestamp '${options.from}'`);
+  }
+  if (options.to && toTs === null) {
+    throw new Error(`invalid replay --to timestamp '${options.to}'`);
+  }
+  if (fromTs !== null && toTs !== null && fromTs > toTs) {
+    throw new Error("invalid replay date range: --from is after --to");
+  }
+  const ranged = sorted.filter((turn) => inDateRange(turn, fromTs, toTs));
+  const filteredByDate = sorted.length - ranged.length;
+  const startOffset = clampNonNegativeInt(options.startOffset, 0);
+  const skippedByOffset = Math.min(startOffset, ranged.length);
+  const offsetApplied = ranged.slice(startOffset);
+  const maxTurns = clampNonNegativeInt(options.maxTurns, offsetApplied.length);
+  const selected = offsetApplied.slice(0, maxTurns);
+  const dryRun = options.dryRun === true;
+  const batchSize = clampBatchSize(options.batchSize);
+  let batchCount = 0;
+  if (!dryRun) {
+    for (let i = 0; i < selected.length; i += batchSize) {
+      const batch = selected.slice(i, i + batchSize);
+      batchCount += 1;
+      if (handlers.onBatch) await handlers.onBatch(batch);
+      if (handlers.onTurn) {
+        for (const turn of batch) {
+          await handlers.onTurn(turn);
+        }
+      }
+    }
+  } else if (selected.length > 0) {
+    batchCount = Math.ceil(selected.length / batchSize);
+  }
+  return {
+    source: normalizer.source,
+    parsedTurns: parsedTurns.length,
+    validTurns: sorted.length,
+    invalidTurns,
+    filteredByDate,
+    skippedByOffset,
+    processedTurns: selected.length,
+    batchCount,
+    dryRun,
+    nextOffset: startOffset + selected.length,
+    firstTimestamp: selected[0]?.timestamp,
+    lastTimestamp: selected[selected.length - 1]?.timestamp,
+    warnings
+  };
+}
+
+// src/replay/normalizers/shared.ts
+function normalizeReplayRole(value, options = {}) {
+  if (typeof value !== "string") return null;
+  const role = value.trim().toLowerCase();
+  if (isReplayRole(role)) return role;
+  if (options.userAliases?.includes(role) || role === "human") return "user";
+  if (options.assistantAliases?.includes(role) || role === "ai" || role === "model") return "assistant";
+  return null;
+}
+function normalizeReplayContent(value) {
+  if (typeof value === "string") {
+    const content = value.trim();
+    return content.length > 0 ? content : null;
+  }
+  if (Array.isArray(value)) {
+    const text = value.map((part) => typeof part === "string" ? part : "").join("\n").trim();
+    return text.length > 0 ? text : null;
+  }
+  if (value && typeof value === "object") {
+    const obj = value;
+    if (Array.isArray(obj.parts)) return normalizeReplayContent(obj.parts);
+    if (typeof obj.text === "string") return normalizeReplayContent(obj.text);
+  }
+  return null;
+}
+function normalizeReplayTimestamp(value, options = {}) {
+  const toIso = (millis) => {
+    if (!Number.isFinite(millis)) return null;
+    const date = new Date(millis);
+    if (!Number.isFinite(date.getTime())) return null;
+    try {
+      return date.toISOString();
+    } catch {
+      return null;
+    }
+  };
+  if (typeof value === "number" && Number.isFinite(value)) {
+    const millis = value > 1e12 ? value : value * 1e3;
+    return toIso(millis);
+  }
+  if (options.acceptDateObject && value instanceof Date && Number.isFinite(value.getTime())) {
+    return toIso(value.getTime());
+  }
+  if (typeof value !== "string") return null;
+  const raw = options.trimString === false ? value : value.trim();
+  if (raw.length === 0) return null;
+  return toIso(Date.parse(raw));
+}
+
+// src/replay/normalizers/chatgpt.ts
+function gatherConversations(input) {
+  if (Array.isArray(input)) {
+    return input.filter((item) => !!item && typeof item === "object");
+  }
+  if (!input || typeof input !== "object") return [];
+  const obj = input;
+  if (Array.isArray(obj.conversations)) {
+    return obj.conversations.filter((item) => !!item && typeof item === "object");
+  }
+  return [obj];
+}
+function extractFromMapping(conversation) {
+  const mapping = conversation.mapping;
+  if (!mapping || typeof mapping !== "object") return [];
+  const nodes = mapping;
+  const currentNodeId = typeof conversation.current_node === "string" ? conversation.current_node : null;
+  if (!currentNodeId || !nodes[currentNodeId] || typeof nodes[currentNodeId] !== "object") {
+    const loose = [];
+    for (const node of Object.values(nodes)) {
+      if (!node || typeof node !== "object") continue;
+      const nodeObj = node;
+      const message = nodeObj.message;
+      if (!message || typeof message !== "object") continue;
+      loose.push({
+        ...message,
+        _nodeId: typeof nodeObj.id === "string" ? nodeObj.id : void 0,
+        _nodeCreateTime: nodeObj.create_time
+      });
+    }
+    return loose;
+  }
+  const chain = [];
+  const seen = /* @__PURE__ */ new Set();
+  let cursor = currentNodeId;
+  while (cursor && !seen.has(cursor)) {
+    seen.add(cursor);
+    const node = nodes[cursor];
+    if (!node || typeof node !== "object") break;
+    const nodeObj = node;
+    const message = nodeObj.message;
+    if (message && typeof message === "object") {
+      chain.push({
+        ...message,
+        _nodeId: typeof nodeObj.id === "string" ? nodeObj.id : cursor,
+        _nodeCreateTime: nodeObj.create_time
+      });
+    }
+    cursor = typeof nodeObj.parent === "string" ? nodeObj.parent : null;
+  }
+  return chain.reverse();
+}
+var chatgptReplayNormalizer = {
+  source: "chatgpt",
+  parse(input, options = {}) {
+    let parsedInput = input;
+    if (typeof input === "string") {
+      try {
+        parsedInput = JSON.parse(input);
+      } catch {
+        parsedInput = [];
+      }
+    }
+    const warnings = [];
+    const turns = [];
+    const conversations = gatherConversations(parsedInput);
+    for (let i = 0; i < conversations.length; i += 1) {
+      const conversation = conversations[i];
+      const convIdRaw = conversation.id ?? conversation.conversation_id ?? conversation.uuid;
+      const hasSourceConversationId = typeof convIdRaw === "string" && convIdRaw.trim().length > 0;
+      const convId = hasSourceConversationId ? convIdRaw.trim() : `conv-${i + 1}`;
+      const sessionKey = `replay:chatgpt:${convId}`;
+      const fallbackSessionKey = options.defaultSessionKey?.trim() || sessionKey;
+      const messageRows = Array.isArray(conversation.messages) ? conversation.messages.filter((item) => !!item && typeof item === "object") : extractFromMapping(conversation);
+      for (let j = 0; j < messageRows.length; j += 1) {
+        const row = messageRows[j];
+        const role = normalizeReplayRole(
+          row.author?.role ?? row.role
+        );
+        const content = normalizeReplayContent(
+          row.content?.parts ?? row.content ?? row.text
+        );
+        const timestamp = normalizeReplayTimestamp(
+          row.create_time ?? row.timestamp ?? row._nodeCreateTime ?? row.created_at
+        );
+        if (!role || !content || !timestamp) {
+          const message = `Skipping invalid ChatGPT replay message at conversation ${i + 1}, index ${j}.`;
+          if (options.strict) throw new Error(message);
+          warnings.push({ code: "replay.chatgpt.message.invalid", message, index: j });
+          continue;
+        }
+        const externalIdRaw = row.id ?? row._nodeId;
+        turns.push({
+          source: "chatgpt",
+          sessionKey: hasSourceConversationId ? sessionKey : fallbackSessionKey,
+          role,
+          content,
+          timestamp,
+          externalId: typeof externalIdRaw === "string" ? externalIdRaw : void 0,
+          metadata: {
+            conversationId: convId,
+            conversationTitle: typeof conversation.title === "string" ? conversation.title : void 0
+          }
+        });
+      }
+    }
+    return { turns, warnings };
+  }
+};
+
+// src/replay/normalizers/claude.ts
+function gatherConversations2(input) {
+  if (Array.isArray(input)) return input.filter((item) => !!item && typeof item === "object");
+  if (!input || typeof input !== "object") return [];
+  const obj = input;
+  if (Array.isArray(obj.conversations)) {
+    return obj.conversations.filter((item) => !!item && typeof item === "object");
+  }
+  if (Array.isArray(obj.chat_messages) || Array.isArray(obj.messages)) {
+    return [obj];
+  }
+  return [];
+}
+var claudeReplayNormalizer = {
+  source: "claude",
+  parse(input, options = {}) {
+    let parsedInput = input;
+    if (typeof input === "string") {
+      try {
+        parsedInput = JSON.parse(input);
+      } catch {
+        parsedInput = [];
+      }
+    }
+    const warnings = [];
+    const turns = [];
+    const conversations = gatherConversations2(parsedInput);
+    for (let i = 0; i < conversations.length; i += 1) {
+      const conversation = conversations[i];
+      const convoIdRaw = conversation.uuid ?? conversation.id ?? conversation.conversation_id;
+      const hasSourceConversationId = typeof convoIdRaw === "string" && convoIdRaw.trim().length > 0;
+      const convoId = hasSourceConversationId ? convoIdRaw.trim() : `conv-${i + 1}`;
+      const sessionKey = `replay:claude:${convoId}`;
+      const fallbackSessionKey = options.defaultSessionKey?.trim() || sessionKey;
+      const messagesRaw = Array.isArray(conversation.chat_messages) ? conversation.chat_messages : Array.isArray(conversation.messages) ? conversation.messages : [];
+      for (let j = 0; j < messagesRaw.length; j += 1) {
+        const msg = messagesRaw[j];
+        if (!msg || typeof msg !== "object") {
+          warnings.push({
+            code: "replay.claude.message.invalid",
+            message: `Skipping malformed Claude message at conversation ${i + 1}, index ${j}.`,
+            index: j
+          });
+          continue;
+        }
+        const row = msg;
+        const role = normalizeReplayRole(
+          row.sender ?? row.role ?? row.author?.role
+        );
+        const content = normalizeReplayContent(row.text ?? row.content ?? row.message);
+        const timestamp = normalizeReplayTimestamp(
+          row.created_at ?? row.createdAt ?? row.updated_at ?? row.updatedAt ?? row.timestamp
+        );
+        if (!role || !content || !timestamp) {
+          const message = `Skipping invalid Claude replay message at conversation ${i + 1}, index ${j}.`;
+          if (options.strict) throw new Error(message);
+          warnings.push({ code: "replay.claude.message.invalid", message, index: j });
+          continue;
+        }
+        const externalIdRaw = row.uuid ?? row.id;
+        turns.push({
+          source: "claude",
+          sessionKey: hasSourceConversationId ? sessionKey : fallbackSessionKey,
+          role,
+          content,
+          timestamp,
+          externalId: typeof externalIdRaw === "string" ? externalIdRaw : void 0,
+          metadata: {
+            conversationId: convoId,
+            conversationName: typeof conversation.name === "string" ? conversation.name : void 0
+          }
+        });
+      }
+    }
+    return { turns, warnings };
+  }
+};
+
+// src/replay/normalizers/openclaw.ts
+function parseJsonl(raw, warnings) {
+  const out = [];
+  for (const [index, line] of raw.split("\n").entries()) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      out.push(JSON.parse(trimmed));
+    } catch {
+      warnings.push({
+        code: "replay.openclaw.jsonl.invalid_line",
+        message: `Skipping invalid JSONL line ${index + 1}.`,
+        index
+      });
+    }
+  }
+  return out;
+}
+function gatherCandidates(input, warnings) {
+  if (Array.isArray(input)) return input;
+  if (typeof input === "string") {
+    try {
+      return gatherCandidates(JSON.parse(input), warnings);
+    } catch {
+      return parseJsonl(input, warnings);
+    }
+  }
+  if (!input || typeof input !== "object") return [];
+  const obj = input;
+  if (Array.isArray(obj.turns)) return obj.turns;
+  if (Array.isArray(obj.entries)) return obj.entries;
+  if (Array.isArray(obj.messages)) return obj.messages;
+  if (Array.isArray(obj.records)) {
+    const rows = [];
+    for (const rec of obj.records) {
+      if (!rec || typeof rec !== "object") continue;
+      const record = rec;
+      const content = typeof record.content === "string" ? record.content : null;
+      if (!content) continue;
+      const path36 = typeof record.path === "string" ? record.path : "";
+      if (!path36.startsWith("transcripts/") && !path36.includes("/transcripts/")) continue;
+      rows.push(...parseJsonl(content, warnings));
+    }
+    return rows;
+  }
+  return [];
+}
+var openclawReplayNormalizer = {
+  source: "openclaw",
+  parse(input, options = {}) {
+    const warnings = [];
+    const rawTurns = gatherCandidates(input, warnings);
+    const turns = [];
+    const defaultSessionKey = options.defaultSessionKey?.trim() || "replay:openclaw:import";
+    for (let i = 0; i < rawTurns.length; i += 1) {
+      const raw = rawTurns[i];
+      if (!raw || typeof raw !== "object") {
+        warnings.push({
+          code: "replay.openclaw.turn.invalid",
+          message: "Skipping non-object replay turn.",
+          index: i
+        });
+        continue;
+      }
+      const row = raw;
+      const role = normalizeReplayRole(row.role ?? row.sender ?? row.author?.role, {
+        assistantAliases: ["bot"]
+      });
+      const content = normalizeReplayContent(row.content ?? row.text ?? row.message);
+      const timestamp = normalizeReplayTimestamp(
+        row.timestamp ?? row.createdAt ?? row.created_at ?? row.time ?? row.date,
+        { acceptDateObject: true }
+      );
+      if (!role || !content || !timestamp) {
+        const message = `Skipping invalid openclaw turn at index ${i}.`;
+        if (options.strict) throw new Error(message);
+        warnings.push({ code: "replay.openclaw.turn.invalid", message, index: i });
+        continue;
+      }
+      const sessionKeyRaw = row.sessionKey ?? row.session_key;
+      const sessionKey = typeof sessionKeyRaw === "string" && sessionKeyRaw.trim().length > 0 ? sessionKeyRaw.trim() : defaultSessionKey;
+      const externalIdRaw = row.turnId ?? row.turn_id ?? row.id;
+      turns.push({
+        source: "openclaw",
+        sessionKey,
+        role,
+        content,
+        timestamp,
+        externalId: typeof externalIdRaw === "string" ? externalIdRaw : void 0
+      });
+    }
+    return { turns, warnings };
+  }
+};
+
 // src/cli.ts
 function rankCandidateForKeep(a, b) {
   const aConfidence = typeof a.frontmatter.confidence === "number" ? a.frontmatter.confidence : 0;
@@ -16715,6 +17335,83 @@ function planExactDuplicateDeletions(memories) {
 function planAggressiveDuplicateDeletions(memories) {
   return buildDedupePlan(memories, (memory) => normalizeAggressiveBody(memory.content));
 }
+async function withTimeout(promise, timeoutMs, timeoutMessage) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+async function runReplayCliCommand(orchestrator, options) {
+  const extractionIdleTimeoutMs = Number.isFinite(options.extractionIdleTimeoutMs) ? Math.max(1e3, Math.floor(options.extractionIdleTimeoutMs)) : 15 * 6e4;
+  const inputRaw = await readFile23(options.inputPath, "utf-8");
+  const registry = buildReplayNormalizerRegistry([
+    openclawReplayNormalizer,
+    claudeReplayNormalizer,
+    chatgptReplayNormalizer
+  ]);
+  const ingestBatchSize = clampBatchSize(options.batchSize);
+  const turnsBySession = /* @__PURE__ */ new Map();
+  const ingestSessionChunk = async (sessionTurns) => {
+    const deadlineMs = Date.now() + extractionIdleTimeoutMs;
+    await withTimeout(
+      orchestrator.ingestReplayBatch(sessionTurns, { deadlineMs }),
+      extractionIdleTimeoutMs,
+      `replay extraction batch did not complete before timeout (${extractionIdleTimeoutMs}ms)`
+    );
+  };
+  const summary = await runReplay(
+    options.source,
+    inputRaw,
+    registry,
+    {
+      onBatch: async (batch) => {
+        for (const turn of batch) {
+          const key = normalizeReplaySessionKey(turn.sessionKey);
+          const turns = turnsBySession.get(key) ?? [];
+          turns.push(turn);
+          turnsBySession.set(key, turns);
+          while (turns.length >= ingestBatchSize) {
+            const chunk = turns.splice(0, ingestBatchSize);
+            await ingestSessionChunk(chunk);
+          }
+        }
+      }
+    },
+    {
+      from: options.from,
+      to: options.to,
+      dryRun: options.dryRun === true,
+      startOffset: options.startOffset,
+      maxTurns: options.maxTurns,
+      batchSize: options.batchSize,
+      defaultSessionKey: options.defaultSessionKey,
+      strict: options.strict
+    }
+  );
+  if (!summary.dryRun) {
+    for (const turns of turnsBySession.values()) {
+      if (turns.length === 0) continue;
+      await ingestSessionChunk(turns);
+    }
+    if (options.runConsolidation === true) {
+      const consolidationIdle = await orchestrator.waitForConsolidationIdle(extractionIdleTimeoutMs);
+      if (!consolidationIdle) {
+        throw new Error(
+          `replay consolidation did not become idle before timeout (${extractionIdleTimeoutMs}ms)`
+        );
+      }
+      await orchestrator.runConsolidationNow();
+    }
+  }
+  return summary;
+}
 async function getPluginVersion() {
   try {
     const pkgPath = new URL("../package.json", import.meta.url);
@@ -16945,6 +17642,60 @@ function registerCli(api, orchestrator) {
         });
         console.log("OK");
       });
+      cmd.command("replay").description("Import replay transcripts from external exports").option("--source <source>", "Replay source: openclaw|claude|chatgpt").option("--input <path>", "Path to replay export file").option("--from <iso>", "Inclusive lower bound timestamp (ISO UTC)").option("--to <iso>", "Inclusive upper bound timestamp (ISO UTC)").option("--dry-run", "Parse and validate only; do not enqueue extraction").option("--start-offset <n>", "Start replay at offset", "0").option("--max-turns <n>", "Maximum turns to process", "0").option("--batch-size <n>", "Replay ingestion batch size", "100").option("--default-session-key <key>", "Fallback session key when source session identifiers are missing").option("--strict", "Fail on invalid source rows").option("--run-consolidation", "Run consolidation after replay ingestion completes").option("--idle-timeout-ms <n>", "Extraction idle timeout per replay batch/final drain in milliseconds", "900000").action(async (...args) => {
+        const options = args[0] ?? {};
+        const sourceRaw = typeof options.source === "string" ? options.source.trim().toLowerCase() : "";
+        const inputPath = typeof options.input === "string" ? options.input.trim() : "";
+        if (!isReplaySource(sourceRaw)) {
+          console.log("Missing or invalid --source. Use one of: openclaw, claude, chatgpt.");
+          return;
+        }
+        if (inputPath.length === 0) {
+          console.log("Missing --input. Example: openclaw engram replay --source openclaw --input /tmp/replay.jsonl");
+          return;
+        }
+        const startOffset = parseInt(String(options.startOffset ?? "0"), 10);
+        const maxTurnsRaw = parseInt(String(options.maxTurns ?? "0"), 10);
+        const batchSize = parseInt(String(options.batchSize ?? "100"), 10);
+        const idleTimeoutMs = parseInt(String(options.idleTimeoutMs ?? "900000"), 10);
+        const summary = await runReplayCliCommand(orchestrator, {
+          source: sourceRaw,
+          inputPath,
+          from: typeof options.from === "string" ? options.from : void 0,
+          to: typeof options.to === "string" ? options.to : void 0,
+          dryRun: options.dryRun === true,
+          startOffset: Number.isFinite(startOffset) ? Math.max(0, startOffset) : 0,
+          maxTurns: Number.isFinite(maxTurnsRaw) && maxTurnsRaw > 0 ? maxTurnsRaw : void 0,
+          batchSize: Number.isFinite(batchSize) && batchSize > 0 ? batchSize : 100,
+          defaultSessionKey: typeof options.defaultSessionKey === "string" && options.defaultSessionKey.trim().length > 0 ? options.defaultSessionKey.trim() : void 0,
+          strict: options.strict === true,
+          runConsolidation: options.runConsolidation === true,
+          extractionIdleTimeoutMs: Number.isFinite(idleTimeoutMs) && idleTimeoutMs > 0 ? idleTimeoutMs : 9e5
+        });
+        console.log(`Replay source: ${summary.source}`);
+        console.log(`Parsed turns: ${summary.parsedTurns}`);
+        console.log(`Valid turns: ${summary.validTurns}`);
+        console.log(`Invalid turns: ${summary.invalidTurns}`);
+        console.log(`Filtered by date: ${summary.filteredByDate}`);
+        console.log(`Skipped by offset: ${summary.skippedByOffset}`);
+        console.log(`Processed turns: ${summary.processedTurns}`);
+        console.log(`Batches: ${summary.batchCount}`);
+        console.log(`Dry run: ${summary.dryRun ? "yes" : "no"}`);
+        console.log(`Next offset: ${summary.nextOffset}`);
+        if (summary.firstTimestamp) console.log(`First timestamp: ${summary.firstTimestamp}`);
+        if (summary.lastTimestamp) console.log(`Last timestamp: ${summary.lastTimestamp}`);
+        if (summary.warnings.length > 0) {
+          console.log(`Warnings (${summary.warnings.length}):`);
+          for (const warning of summary.warnings.slice(0, 20)) {
+            const idx = typeof warning.index === "number" ? ` @${warning.index}` : "";
+            console.log(`  - ${warning.code}${idx}: ${warning.message}`);
+          }
+          if (summary.warnings.length > 20) {
+            console.log(`  ... and ${summary.warnings.length - 20} more`);
+          }
+        }
+        console.log("OK");
+      });
       cmd.command("dedupe-exact").description("Delete exact duplicate memory entries (same body text), keeping highest-confidence/newest copy").option("--dry-run", "Show what would be deleted without deleting files").option("--namespace <ns>", "Namespace to dedupe (v3.0+, default: config defaultNamespace)", "").option("--qmd-sync", "Run QMD update/embed after deletions (default: off)").action(async (...args) => {
         const options = args[0] ?? {};
         const dryRun = options.dryRun === true;