@mastra/memory 1.5.2 → 1.6.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.5.2"
+  version: "1.6.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,70 +1,70 @@
 {
-  "version": "1.5.2",
+  "version": "1.6.0",
   "package": "@mastra/memory",
   "exports": {
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js"
+      "implementation": "dist/chunk-A62BQK35.js"
     },
     "OBSERVATION_CONTEXT_INSTRUCTIONS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js"
+      "implementation": "dist/chunk-A62BQK35.js"
     },
     "OBSERVATION_CONTEXT_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js"
+      "implementation": "dist/chunk-A62BQK35.js"
     },
     "OBSERVATION_CONTINUATION_HINT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js"
+      "implementation": "dist/chunk-A62BQK35.js"
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js"
+      "implementation": "dist/chunk-A62BQK35.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 1258
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 919
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 533
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 281
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 662
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 376
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 650
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 673
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-HNPAIFCZ.js",
+      "implementation": "dist/chunk-A62BQK35.js",
       "line": 564
     },
     "extractWorkingMemoryContent": {
@@ -96,7 +96,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-HNPAIFCZ.js"
+        "chunk-A62BQK35.js"
       ]
     }
   }

package/dist/docs/references/docs-memory-observational-memory.md

@@ -85,13 +85,11 @@ The result is a three-tier system:
 
 ## Models
 
-The Observer and Reflector run in the background. Any model that works with Mastra's model routing (e.g. `openai/...`, `google/...`, `deepseek/...`) can be used.
+The Observer and Reflector run in the background. Any model that works with Mastra's [model routing](https://mastra.ai/models) (`provider/model`) can be used. When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
 
-When using `observationalMemory: true`, the default model is `google/gemini-2.5-flash`. When passing a config object, a `model` must be explicitly set.
+Generally speaking, we recommend using a model that has a large context window (128K+ tokens) and is fast enough to run in the background without slowing down your actions.
 
-We recommend `google/gemini-2.5-flash` — it works well for both observation and reflection, and its 1M token context window gives the Reflector headroom.
-
-We've also tested `deepseek`, `qwen3`, and `glm-4.7` for the Observer. For the Reflector, make sure the model's context window can fit all observations. Note that Claude 4.5 models currently don't work well as observer or reflector.
+If you're unsure which model to use, start with the default `google/gemini-2.5-flash`. We've also successfully tested `openai/gpt-5-mini`, `anthropic/claude-haiku-4-5`, `deepseek/deepseek-reasoner`, `qwen3`, and `glm-4.7`.
 
 ```typescript
 const memory = new Memory({

package/dist/docs/references/reference-memory-cloneThread.md

@@ -44,6 +44,8 @@ const { thread, clonedMessages } = await memory.cloneThread({
 
 **clonedMessages:** (`MastraDBMessage[]`): Array of the cloned messages with new IDs assigned to the new thread.
 
+**messageIdMap?:** (`Record<string, string>`): A mapping from source message IDs to their corresponding cloned message IDs.
+
 ### Clone Metadata
 
 The cloned thread's metadata includes a `clone` property with:
@@ -127,4 +129,14 @@ const results = await memory.recall({
   threadId: thread.id,
   vectorSearchString: 'search query',
 })
-```
+```
+
+## Observational Memory
+
+When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, `cloneThread()` automatically clones the OM records associated with the source thread. The behavior depends on the OM scope:
+
+- **Thread-scoped OM**: The OM record is cloned to the new thread. All internal message ID references are remapped to point to the cloned messages.
+- **Resource-scoped OM (same `resourceId`)**: The OM record is shared between the source and cloned threads since they belong to the same resource. No duplication occurs.
+- **Resource-scoped OM (different `resourceId`)**: The OM record is cloned to the new resource. Message IDs are remapped and any thread-identifying tags within observations are updated to reference the cloned thread.
+
+Only the current (most recent) OM generation is cloned — older history generations are not copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.

package/dist/docs/references/reference-memory-observational-memory.md

@@ -107,6 +107,8 @@ export const agent = new Agent({
 
 ### Shared token budget
 
+When `shareTokenBudget` is enabled, the total budget is `observation.messageTokens + reflection.observationTokens` (100k in this example). If observations only use 30k tokens, messages can expand to use up to 70k. If messages are short, observations have more room before triggering reflection.
+
 ```typescript
 import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
@@ -132,10 +134,10 @@ export const agent = new Agent({
 })
 ```
 
-When `shareTokenBudget` is enabled, the total budget is `observation.messageTokens + reflection.observationTokens` (100k in this example). If observations only use 30k tokens, messages can expand to use up to 70k. If messages are short, observations have more room before triggering reflection.
-
 ### Custom model
 
+By passing a `model` in the config, you can use any model from Mastra's model router.
+
 ```typescript
 import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'

package/dist/index.cjs

@@ -15364,7 +15364,8 @@ var Memory = class extends memory.MastraMemory {
     const rawMessages = shouldGetNewestAndReverse ? paginatedResult.messages.reverse() : paginatedResult.messages;
     const list = new agent.MessageList({ threadId, resourceId }).add(rawMessages, "memory");
     const messages = list.get.all.db();
-    return { messages, usage };
+    const { total, page: resultPage, perPage: resultPerPage, hasMore } = paginatedResult;
+    return { messages, usage, total, page: resultPage, perPage: resultPerPage, hasMore };
   }
   async getThreadById({ threadId }) {
     const memoryStore = await this.getMemoryStore();
@@ -16119,13 +16120,10 @@ Notes:
     const memoryStore = await this.getMemoryStore();
     const result = await memoryStore.cloneThread(args);
     const config = this.getMergedThreadConfig(memoryConfig);
-    if (this.vector && config.semanticRecall && result.clonedMessages.length > 0) {
-      await this.embedClonedMessages(result.clonedMessages, config);
-    }
+    const sourceThread = await this.getThreadById({ threadId: args.sourceThreadId });
+    const sourceResourceId = sourceThread?.resourceId;
     if (config.workingMemory?.enabled) {
       const scope = config.workingMemory.scope || "resource";
-      const sourceThread = await this.getThreadById({ threadId: args.sourceThreadId });
-      const sourceResourceId = sourceThread?.resourceId;
       const shouldCopy = scope === "thread" || scope === "resource" && args.resourceId && args.resourceId !== sourceResourceId;
       if (shouldCopy) {
         const sourceWm = await this.getWorkingMemory({
@@ -16143,8 +16141,109 @@ Notes:
         }
       }
     }
+    if (memoryStore.supportsObservationalMemory && sourceResourceId) {
+      try {
+        await this.cloneObservationalMemory(memoryStore, args.sourceThreadId, sourceResourceId, result);
+      } catch (error) {
+        try {
+          await memoryStore.deleteThread({ threadId: result.thread.id });
+        } catch (rollbackError) {
+          this.logger.error("Failed to rollback cloned thread after OM clone failure", rollbackError);
+        }
+        throw error;
+      }
+    }
+    if (this.vector && config.semanticRecall && result.clonedMessages.length > 0) {
+      await this.embedClonedMessages(result.clonedMessages, config);
+    }
     return result;
   }
+  /**
+   * Clone observational memory records when cloning a thread.
+   * Thread-scoped: always cloned to the new thread.
+   * Resource-scoped: cloned only when the resourceId changes (same resourceId shares OM naturally).
+   * All stored message/thread IDs are remapped to the cloned IDs.
+   */
+  async cloneObservationalMemory(memoryStore, sourceThreadId, sourceResourceId, result) {
+    let sourceOM = await memoryStore.getObservationalMemory(sourceThreadId, sourceResourceId);
+    if (!sourceOM) {
+      sourceOM = await memoryStore.getObservationalMemory(null, sourceResourceId);
+    }
+    if (!sourceOM) return;
+    const clonedThreadId = result.thread.id;
+    const clonedResourceId = result.thread.resourceId;
+    const resourceChanged = clonedResourceId !== sourceResourceId;
+    if (sourceOM.scope === "resource" && !resourceChanged) return;
+    const messageIdMap = result.messageIdMap ?? {};
+    const hasher = await this.hasher;
+    const cloned = this.remapObservationalMemoryRecord(sourceOM, {
+      newThreadId: sourceOM.scope === "thread" ? clonedThreadId : null,
+      newResourceId: clonedResourceId,
+      messageIdMap,
+      sourceThreadId: resourceChanged ? sourceThreadId : void 0,
+      clonedThreadId: resourceChanged ? clonedThreadId : void 0,
+      hasher: resourceChanged ? hasher : void 0
+    });
+    const now = /* @__PURE__ */ new Date();
+    cloned.id = crypto.randomUUID();
+    cloned.createdAt = now;
+    cloned.updatedAt = now;
+    await memoryStore.insertObservationalMemoryRecord(cloned);
+  }
+  /**
+   * Create a remapped copy of an OM record with new thread/message IDs.
+   */
+  remapObservationalMemoryRecord(record, opts) {
+    const { newThreadId, newResourceId, messageIdMap, sourceThreadId, clonedThreadId, hasher } = opts;
+    const cloned = { ...record };
+    cloned.threadId = newThreadId;
+    cloned.resourceId = newResourceId;
+    if (Array.isArray(cloned.observedMessageIds)) {
+      cloned.observedMessageIds = cloned.observedMessageIds.map((id) => messageIdMap[id]).filter((id) => Boolean(id));
+    } else {
+      cloned.observedMessageIds = void 0;
+    }
+    if (Array.isArray(cloned.bufferedMessageIds)) {
+      cloned.bufferedMessageIds = cloned.bufferedMessageIds.map((id) => messageIdMap[id]).filter((id) => Boolean(id));
+    } else {
+      cloned.bufferedMessageIds = void 0;
+    }
+    if (Array.isArray(cloned.bufferedObservationChunks)) {
+      cloned.bufferedObservationChunks = cloned.bufferedObservationChunks.map(
+        (chunk) => ({
+          ...chunk,
+          messageIds: Array.isArray(chunk.messageIds) ? chunk.messageIds.map((id) => messageIdMap[id]).filter((id) => Boolean(id)) : []
+        })
+      );
+    } else {
+      cloned.bufferedObservationChunks = void 0;
+    }
+    if (sourceThreadId && clonedThreadId && hasher) {
+      const sourceObscured = hasher.h32ToString(sourceThreadId);
+      const clonedObscured = hasher.h32ToString(clonedThreadId);
+      if (sourceObscured !== clonedObscured) {
+        const replaceThreadTags = (text4) => {
+          if (!text4) return text4;
+          return text4.replaceAll(`<thread id="${sourceObscured}">`, `<thread id="${clonedObscured}">`);
+        };
+        cloned.activeObservations = replaceThreadTags(cloned.activeObservations) ?? "";
+        cloned.bufferedReflection = replaceThreadTags(cloned.bufferedReflection);
+        if (cloned.bufferedObservationChunks) {
+          cloned.bufferedObservationChunks = cloned.bufferedObservationChunks.map(
+            (chunk) => ({
+              ...chunk,
+              observations: replaceThreadTags(chunk.observations) ?? chunk.observations
+            })
+          );
+        }
+      }
+    }
+    cloned.isObserving = false;
+    cloned.isReflecting = false;
+    cloned.isBufferingObservation = false;
+    cloned.isBufferingReflection = false;
+    return cloned;
+  }
   /**
    * Embed cloned messages for semantic recall.
    * This is similar to the embedding logic in saveMessages but operates on already-saved messages.
@@ -16377,7 +16476,7 @@ Notes:
         "Observational memory async buffering is enabled by default but the installed version of @mastra/core does not support it. Either upgrade @mastra/core, @mastra/memory, and your storage adapter (@mastra/libsql, @mastra/pg, or @mastra/mongodb) to the latest version, or explicitly disable async buffering by setting `observation: { bufferTokens: false }` in your observationalMemory config."
       );
     }
-    const { ObservationalMemory } = await import('./observational-memory-Q47HN5YL.cjs');
+    const { ObservationalMemory } = await import('./observational-memory-MXI54VC7.cjs');
     return new ObservationalMemory({
       storage: memoryStore,
       scope: omConfig.scope,