@mastra/memory 1.14.0-alpha.1 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # @mastra/memory
 
+## 1.14.0
+
+### Minor Changes
+
+- Added usage data to ObserveHooks callbacks and standalone reflect() return. ([#15047](https://github.com/mastra-ai/mastra/pull/15047))
+
+  **ObserveHooks:** `onObservationEnd` and `onReflectionEnd` now receive a result object containing token usage from the underlying LLM call. This enables reliable usage tracking across all observation and reflection paths (sync, async buffered, and resource-scoped).
+
+  **Standalone reflect():** `reflect()` now returns `{ reflected, record, usage? }` so callers can capture token usage without hooks.
+
+  **Examples**
+
+  ```ts
+  // Via hooks
+  await memory.observe({
+    threadId,
+    messages,
+    hooks: {
+      onObservationEnd: ({ usage }) => {
+        // usage: { inputTokens, outputTokens, totalTokens }
+      },
+      onReflectionEnd: ({ usage }) => {
+        // usage: { inputTokens, outputTokens, totalTokens }
+      },
+    },
+  });
+
+  // Via standalone reflect()
+  const { reflected, usage } = await memory.reflect(threadId, resourceId);
+  ```
+
+  Existing callbacks that accept no arguments continue to work without changes.
+
+- Added tracing support to Memory operations (recall, save, delete, update working memory). When an `observabilityContext` is provided, Memory creates `MEMORY_OPERATION` spans that capture operation type, message counts, embedding token usage, and vector result counts. Tracing is fully opt-in — existing usage without `observabilityContext` is unaffected. ([#14305](https://github.com/mastra-ai/mastra/pull/14305))
+
+  **Example usage:**
+
+  ```typescript
+  import { Memory } from '@mastra/memory';
+  import { InMemoryStore } from '@mastra/core/storage';
+
+  const memory = new Memory({ storage: new InMemoryStore() });
+
+  // Pass observabilityContext to create observable spans
+  await memory.recall({
+    threadId: 'thread-1',
+    observabilityContext: { tracingContext: { currentSpan: parentSpan } },
+  });
+
+  await memory.saveMessages({
+    messages: [userMessage, assistantMessage],
+    observabilityContext: { tracingContext: { currentSpan: parentSpan } },
+  });
+  ```
+
+- Added per-record config overrides for observation and reflection thresholds in Observational Memory. Each thread can now have its own `messageTokens` and `observationTokens` thresholds that override the instance-level defaults, without requiring a process restart or cache invalidation. If no per-record override is set, the instance-level config is used as before. ([#15102](https://github.com/mastra-ai/mastra/pull/15102))
+
+### Patch Changes
+
+- Fixed observational memory buffering so sealed assistant chunks stay split instead of being merged back into one persisted message during long tool runs. ([#14995](https://github.com/mastra-ai/mastra/pull/14995))
+
+- Fixed recall() to hide dynamic system reminder messages by default, with includeSystemReminders available when callers need raw reminder history. ([#15100](https://github.com/mastra-ai/mastra/pull/15100))
+
+- Updated dependencies [[`f32b9e1`](https://github.com/mastra-ai/mastra/commit/f32b9e115a3c754d1c8cfa3f4256fba87b09cfb7), [`7d6f521`](https://github.com/mastra-ai/mastra/commit/7d6f52164d0cca099f0b07cb2bba334360f1c8ab), [`a50d220`](https://github.com/mastra-ai/mastra/commit/a50d220b01ecbc5644d489a3d446c3bd4ab30245), [`665477b`](https://github.com/mastra-ai/mastra/commit/665477bc104fd52cfef8e7610d7664781a70c220), [`4cc2755`](https://github.com/mastra-ai/mastra/commit/4cc2755a7194cb08720ff2ab4dffb4b4a5103dfd), [`ac7baf6`](https://github.com/mastra-ai/mastra/commit/ac7baf66ef1db15e03975ef4ebb02724f015a391), [`ed425d7`](https://github.com/mastra-ai/mastra/commit/ed425d78e7c66cbda8209fee910856f98c6c6b82), [`1371703`](https://github.com/mastra-ai/mastra/commit/1371703835080450ef3f9aea58059a95d0da2e5a), [`0df8321`](https://github.com/mastra-ai/mastra/commit/0df832196eeb2450ab77ce887e8553abdd44c5a6), [`98f8a8b`](https://github.com/mastra-ai/mastra/commit/98f8a8bdf5761b9982f3ad3acbe7f1cc3efa71f3), [`ba6f7e9`](https://github.com/mastra-ai/mastra/commit/ba6f7e9086d8281393f2acae60fda61de3bff1f9), [`7eb2596`](https://github.com/mastra-ai/mastra/commit/7eb25960d607e07468c9a10c5437abd2deaf1e9a), [`1805ddc`](https://github.com/mastra-ai/mastra/commit/1805ddc9c9b3b14b63749735a13c05a45af43a80), [`fff91cf`](https://github.com/mastra-ai/mastra/commit/fff91cf914de0e731578aacebffdeebef82f0440), [`61109b3`](https://github.com/mastra-ai/mastra/commit/61109b34feb0e38d54bee4b8ca83eb7345b1d557), [`33f1ead`](https://github.com/mastra-ai/mastra/commit/33f1eadfa19c86953f593478e5fa371093b33779)]:
+  - @mastra/core@1.23.0
+
+## 1.14.0-alpha.2
+
+### Minor Changes
+
+- Added tracing support to Memory operations (recall, save, delete, update working memory). When an `observabilityContext` is provided, Memory creates `MEMORY_OPERATION` spans that capture operation type, message counts, embedding token usage, and vector result counts. Tracing is fully opt-in — existing usage without `observabilityContext` is unaffected. ([#14305](https://github.com/mastra-ai/mastra/pull/14305))
+
+  **Example usage:**
+
+  ```typescript
+  import { Memory } from '@mastra/memory';
+  import { InMemoryStore } from '@mastra/core/storage';
+
+  const memory = new Memory({ storage: new InMemoryStore() });
+
+  // Pass observabilityContext to create observable spans
+  await memory.recall({
+    threadId: 'thread-1',
+    observabilityContext: { tracingContext: { currentSpan: parentSpan } },
+  });
+
+  await memory.saveMessages({
+    messages: [userMessage, assistantMessage],
+    observabilityContext: { tracingContext: { currentSpan: parentSpan } },
+  });
+  ```
+
+- Added per-record config overrides for observation and reflection thresholds in Observational Memory. Each thread can now have its own `messageTokens` and `observationTokens` thresholds that override the instance-level defaults, without requiring a process restart or cache invalidation. If no per-record override is set, the instance-level config is used as before. ([#15102](https://github.com/mastra-ai/mastra/pull/15102))
+
+### Patch Changes
+
+- Fixed recall() to hide dynamic system reminder messages by default, with includeSystemReminders available when callers need raw reminder history. ([#15100](https://github.com/mastra-ai/mastra/pull/15100))
+
+- Updated dependencies [[`ac7baf6`](https://github.com/mastra-ai/mastra/commit/ac7baf66ef1db15e03975ef4ebb02724f015a391), [`0df8321`](https://github.com/mastra-ai/mastra/commit/0df832196eeb2450ab77ce887e8553abdd44c5a6), [`61109b3`](https://github.com/mastra-ai/mastra/commit/61109b34feb0e38d54bee4b8ca83eb7345b1d557), [`33f1ead`](https://github.com/mastra-ai/mastra/commit/33f1eadfa19c86953f593478e5fa371093b33779)]:
+  - @mastra/core@1.23.0-alpha.8
+
 ## 1.14.0-alpha.1
 
 ### Minor Changes

package/dist/{chunk-FQGF36BE.js → chunk-GXDPND6K.js}

@@ -6258,6 +6258,47 @@ Async buffering is enabled by default \u2014 this opt-out is only needed when us
       }
     }
   }
+  /**
+   * Resolve the effective messageTokens for a record.
+   * Only explicit per-record overrides (stored under `_overrides`) win;
+   * the initial config snapshot written by getOrCreateRecord() is ignored
+   * so that later instance-level changes still take effect.
+   *
+   * Overrides that fall below the instance-level buffering floor
+   * (bufferTokens / absolute bufferActivation) are clamped to the
+   * instance threshold to preserve buffering invariants.
+   */
+  getEffectiveMessageTokens(record) {
+    const overrides = record.config?._overrides;
+    const recordTokens = overrides?.observation?.messageTokens;
+    if (recordTokens) {
+      const maxOverride = getMaxThreshold(recordTokens);
+      const bufferTokens = this.observationConfig.bufferTokens;
+      if (bufferTokens && maxOverride <= bufferTokens) {
+        return this.observationConfig.messageTokens;
+      }
+      const bufferActivation = this.observationConfig.bufferActivation;
+      if (bufferActivation && bufferActivation >= 1e3 && maxOverride <= bufferActivation) {
+        return this.observationConfig.messageTokens;
+      }
+      return recordTokens;
+    }
+    return this.observationConfig.messageTokens;
+  }
+  /**
+   * Resolve the effective reflection observationTokens for a record.
+   * Only explicit per-record overrides (stored under `_overrides`) win;
+   * the initial config snapshot is ignored so instance-level changes
+   * still take effect for existing records.
+   */
+  getEffectiveReflectionTokens(record) {
+    const overrides = record.config?._overrides;
+    const recordTokens = overrides?.reflection?.observationTokens;
+    if (recordTokens) {
+      return recordTokens;
+    }
+    return this.reflectionConfig.observationTokens;
+  }
   /**
    * Check whether the unobserved message tokens meet the observation threshold.
    */
@@ -6265,7 +6306,7 @@ Async buffering is enabled by default \u2014 this opt-out is only needed when us
     const { record, unobservedTokens, extraTokens = 0 } = opts;
     const pendingTokens = (record.pendingMessageTokens ?? 0) + unobservedTokens + extraTokens;
     const currentObservationTokens = record.observationTokenCount ?? 0;
-    const threshold = calculateDynamicThreshold(this.observationConfig.messageTokens, currentObservationTokens);
+    const threshold = calculateDynamicThreshold(this.getEffectiveMessageTokens(record), currentObservationTokens);
     return pendingTokens >= threshold;
   }
   /**
@@ -7414,7 +7455,7 @@ ${grouped}` : grouped;
       const projectedMessageRemoval = calculateProjectedMessageRemoval(
         bufferedChunks,
         this.observationConfig.bufferActivation ?? 1,
-        getMaxThreshold(this.observationConfig.messageTokens),
+        getMaxThreshold(this.getEffectiveMessageTokens(record)),
         pendingTokens
       );
       let obsBufferStatus = "idle";
@@ -7503,7 +7544,7 @@ ${grouped}` : grouped;
       otherThreadTokens = otherContext ? this.tokenCounter.countString(otherContext) : 0;
     }
     const pendingTokens = Math.max(0, contextWindowTokens + otherThreadTokens);
-    const threshold = calculateDynamicThreshold(this.observationConfig.messageTokens, currentObservationTokens);
+    const threshold = calculateDynamicThreshold(this.getEffectiveMessageTokens(record), currentObservationTokens);
     const bufferedChunks = getBufferedChunks(record);
     const bufferedChunkCount = bufferedChunks.length;
     const bufferedChunkTokens = bufferedChunks.reduce((sum, chunk) => sum + (chunk.messageTokens ?? 0), 0);
@@ -7520,11 +7561,12 @@ ${grouped}` : grouped;
       );
     }
     const shouldObserve = pendingTokens >= threshold;
-    const reflectThreshold = getMaxThreshold(this.reflectionConfig.observationTokens);
+    const reflectThreshold = getMaxThreshold(this.getEffectiveReflectionTokens(record));
     const shouldReflect = currentObservationTokens >= reflectThreshold;
     const canActivate = bufferedChunkCount > 0;
-    const isSharedBudget = typeof this.observationConfig.messageTokens !== "number";
-    const totalBudget = isSharedBudget ? this.observationConfig.messageTokens.max : 0;
+    const effectiveMessageTokens = this.getEffectiveMessageTokens(record);
+    const isSharedBudget = typeof effectiveMessageTokens !== "number";
+    const totalBudget = isSharedBudget ? effectiveMessageTokens.max : 0;
     const effectiveObservationTokensThreshold = isSharedBudget ? Math.max(totalBudget - threshold, 1e3) : reflectThreshold;
     const unbufferedPendingTokens = Math.max(0, pendingTokens - bufferedChunkTokens);
     return {
@@ -7839,7 +7881,7 @@ ${grouped}` : grouped;
     if (!freshChunks.length) {
       return { activated: false, record };
     }
-    const messageTokensThreshold = getMaxThreshold(this.observationConfig.messageTokens);
+    const messageTokensThreshold = getMaxThreshold(this.getEffectiveMessageTokens(freshRecord));
     const bufferActivation = this.observationConfig.bufferActivation ?? 0.7;
     const activationRatio = resolveActivationRatio(bufferActivation, messageTokensThreshold);
     const totalChunkMessageTokens = freshChunks.reduce((sum, c) => sum + (c.messageTokens ?? 0), 0);
@@ -7988,7 +8030,7 @@ ${grouped}` : grouped;
     await this.storage.setReflectingFlag(record.id, true);
     registerOp(record.id, "reflecting");
     try {
-      const reflectThreshold = getMaxThreshold(this.reflectionConfig.observationTokens);
+      const reflectThreshold = getMaxThreshold(this.getEffectiveReflectionTokens(record));
       const reflectResult = await this.reflector.call(
         record.activeObservations,
         prompt,
@@ -8033,6 +8075,34 @@ ${grouped}` : grouped;
     const ids = this.getStorageIds(threadId, resourceId);
     return this.storage.getObservationalMemory(ids.threadId, ids.resourceId);
   }
+  /**
+   * Update per-record config overrides for observation and/or reflection thresholds.
+   * The provided config is deep-merged into the record's `_overrides` key,
+   * so you only need to specify the fields you want to change.
+   *
+   * Overrides that violate buffering invariants (e.g. messageTokens below
+   * bufferTokens) are silently ignored at read time — the helpers fall back
+   * to the instance-level config.
+   *
+   * @example
+   * ```ts
+   * await om.updateRecordConfig('thread-1', undefined, {
+   *   observation: { messageTokens: 2000 },
+   *   reflection: { observationTokens: 8000 },
+   * });
+   * ```
+   */
+  async updateRecordConfig(threadId, resourceId, config) {
+    const ids = this.getStorageIds(threadId, resourceId);
+    const record = await this.storage.getObservationalMemory(ids.threadId, ids.resourceId);
+    if (!record) {
+      throw new Error(`No observational memory record found for thread ${ids.threadId}`);
+    }
+    await this.storage.updateObservationalMemoryConfig({
+      id: record.id,
+      config: { _overrides: config }
+    });
+  }
   /**
    * Get observation history (previous generations)
    */
@@ -8584,5 +8654,5 @@ function getObservationsAsOf(activeObservations, asOf) {
 }
 
 export { ModelByInputTokens, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, TokenCounter, buildObserverPrompt, buildObserverSystemPrompt, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, formatToolResultForObserver, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, resolveToolResultValue, stripEphemeralAnchorIds, stripObservationGroups, truncateStringByTokens, wrapInObservationGroup };
-//# sourceMappingURL=chunk-FQGF36BE.js.map
-//# sourceMappingURL=chunk-FQGF36BE.js.map
+//# sourceMappingURL=chunk-GXDPND6K.js.map
+//# sourceMappingURL=chunk-GXDPND6K.js.map