@mastra/memory 1.14.0-alpha.1 → 1.14.0

package/dist/index.js

@@ -1,15 +1,16 @@
 import { __commonJS, require_token_error, __toESM } from './chunk-SVPZMV27.js';
 import { __commonJS as __commonJS$1, require_token_error as require_token_error$1, __toESM as __toESM$1 } from './chunk-RC6RZVYE.js';
-import { truncateStringByTokens, resolveToolResultValue, formatToolResultForObserver } from './chunk-FQGF36BE.js';
-export { ModelByInputTokens, getObservationsAsOf } from './chunk-FQGF36BE.js';
+import { truncateStringByTokens, resolveToolResultValue, formatToolResultForObserver } from './chunk-GXDPND6K.js';
+export { ModelByInputTokens, getObservationsAsOf } from './chunk-GXDPND6K.js';
 import { ZodFirstPartyTypeKind } from 'zod/v3';
 import { z } from 'zod';
 import * as z4 from 'zod/v4';
 import { z as z$1 } from 'zod/v4';
 import { MessageList } from '@mastra/core/agent';
 import { coreFeatures } from '@mastra/core/features';
-import { MastraMemory, removeWorkingMemoryTags, extractWorkingMemoryContent } from '@mastra/core/memory';
+import { MastraMemory, filterSystemReminderMessages, removeWorkingMemoryTags, extractWorkingMemoryContent } from '@mastra/core/memory';
 export { extractWorkingMemoryContent, extractWorkingMemoryTags, removeWorkingMemoryTags } from '@mastra/core/memory';
+import { EntityType, SpanType } from '@mastra/core/observability';
 import { generateEmptyFromSchema } from '@mastra/core/utils';
 import { isStandardSchemaWithJSON, toStandardSchema, standardSchemaToJSONSchema } from '@mastra/schema-compat/schema';
 import { Mutex } from 'async-mutex';
@@ -16599,94 +16600,149 @@ var Memory = class extends MastraMemory {
       );
     }
   }
+  createMemorySpan(operationType, observabilityContext, input, attributes) {
+    const currentSpan = observabilityContext?.tracingContext?.currentSpan;
+    if (!currentSpan) return void 0;
+    return currentSpan.createChildSpan({
+      type: SpanType.MEMORY_OPERATION,
+      name: `memory: ${operationType}`,
+      entityType: EntityType.MEMORY,
+      entityName: "Memory",
+      input,
+      attributes: { operationType, ...attributes }
+    });
+  }
   async recall(args) {
-    const { threadId, resourceId, perPage: perPageArg, page, orderBy, threadConfig, vectorSearchString, filter: filter3 } = args;
-    const config = this.getMergedThreadConfig(threadConfig || {});
-    if (resourceId) await this.validateThreadIsOwnedByResource(threadId, resourceId, config);
-    const perPage = perPageArg !== void 0 ? perPageArg : config.lastMessages;
-    const historyDisabledByConfig = config.lastMessages === false && perPageArg === void 0;
-    const shouldGetNewestAndReverse = !orderBy && perPage !== false;
-    const effectiveOrderBy = shouldGetNewestAndReverse ? { field: "createdAt", direction: "DESC" } : orderBy;
-    const vectorResults = [];
-    this.logger.debug("Memory recall", {
+    const {
       threadId,
-      perPage,
+      resourceId,
+      perPage: perPageArg,
       page,
-      orderBy: effectiveOrderBy,
-      hasWorkingMemorySchema: Boolean(config.workingMemory?.schema),
-      workingMemoryEnabled: config.workingMemory?.enabled,
-      semanticRecallEnabled: Boolean(config.semanticRecall),
-      historyDisabledByConfig
-    });
-    const defaultRange = DEFAULT_MESSAGE_RANGE;
-    const defaultTopK = DEFAULT_TOP_K;
-    const vectorConfig = typeof config?.semanticRecall === `boolean` ? {
-      topK: defaultTopK,
-      messageRange: defaultRange
-    } : {
-      topK: config?.semanticRecall?.topK ?? defaultTopK,
-      messageRange: config?.semanticRecall?.messageRange ?? defaultRange
-    };
-    const resourceScope = typeof config?.semanticRecall === "object" && config?.semanticRecall?.scope !== `thread` || config.semanticRecall === true;
-    if (resourceScope && !resourceId && config?.semanticRecall && vectorSearchString) {
-      throw new Error(
-        `Memory error: Resource-scoped semantic recall is enabled but no resourceId was provided. Either provide a resourceId or explicitly set semanticRecall.scope to 'thread'.`
-      );
-    }
-    let usage;
-    if (historyDisabledByConfig && (!config.semanticRecall || !vectorSearchString || !this.vector)) {
-      return { messages: [], usage: void 0, total: 0, page: page ?? 0, perPage: 0, hasMore: false };
-    }
-    if (config?.semanticRecall && vectorSearchString && this.vector) {
-      const result = await this.embedMessageContent(vectorSearchString);
-      usage = result.usage;
-      const { embeddings, dimension } = result;
-      const { indexName } = await this.createEmbeddingIndex(dimension, config);
-      await Promise.all(
-        embeddings.map(async (embedding) => {
-          if (typeof this.vector === `undefined`) {
-            throw new Error(
-              `Tried to query vector index ${indexName} but this Memory instance doesn't have an attached vector db.`
+      orderBy,
+      threadConfig,
+      vectorSearchString,
+      includeSystemReminders,
+      filter: filter3
+    } = args;
+    const config = this.getMergedThreadConfig(threadConfig || {});
+    const semanticRecallEnabled = Boolean(config.semanticRecall);
+    const span = this.createMemorySpan(
+      "recall",
+      args.observabilityContext,
+      { threadId, resourceId, vectorSearchString },
+      {
+        semanticRecallEnabled,
+        lastMessages: config.lastMessages
+      }
+    );
+    try {
+      if (resourceId) await this.validateThreadIsOwnedByResource(threadId, resourceId, config);
+      const perPage = perPageArg !== void 0 ? perPageArg : config.lastMessages;
+      const historyDisabledByConfig = config.lastMessages === false && perPageArg === void 0;
+      const shouldGetNewestAndReverse = !orderBy && perPage !== false;
+      const effectiveOrderBy = shouldGetNewestAndReverse ? { field: "createdAt", direction: "DESC" } : orderBy;
+      const vectorResults = [];
+      this.logger.debug("Memory recall", {
+        threadId,
+        perPage,
+        page,
+        orderBy: effectiveOrderBy,
+        hasWorkingMemorySchema: Boolean(config.workingMemory?.schema),
+        workingMemoryEnabled: config.workingMemory?.enabled,
+        semanticRecallEnabled,
+        historyDisabledByConfig
+      });
+      const defaultRange = DEFAULT_MESSAGE_RANGE;
+      const defaultTopK = DEFAULT_TOP_K;
+      const vectorConfig = typeof config?.semanticRecall === `boolean` ? {
+        topK: defaultTopK,
+        messageRange: defaultRange
+      } : {
+        topK: config?.semanticRecall?.topK ?? defaultTopK,
+        messageRange: config?.semanticRecall?.messageRange ?? defaultRange
+      };
+      const resourceScope = typeof config?.semanticRecall === "object" && config?.semanticRecall?.scope !== `thread` || config.semanticRecall === true;
+      if (resourceScope && !resourceId && config?.semanticRecall && vectorSearchString) {
+        throw new Error(
+          `Memory error: Resource-scoped semantic recall is enabled but no resourceId was provided. Either provide a resourceId or explicitly set semanticRecall.scope to 'thread'.`
+        );
+      }
+      let usage;
+      if (historyDisabledByConfig && (!config.semanticRecall || !vectorSearchString || !this.vector)) {
+        const result = {
+          messages: [],
+          usage: void 0,
+          total: 0,
+          page: page ?? 0,
+          perPage: 0,
+          hasMore: false
+        };
+        span?.end({ output: { success: true }, attributes: { messageCount: 0 } });
+        return result;
+      }
+      if (config?.semanticRecall && vectorSearchString && this.vector) {
+        const result = await this.embedMessageContent(vectorSearchString);
+        usage = result.usage;
+        const { embeddings, dimension } = result;
+        const { indexName } = await this.createEmbeddingIndex(dimension, config);
+        await Promise.all(
+          embeddings.map(async (embedding) => {
+            if (typeof this.vector === `undefined`) {
+              throw new Error(
+                `Tried to query vector index ${indexName} but this Memory instance doesn't have an attached vector db.`
+              );
+            }
+            vectorResults.push(
+              ...await this.vector.query({
+                indexName,
+                queryVector: embedding,
+                topK: vectorConfig.topK,
+                filter: resourceScope ? {
+                  resource_id: resourceId
+                } : {
+                  thread_id: threadId
+                }
+              })
             );
-          }
-          vectorResults.push(
-            ...await this.vector.query({
-              indexName,
-              queryVector: embedding,
-              topK: vectorConfig.topK,
-              filter: resourceScope ? {
-                resource_id: resourceId
-              } : {
-                thread_id: threadId
-              }
-            })
-          );
-        })
-      );
+          })
+        );
+      }
+      const memoryStore = await this.getMemoryStore();
+      const effectivePerPage = historyDisabledByConfig ? 0 : perPage;
+      const paginatedResult = await memoryStore.listMessages({
+        threadId,
+        resourceId,
+        perPage: effectivePerPage,
+        page,
+        orderBy: effectiveOrderBy,
+        filter: filter3,
+        ...vectorResults?.length ? {
+          include: vectorResults.map((r) => ({
+            id: r.metadata?.message_id,
+            threadId: r.metadata?.thread_id,
+            withNextMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.after,
+            withPreviousMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.before
+          }))
+        } : {}
+      });
+      const rawMessages = shouldGetNewestAndReverse ? paginatedResult.messages.reverse() : paginatedResult.messages;
+      const list = new MessageList({ threadId, resourceId }).add(rawMessages, "memory");
+      const messages = filterSystemReminderMessages(list.get.all.db(), includeSystemReminders);
+      const { total, page: resultPage, perPage: resultPerPage, hasMore } = paginatedResult;
+      const recallResult = { messages, usage, total, page: resultPage, perPage: resultPerPage, hasMore };
+      span?.end({
+        output: { success: true },
+        attributes: {
+          messageCount: messages.length,
+          embeddingTokens: usage?.tokens,
+          vectorResultCount: vectorResults.length
+        }
+      });
+      return recallResult;
+    } catch (error) {
+      span?.error({ error, endSpan: true });
+      throw error;
     }
-    const memoryStore = await this.getMemoryStore();
-    const effectivePerPage = historyDisabledByConfig ? 0 : perPage;
-    const paginatedResult = await memoryStore.listMessages({
-      threadId,
-      resourceId,
-      perPage: effectivePerPage,
-      page,
-      orderBy: effectiveOrderBy,
-      filter: filter3,
-      ...vectorResults?.length ? {
-        include: vectorResults.map((r) => ({
-          id: r.metadata?.message_id,
-          threadId: r.metadata?.thread_id,
-          withNextMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.after,
-          withPreviousMessages: typeof vectorConfig.messageRange === "number" ? vectorConfig.messageRange : vectorConfig.messageRange.before
-        }))
-      } : {}
-    });
-    const rawMessages = shouldGetNewestAndReverse ? paginatedResult.messages.reverse() : paginatedResult.messages;
-    const list = new MessageList({ threadId, resourceId }).add(rawMessages, "memory");
-    const messages = list.get.all.db();
-    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();
@@ -16796,45 +16852,60 @@ var Memory = class extends MastraMemory {
     threadId,
     resourceId,
     workingMemory,
-    memoryConfig
+    memoryConfig,
+    observabilityContext
   }) {
     const config = this.getMergedThreadConfig(memoryConfig || {});
     if (!config.workingMemory?.enabled) {
       throw new Error("Working memory is not enabled for this memory instance");
     }
-    const scope = config.workingMemory.scope || "resource";
-    if (scope === "resource" && !resourceId) {
-      throw new Error(
-        `Memory error: Resource-scoped working memory is enabled but no resourceId was provided. Either provide a resourceId or explicitly set workingMemory.scope to 'thread'.`
-      );
-    }
-    const mutexKey = scope === "resource" ? `resource-${resourceId}` : `thread-${threadId}`;
-    const mutex = this.updateWorkingMemoryMutexes.has(mutexKey) ? this.updateWorkingMemoryMutexes.get(mutexKey) : new Mutex();
-    this.updateWorkingMemoryMutexes.set(mutexKey, mutex);
-    const release = await mutex.acquire();
+    const span = this.createMemorySpan(
+      "update",
+      observabilityContext,
+      { threadId, resourceId },
+      {
+        workingMemoryEnabled: true
+      }
+    );
     try {
-      const memoryStore = await this.getMemoryStore();
-      if (scope === "resource" && resourceId) {
-        await memoryStore.updateResource({
-          resourceId,
-          workingMemory
-        });
-      } else {
-        const thread = await this.getThreadById({ threadId });
-        if (!thread) {
-          throw new Error(`Thread ${threadId} not found`);
-        }
-        await memoryStore.updateThread({
-          id: threadId,
-          title: thread.title || "",
-          metadata: {
-            ...thread.metadata,
+      const scope = config.workingMemory.scope || "resource";
+      if (scope === "resource" && !resourceId) {
+        throw new Error(
+          `Memory error: Resource-scoped working memory is enabled but no resourceId was provided. Either provide a resourceId or explicitly set workingMemory.scope to 'thread'.`
+        );
+      }
+      const mutexKey = scope === "resource" ? `resource-${resourceId}` : `thread-${threadId}`;
+      const mutex = this.updateWorkingMemoryMutexes.has(mutexKey) ? this.updateWorkingMemoryMutexes.get(mutexKey) : new Mutex();
+      this.updateWorkingMemoryMutexes.set(mutexKey, mutex);
+      const release = await mutex.acquire();
+      try {
+        const memoryStore = await this.getMemoryStore();
+        if (scope === "resource" && resourceId) {
+          await memoryStore.updateResource({
+            resourceId,
             workingMemory
+          });
+        } else {
+          const thread = await this.getThreadById({ threadId });
+          if (!thread) {
+            throw new Error(`Thread ${threadId} not found`);
           }
-        });
+          await memoryStore.updateThread({
+            id: threadId,
+            title: thread.title || "",
+            metadata: {
+              ...thread.metadata,
+              workingMemory
+            }
+          });
+        }
+      } finally {
+        release();
       }
-    } finally {
-      release();
+      span?.end({ output: { success: true } });
+    } catch (error) {
+      span?.error({ error, endSpan: true });
+      throw error;
     }
   }
   updateWorkingMemoryMutexes = /* @__PURE__ */ new Map();
@@ -17012,67 +17083,85 @@ ${workingMemory}`;
   }
   async saveMessages({
     messages,
-    memoryConfig
+    memoryConfig,
+    observabilityContext
   }) {
-    const updatedMessages = messages.map((m) => {
-      return this.updateMessageToHideWorkingMemoryV2(m);
-    }).filter((m) => Boolean(m));
-    const config = this.getMergedThreadConfig(memoryConfig);
-    const dbMessages = new MessageList({
-      generateMessageId: () => this.generateId()
-    }).add(updatedMessages, "memory").get.all.db();
-    const memoryStore = await this.getMemoryStore();
-    const result = await memoryStore.saveMessages({
-      messages: dbMessages
+    const span = this.createMemorySpan("save", observabilityContext, void 0, {
+      messageCount: messages.length
     });
-    let totalTokens = 0;
-    if (this.vector && config.semanticRecall) {
-      const embeddingData = [];
-      let dimension;
-      await Promise.all(
-        updatedMessages.map(async (message) => {
-          let textForEmbedding = null;
-          if (message.content.content && typeof message.content.content === "string" && message.content.content.trim() !== "") {
-            textForEmbedding = message.content.content;
-          } else if (message.content.parts && message.content.parts.length > 0) {
-            const joined = message.content.parts.filter((part) => part.type === "text").map((part) => part.text).join(" ").trim();
-            if (joined) textForEmbedding = joined;
+    try {
+      const updatedMessages = messages.map((m) => {
+        return this.updateMessageToHideWorkingMemoryV2(m);
+      }).filter((m) => Boolean(m));
+      const config = this.getMergedThreadConfig(memoryConfig);
+      const dbMessages = new MessageList({
+        generateMessageId: () => this.generateId()
+      }).add(updatedMessages, "memory").get.all.db();
+      const memoryStore = await this.getMemoryStore();
+      const result = await memoryStore.saveMessages({
+        messages: dbMessages
+      });
+      let totalTokens = 0;
+      if (this.vector && config.semanticRecall) {
+        const embeddingData = [];
+        let dimension;
+        await Promise.all(
+          updatedMessages.map(async (message) => {
+            let textForEmbedding = null;
+            if (message.content.content && typeof message.content.content === "string" && message.content.content.trim() !== "") {
+              textForEmbedding = message.content.content;
+            } else if (message.content.parts && message.content.parts.length > 0) {
+              const joined = message.content.parts.filter((part) => part.type === "text").map((part) => part.text).join(" ").trim();
+              if (joined) textForEmbedding = joined;
+            }
+            if (!textForEmbedding) return;
+            const result2 = await this.embedMessageContent(textForEmbedding);
+            dimension = result2.dimension;
+            if (result2.usage?.tokens) {
+              totalTokens += result2.usage.tokens;
+            }
+            embeddingData.push({
+              embeddings: result2.embeddings,
+              metadata: result2.chunks.map(() => ({
+                message_id: message.id,
+                thread_id: message.threadId,
+                resource_id: message.resourceId
+              }))
+            });
+          })
+        );
+        if (embeddingData.length > 0 && dimension !== void 0) {
+          if (typeof this.vector === `undefined`) {
+            throw new Error(`Tried to upsert embeddings but this Memory instance doesn't have an attached vector db.`);
           }
-          if (!textForEmbedding) return;
-          const result2 = await this.embedMessageContent(textForEmbedding);
-          dimension = result2.dimension;
-          if (result2.usage?.tokens) {
-            totalTokens += result2.usage.tokens;
+          const { indexName } = await this.createEmbeddingIndex(dimension, config);
+          const allVectors = [];
+          const allMetadata = [];
+          for (const data of embeddingData) {
+            allVectors.push(...data.embeddings);
+            allMetadata.push(...data.metadata);
           }
-          embeddingData.push({
-            embeddings: result2.embeddings,
-            metadata: result2.chunks.map(() => ({
-              message_id: message.id,
-              thread_id: message.threadId,
-              resource_id: message.resourceId
-            }))
+          await this.vector.upsert({
+            indexName,
+            vectors: allVectors,
+            metadata: allMetadata
           });
-        })
-      );
-      if (embeddingData.length > 0 && dimension !== void 0) {
-        if (typeof this.vector === `undefined`) {
-          throw new Error(`Tried to upsert embeddings but this Memory instance doesn't have an attached vector db.`);
-        }
-        const { indexName } = await this.createEmbeddingIndex(dimension, config);
-        const allVectors = [];
-        const allMetadata = [];
-        for (const data of embeddingData) {
-          allVectors.push(...data.embeddings);
-          allMetadata.push(...data.metadata);
         }
-        await this.vector.upsert({
-          indexName,
-          vectors: allVectors,
-          metadata: allMetadata
-        });
       }
+      const saveResult = { ...result, usage: totalTokens > 0 ? { tokens: totalTokens } : void 0 };
+      span?.end({
+        output: { success: true },
+        attributes: {
+          messageCount: dbMessages.length,
+          embeddingTokens: saveResult.usage?.tokens,
+          semanticRecallEnabled: Boolean(config.semanticRecall)
+        }
+      });
+      return saveResult;
+    } catch (error) {
+      span?.error({ error, endSpan: true });
+      throw error;
     }
-    return { ...result, usage: totalTokens > 0 ? { tokens: totalTokens } : void 0 };
   }
   updateMessageToHideWorkingMemoryV2(message) {
     const newMessage = { ...message };
@@ -17344,7 +17433,7 @@ ${workingMemory}`;
         "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
       );
     }
-    const { ObservationalMemory: OMClass } = await import('./observational-memory-JQ34KLFS.js');
+    const { ObservationalMemory: OMClass } = await import('./observational-memory-OVRHDQRG.js');
     const onIndexObservations = this.hasRetrievalSearch(omConfig.retrieval) ? async (observation) => {
       await this.indexObservation(observation);
     } : void 0;
@@ -17607,6 +17696,32 @@ Notes:
       }))
     });
   }
+  /**
+   * Update per-record observational memory config overrides for a thread.
+   * The provided config is deep-merged, so you only need to specify fields you want to change.
+   *
+   * @example
+   * ```ts
+   * await memory.updateObservationalMemoryConfig({
+   *   threadId: 'thread-1',
+   *   config: {
+   *     observation: { messageTokens: 2000 },
+   *     reflection: { observationTokens: 8000 },
+   *   },
+   * });
+   * ```
+   */
+  async updateObservationalMemoryConfig({
+    threadId,
+    resourceId,
+    config
+  }) {
+    const omEngine = await this.omEngine;
+    if (!omEngine) {
+      throw new Error("Observational memory is not enabled");
+    }
+    await omEngine.updateRecordConfig(threadId, resourceId, config);
+  }
   /**
    * Index a list of messages directly (without querying storage).
    * Used by observe-time indexing to vectorize newly-observed messages.
@@ -17780,7 +17895,7 @@ Notes:
    *   - Message objects with 'id' properties
    * @returns Promise that resolves when all messages are deleted
    */
-  async deleteMessages(input) {
+  async deleteMessages(input, observabilityContext) {
     let messageIds;
     if (!Array.isArray(input)) {
       throw new Error("Invalid input: must be an array of message IDs or message objects");
@@ -17801,10 +17916,19 @@ Notes:
     if (invalidIds.length > 0) {
       throw new Error("All message IDs must be non-empty strings");
     }
-    const memoryStore = await this.getMemoryStore();
-    await memoryStore.deleteMessages(messageIds);
-    if (this.vector) {
-      void this.deleteMessageVectors(messageIds);
+    const span = this.createMemorySpan("delete", observabilityContext, void 0, {
+      messageCount: messageIds.length
+    });
+    try {
+      const memoryStore = await this.getMemoryStore();
+      await memoryStore.deleteMessages(messageIds);
+      if (this.vector) {
+        void this.deleteMessageVectors(messageIds);
+      }
+      span?.end({ output: { success: true }, attributes: { messageCount: messageIds.length } });
+    } catch (error) {
+      span?.error({ error, endSpan: true });
+      throw error;
     }
   }
   /**
@@ -18232,7 +18356,7 @@ Notes:
     if (!effectiveConfig) return null;
     const engine = await this.omEngine;
     if (!engine) return null;
-    const { ObservationalMemoryProcessor } = await import('./observational-memory-JQ34KLFS.js');
+    const { ObservationalMemoryProcessor } = await import('./observational-memory-OVRHDQRG.js');
     return new ObservationalMemoryProcessor(engine, this);
   }
 };