@mastra/memory 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @mastra/memory
 
+## 1.17.0
+
+### Minor Changes
+
+- Added opt-in temporal-gap markers for observational memory. When enabled via `observationalMemory.temporalMarkers: true`, the agent receives a `<system-reminder type="temporal-gap">` before any user message that arrives more than 10 minutes after the previous one, so it can anchor responses in real elapsed time. Markers are persisted, surfaced to the observer, and rendered by the MastraCode TUI on reload. ([#15605](https://github.com/mastra-ai/mastra/pull/15605))
+
+### Patch Changes
+
+- Fixed observer agent truncation that could cut UTF-16 surrogate pairs in half when formatting messages, tool results, or observation lines with emoji or other astral-plane characters. This produced lone surrogates that strict JSON parsers (including Anthropic's) reject with errors like `no low surrogate in string`, causing observer runs to fail. ([#15634](https://github.com/mastra-ai/mastra/pull/15634))
+
+- Updated dependencies [[`f112db1`](https://github.com/mastra-ai/mastra/commit/f112db179557ae9b5a0f1d25dc47f928d7d61cd9), [`21d9706`](https://github.com/mastra-ai/mastra/commit/21d970604d89eee970cbf8013d26d7551aff6ea5), [`0a0aa94`](https://github.com/mastra-ai/mastra/commit/0a0aa94729592e99885af2efb90c56aaada62247), [`ed07df3`](https://github.com/mastra-ai/mastra/commit/ed07df32a9d539c8261e892fc1bade783f5b41a6), [`01a7d51`](https://github.com/mastra-ai/mastra/commit/01a7d513493d21562f677f98550f7ceb165ba78c)]:
+  - @mastra/core@1.27.0
+
+## 1.17.0-alpha.0
+
+### Minor Changes
+
+- Added opt-in temporal-gap markers for observational memory. When enabled via `observationalMemory.temporalMarkers: true`, the agent receives a `<system-reminder type="temporal-gap">` before any user message that arrives more than 10 minutes after the previous one, so it can anchor responses in real elapsed time. Markers are persisted, surfaced to the observer, and rendered by the MastraCode TUI on reload. ([#15605](https://github.com/mastra-ai/mastra/pull/15605))
+
+### Patch Changes
+
+- Fixed observer agent truncation that could cut UTF-16 surrogate pairs in half when formatting messages, tool results, or observation lines with emoji or other astral-plane characters. This produced lone surrogates that strict JSON parsers (including Anthropic's) reject with errors like `no low surrogate in string`, causing observer runs to fail. ([#15634](https://github.com/mastra-ai/mastra/pull/15634))
+
+- Updated dependencies [[`0a0aa94`](https://github.com/mastra-ai/mastra/commit/0a0aa94729592e99885af2efb90c56aaada62247), [`01a7d51`](https://github.com/mastra-ai/mastra/commit/01a7d513493d21562f677f98550f7ceb165ba78c)]:
+  - @mastra/core@1.27.0-alpha.1
+
 ## 1.16.0
 
 ### Minor Changes

package/dist/{chunk-HAUWGR76.cjs → chunk-5MTY2UYL.cjs}

@@ -385,6 +385,67 @@ ${gap}
   result += withInlineDates.slice(lastIndex);
   return result;
 }
+var MIN_TEMPORAL_GAP_MS = 10 * 60 * 1e3;
+function formatTemporalGap(diffMs) {
+  if (diffMs < MIN_TEMPORAL_GAP_MS) return null;
+  const minute = 60 * 1e3;
+  const hour = 60 * minute;
+  const day = 24 * hour;
+  const week = 7 * day;
+  const month = 30 * day;
+  const year = 365 * day;
+  const formatUnit = (value, unit) => `${value} ${unit}${value === 1 ? "" : "s"}`;
+  if (diffMs < hour) {
+    const minutes = Math.max(1, Math.round(diffMs / minute));
+    return `${formatUnit(minutes, "minute")} later`;
+  }
+  const formatTwoUnits = (primaryMs, primaryUnit, secondaryMs, secondaryUnit) => {
+    const primary = Math.floor(diffMs / primaryMs);
+    const remainder = diffMs - primary * primaryMs;
+    const secondary = Math.floor(remainder / secondaryMs);
+    const parts = [formatUnit(primary, primaryUnit)];
+    if (secondary > 0) {
+      parts.push(formatUnit(secondary, secondaryUnit));
+    }
+    return `${parts.join(" ")} later`;
+  };
+  if (diffMs < day) {
+    return formatTwoUnits(hour, "hour", minute, "minute");
+  }
+  if (diffMs < week) {
+    return formatTwoUnits(day, "day", hour, "hour");
+  }
+  if (diffMs < month) {
+    return formatTwoUnits(week, "week", day, "day");
+  }
+  if (diffMs < year) {
+    return formatTwoUnits(month, "month", week, "week");
+  }
+  return formatTwoUnits(year, "year", month, "month");
+}
+function formatTemporalTimestamp(date) {
+  return date.toLocaleString("en-US", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "numeric",
+    minute: "2-digit",
+    hour12: true,
+    timeZoneName: "short"
+  });
+}
+function getMessagePartTimestamp(msg, position) {
+  const timestamps = msg.content?.parts?.map((part) => "createdAt" in part ? part.createdAt : void 0).filter((timestamp) => typeof timestamp === "number");
+  if (timestamps && timestamps.length > 0) {
+    const index = position === "first" ? 0 : timestamps.length - 1;
+    const timestamp = timestamps[index];
+    if (timestamp !== void 0) return timestamp;
+  }
+  return new Date(msg.createdAt).getTime();
+}
+function isTemporalGapMarker(msg) {
+  return msg.id.startsWith("__temporal_");
+}
 
 // src/processors/observational-memory/markers.ts
 function createObservationStartMarker(params) {
@@ -2439,6 +2500,15 @@ function stripEphemeralAnchorIds(observations) {
   }
   return observations.replace(/(^|\n)([^\S\n]*)\[(O\d+(?:-N\d+)?)\][^\S\n]*/g, "$1$2");
 }
+
+// src/processors/observational-memory/string-utils.ts
+function safeSlice(str, end) {
+  if (end <= 0) return "";
+  if (end >= str.length) return str;
+  const code = str.charCodeAt(end - 1);
+  const safeEnd = code >= 55296 && code <= 56319 ? end - 1 : end;
+  return str.slice(0, safeEnd);
+}
 var ENCRYPTED_CONTENT_KEY = "encryptedContent";
 var ENCRYPTED_CONTENT_REDACTION_THRESHOLD = 256;
 var DEFAULT_OBSERVER_TOOL_RESULT_MAX_TOKENS = 1e4;
@@ -2504,7 +2574,7 @@ function truncateStringByTokens(text, maxTokens) {
     return text;
   }
   const buildCandidate = (sliceEnd) => {
-    const visible = text.slice(0, sliceEnd);
+    const visible = safeSlice(text, sliceEnd);
     return `${visible}
 ... [truncated ~${totalTokens - tokenx.estimateTokenCount(visible)} tokens]`;
   };
@@ -3058,8 +3128,11 @@ function formatObserverAttachmentPlaceholder(part, counter) {
   return label ? `[${attachmentType} #${attachmentId}: ${label}]` : `[${attachmentType} #${attachmentId}]`;
 }
 function formatObserverPartLine(title, body, time, previousTime) {
-  const timeLabel = time && time !== previousTime ? ` (${time})` : "";
-  return `${title}${timeLabel}: ${body}`;
+  const timeLabel = time && time !== previousTime ? `(${time})` : "";
+  if (!title) {
+    return timeLabel ? `${timeLabel}: ${body}` : body;
+  }
+  return `${title}${timeLabel ? ` ${timeLabel}` : ""}: ${body}`;
 }
 function normalizeObserverCreatedAt(createdAt) {
   if (createdAt instanceof Date) {
@@ -3095,6 +3168,16 @@ function formatObserverLines(lines, context = {}) {
     context: { previousDate, previousTime }
   };
 }
+function getTemporalGapMarkerText(msg) {
+  const metadata = typeof msg.content === "object" && msg.content && "metadata" in msg.content ? msg.content.metadata : void 0;
+  if (metadata?.reminderType === "temporal-gap" && typeof metadata.gapText === "string") {
+    return metadata.gapText;
+  }
+  if (typeof metadata?.systemReminder === "object" && metadata.systemReminder && "type" in metadata.systemReminder && metadata.systemReminder.type === "temporal-gap" && "gapText" in metadata.systemReminder && typeof metadata.systemReminder.gapText === "string") {
+    return metadata.systemReminder.gapText;
+  }
+  return void 0;
+}
 function formatObserverMessage(msg, counter, options) {
   const maxLen = options?.maxPartLength;
   const maxToolResultTokens = options?.maxToolResultTokens ?? DEFAULT_OBSERVER_TOOL_RESULT_MAX_TOKENS;
@@ -3102,6 +3185,7 @@ function formatObserverMessage(msg, counter, options) {
   const attachments = [];
   const messageCreatedAt = normalizeObserverCreatedAt(msg.createdAt);
   let lines = [];
+  const temporalGapText = isTemporalGapMarker(msg) ? getTemporalGapMarkerText(msg) : void 0;
   const pushLine = (title, body, createdAt) => {
     if (!body) {
       return;
@@ -3114,7 +3198,9 @@ function formatObserverMessage(msg, counter, options) {
       body
     });
   };
-  if (typeof msg.content === "string") {
+  if (temporalGapText) {
+    pushLine("", temporalGapText, messageCreatedAt);
+  } else if (typeof msg.content === "string") {
     pushLine(role, maybeTruncate(msg.content, maxLen), messageCreatedAt);
   } else if (msg.content?.parts && Array.isArray(msg.content.parts) && msg.content.parts.length > 0) {
     msg.content.parts.forEach((part) => {
@@ -3215,8 +3301,8 @@ function buildObserverHistoryMessage(messages, options) {
 }
 function maybeTruncate(str, maxLen) {
   if (!maxLen || str.length <= maxLen) return str;
-  const truncated = str.slice(0, maxLen);
-  const remaining = str.length - maxLen;
+  const truncated = safeSlice(str, maxLen);
+  const remaining = str.length - truncated.length;
   return `${truncated}
 ... [truncated ${remaining} characters]`;
 }
@@ -3520,7 +3606,7 @@ function sanitizeObservationLines(observations) {
   let changed = false;
   for (let i = 0; i < lines.length; i++) {
     if (lines[i].length > MAX_OBSERVATION_LINE_CHARS) {
-      lines[i] = lines[i].slice(0, MAX_OBSERVATION_LINE_CHARS) + " \u2026 [truncated]";
+      lines[i] = safeSlice(lines[i], MAX_OBSERVATION_LINE_CHARS) + " \u2026 [truncated]";
       changed = true;
     }
   }
@@ -8859,6 +8945,110 @@ ${grouped}` : grouped;
     });
   }
 };
+
+// src/processors/observational-memory/temporal-markers.ts
+var TEMPORAL_GAP_REMINDER_TYPE = "temporal-gap";
+function getTemporalGapReminderText(gapText, timestamp) {
+  return `${gapText} \u2014 ${formatTemporalTimestamp(new Date(timestamp))}`;
+}
+function getTemporalGapReminderMetadata(message, gapText, gapMs, timestamp) {
+  const formattedTimestamp = formatTemporalTimestamp(new Date(timestamp));
+  return {
+    reminderType: TEMPORAL_GAP_REMINDER_TYPE,
+    gapText,
+    gapMs,
+    timestamp: formattedTimestamp,
+    timestampMs: timestamp,
+    precedesMessageId: message.id,
+    systemReminder: {
+      type: TEMPORAL_GAP_REMINDER_TYPE,
+      message: getTemporalGapReminderText(gapText, timestamp),
+      gapText,
+      gapMs,
+      timestamp: formattedTimestamp,
+      timestampMs: timestamp,
+      precedesMessageId: message.id
+    }
+  };
+}
+function isTemporalGapMarkerForMessage(message, targetMessageId) {
+  if (!isTemporalGapMarker(message)) {
+    return false;
+  }
+  const metadata = message.content.metadata;
+  if (metadata?.precedesMessageId === targetMessageId) {
+    return true;
+  }
+  return metadata?.systemReminder?.type === TEMPORAL_GAP_REMINDER_TYPE && metadata.systemReminder.precedesMessageId === targetMessageId;
+}
+function createTemporalGapMarker(message, gapText, gapMs, timestamp) {
+  const metadata = getTemporalGapReminderMetadata(message, gapText, gapMs, timestamp);
+  return {
+    id: `__temporal_gap_${crypto.randomUUID()}`,
+    role: "user",
+    createdAt: new Date(timestamp - 1),
+    threadId: message.threadId,
+    resourceId: message.resourceId,
+    content: {
+      format: 2,
+      parts: [
+        {
+          type: "text",
+          text: `<system-reminder type="${TEMPORAL_GAP_REMINDER_TYPE}" precedesMessageId="${message.id}">${getTemporalGapReminderText(gapText, timestamp)}</system-reminder>`
+        }
+      ],
+      metadata
+    }
+  };
+}
+async function insertTemporalGapMarkers({
+  messageList,
+  writer
+}) {
+  const inputMessages = messageList.get.input.db().filter((message) => Boolean(message));
+  const latestInputMessage = inputMessages.at(-1);
+  if (!latestInputMessage || isTemporalGapMarker(latestInputMessage)) {
+    return;
+  }
+  const allMessages = messageList.get.all.db().filter((message) => Boolean(message));
+  const latestInputIndex = allMessages.findIndex((message) => message.id === latestInputMessage.id);
+  if (latestInputIndex <= 0) {
+    return;
+  }
+  if (allMessages.some((message) => isTemporalGapMarkerForMessage(message, latestInputMessage.id))) {
+    return;
+  }
+  let previousNonMarker;
+  for (let index = latestInputIndex - 1; index >= 0; index--) {
+    const candidate = allMessages[index];
+    if (candidate && !isTemporalGapMarker(candidate)) {
+      previousNonMarker = candidate;
+      break;
+    }
+  }
+  if (!previousNonMarker) {
+    return;
+  }
+  const timestamp = getMessagePartTimestamp(latestInputMessage, "first");
+  const gapMs = timestamp - getMessagePartTimestamp(previousNonMarker, "last");
+  const gapText = formatTemporalGap(gapMs);
+  if (!gapText) {
+    return;
+  }
+  const reminderMetadata = getTemporalGapReminderMetadata(latestInputMessage, gapText, gapMs, timestamp);
+  await writer?.custom({
+    type: "data-system-reminder",
+    data: {
+      message: getTemporalGapReminderText(gapText, timestamp),
+      ...reminderMetadata
+    },
+    transient: true
+  });
+  const marker = createTemporalGapMarker(latestInputMessage, gapText, gapMs, timestamp);
+  messageList.add(marker, "input");
+}
+
+// src/processors/observational-memory/processor.ts
 function getOmObservabilityContext(args) {
   if (!args.tracing || !args.tracingContext || !args.loggerVNext || !args.metrics) {
     return void 0;
@@ -8881,11 +9071,14 @@ var ObservationalMemoryProcessor = class {
   engine;
   /** Memory instance for loading context. */
   memory;
+  /** Whether temporal-gap reminder markers should be inserted. */
+  temporalMarkers;
   /** Active turn — created on first processInputStep, ended on processOutputResult. */
   turn;
-  constructor(engine, memory) {
+  constructor(engine, memory, options) {
     this.engine = engine;
     this.memory = memory;
+    this.temporalMarkers = options?.temporalMarkers ?? false;
   }
   // ─── Processor lifecycle hooks ──────────────────────────────────────────
   async processInputStep(args) {
@@ -8944,6 +9137,9 @@ var ObservationalMemoryProcessor = class {
         this.turn.writer = writer;
         this.turn.requestContext = requestContext;
         await this.turn.start(this.memory);
+        if (stepNumber === 0 && this.temporalMarkers) {
+          await insertTemporalGapMarkers({ messageList, writer });
+        }
         state.__omTurn = this.turn;
       }
       const observabilityContext = getOmObservabilityContext(args);
@@ -9108,5 +9304,5 @@ exports.stripEphemeralAnchorIds = stripEphemeralAnchorIds;
 exports.stripObservationGroups = stripObservationGroups;
 exports.truncateStringByTokens = truncateStringByTokens;
 exports.wrapInObservationGroup = wrapInObservationGroup;
-//# sourceMappingURL=chunk-HAUWGR76.cjs.map
-//# sourceMappingURL=chunk-HAUWGR76.cjs.map
+//# sourceMappingURL=chunk-5MTY2UYL.cjs.map
+//# sourceMappingURL=chunk-5MTY2UYL.cjs.map