@mastra/memory 1.0.1 → 1.1.0-alpha.1

package/dist/docs/README.md

@@ -33,4 +33,4 @@ docs/
 ## Version
 
 Package: @mastra/memory
-Version: 1.0.1
+Version: 1.1.0-alpha.1

package/dist/docs/SKILL.md

@@ -5,7 +5,7 @@ description: Documentation for @mastra/memory. Includes links to type definition
 
 # @mastra/memory Documentation
 
-> **Version**: 1.0.1
+> **Version**: 1.1.0-alpha.1
 > **Package**: @mastra/memory
 
 ## Quick Navigation
@@ -23,6 +23,17 @@ Each export maps to:
 
 ## Top Exports
 
+  - OBSERVATIONAL_MEMORY_DEFAULTS: dist/processors/index.d.ts
+  - OBSERVER_SYSTEM_PROMPT: dist/processors/index.d.ts
+  - ObservationalMemory: dist/processors/index.d.ts
+  - TokenCounter: dist/processors/index.d.ts
+  - buildObserverPrompt: dist/processors/index.d.ts
+  - buildObserverSystemPrompt: dist/processors/index.d.ts
+  - extractCurrentTask: dist/processors/index.d.ts
+  - formatMessagesForObserver: dist/processors/index.d.ts
+  - hasCurrentTaskSection: dist/processors/index.d.ts
+  - optimizeObservationsForContext: dist/processors/index.d.ts
+  - parseObserverOutput: dist/processors/index.d.ts
   - extractWorkingMemoryContent: dist/index.d.ts
   - extractWorkingMemoryTags: dist/index.d.ts
   - removeWorkingMemoryTags: dist/index.d.ts

package/dist/docs/SOURCE_MAP.json

@@ -1,7 +1,60 @@
 {
-  "version": "1.0.1",
+  "version": "1.1.0-alpha.1",
   "package": "@mastra/memory",
   "exports": {
+    "OBSERVATIONAL_MEMORY_DEFAULTS": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js"
+    },
+    "OBSERVER_SYSTEM_PROMPT": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js"
+    },
+    "ObservationalMemory": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 1206
+    },
+    "TokenCounter": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 925
+    },
+    "buildObserverPrompt": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 644
+    },
+    "buildObserverSystemPrompt": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 403
+    },
+    "extractCurrentTask": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 725
+    },
+    "formatMessagesForObserver": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 490
+    },
+    "hasCurrentTaskSection": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 713
+    },
+    "optimizeObservationsForContext": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 736
+    },
+    "parseObserverOutput": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-6TXUWFIU.js",
+      "line": 670
+    },
     "extractWorkingMemoryContent": {
       "types": "dist/index.d.ts",
       "implementation": "dist/memory"
@@ -27,5 +80,12 @@
       "implementation": "dist/processors"
     }
   },
-  "modules": {}
+  "modules": {
+    "processors": {
+      "index": "dist/processors/index.js",
+      "chunks": [
+        "chunk-6TXUWFIU.js"
+      ]
+    }
+  }
 }

package/dist/docs/memory/02-storage.md

@@ -15,6 +15,16 @@ export const mastra = new Mastra({
   }),
 });
 ```
+
+> **Sharing the database with Mastra Studio**
+When running `mastra dev` alongside your application (e.g., Next.js), use an absolute path to ensure both processes access the same database:
+
+```typescript
+url: "file:/absolute/path/to/your/project/mastra.db"
+```
+
+Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
+
 This configures instance-level storage, which all agents share by default. You can also configure [agent-level storage](#agent-level-storage) for isolated data boundaries.
 
 Mastra automatically creates the necessary tables on first interaction. See the [core schema](https://mastra.ai/reference/storage/overview#core-schema) for details on what gets created, including tables for messages, threads, resources, workflows, traces, and evaluation datasets.

package/dist/index.cjs

@@ -6,6 +6,7 @@ var zod = require('zod');
 var z4 = require('zod/v4');
 var v3 = require('zod/v3');
 var agent = require('@mastra/core/agent');
+var features = require('@mastra/core/features');
 var memory = require('@mastra/core/memory');
 var utils = require('@mastra/core/utils');
 var zodToJson = require('@mastra/schema-compat/zod-to-json');
@@ -14599,6 +14600,12 @@ var __experimental_updateWorkingMemoryToolVNext = (config) => {
     }
   });
 };
+function normalizeObservationalMemoryConfig(config) {
+  if (config === true) return {};
+  if (config === false || config === void 0) return void 0;
+  if (typeof config === "object" && config.enabled === false) return void 0;
+  return config;
+}
 var CHARS_PER_TOKEN = 4;
 var DEFAULT_MESSAGE_RANGE = { before: 1, after: 1 };
 var DEFAULT_TOP_K = 4;
@@ -14613,7 +14620,8 @@ var Memory = class extends memory.MastraMemory {
         // and someone bumps @mastra/memory without bumping @mastra/core the defaults wouldn't exist yet
         enabled: false,
         template: this.defaultWorkingMemoryTemplate
-      }
+      },
+      observationalMemory: config.options?.observationalMemory
     });
     this.threadConfig = mergedConfig;
   }
@@ -14627,6 +14635,10 @@ var Memory = class extends memory.MastraMemory {
     }
     return store;
   }
+  async listMessagesByResourceId(args) {
+    const memoryStore = await this.getMemoryStore();
+    return memoryStore.listMessagesByResourceId(args);
+  }
   async validateThreadIsOwnedByResource(threadId, resourceId, config) {
     const resourceScope = typeof config?.semanticRecall === "object" && config?.semanticRecall?.scope !== `thread` || config.semanticRecall === true;
     const thread = await this.getThreadById({ threadId });
@@ -14671,8 +14683,11 @@ var Memory = class extends memory.MastraMemory {
         `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 (config?.semanticRecall && vectorSearchString && this.vector) {
-      const { embeddings, dimension } = await this.embedMessageContent(vectorSearchString);
+      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) => {
@@ -14716,7 +14731,7 @@ 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 };
+    return { messages, usage };
   }
   async getThreadById({ threadId }) {
     const memoryStore = await this.getMemoryStore();
@@ -14963,10 +14978,11 @@ ${workingMemory}`;
       ...this.embedderOptions || {}
     });
     if (isFastEmbed && !this.firstEmbed) this.firstEmbed = promise;
-    const { embeddings } = await promise;
+    const { embeddings, usage } = await promise;
     const result = {
       embeddings,
       chunks,
+      usage,
       dimension: embeddings[0]?.length
     };
     this.embeddingCache.set(key, result);
@@ -14987,6 +15003,7 @@ ${workingMemory}`;
     const result = await memoryStore.saveMessages({
       messages: dbMessages
     });
+    let totalTokens = 0;
     if (this.vector && config.semanticRecall) {
       const embeddingData = [];
       let dimension;
@@ -15002,6 +15019,9 @@ ${workingMemory}`;
           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(() => ({
@@ -15030,7 +15050,7 @@ ${workingMemory}`;
         });
       }
     }
-    return result;
+    return { ...result, usage: totalTokens > 0 ? { tokens: totalTokens } : void 0 };
   }
   updateMessageToHideWorkingMemoryV2(message) {
     const newMessage = { ...message };
@@ -15636,6 +15656,89 @@ Notes:
     }
     return history;
   }
+  /**
+   * Get input processors for this memory instance.
+   * Extends the base implementation to add ObservationalMemory processor when configured.
+   *
+   * @param configuredProcessors - Processors already configured by the user (for deduplication)
+   * @param context - Request context for runtime configuration
+   * @returns Array of input processors configured for this memory instance
+   */
+  async getInputProcessors(configuredProcessors = [], context) {
+    const processors = await super.getInputProcessors(configuredProcessors, context);
+    const om = await this.createOMProcessor(configuredProcessors, context);
+    if (om) {
+      processors.push(om);
+    }
+    return processors;
+  }
+  /**
+   * Extends the base implementation to add ObservationalMemory as an output processor.
+   * OM needs processOutputResult to save messages at the end of the agent turn,
+   * even when the observation threshold was never reached during the loop.
+   */
+  async getOutputProcessors(configuredProcessors = [], context) {
+    const processors = await super.getOutputProcessors(configuredProcessors, context);
+    const om = await this.createOMProcessor(configuredProcessors, context);
+    if (om) {
+      processors.push(om);
+    }
+    return processors;
+  }
+  /**
+   * Creates an ObservationalMemory processor instance if configured and not already present.
+   * A new instance is created per call — processorStates (e.g., sealedIds) are shared
+   * via the ProcessorRunner's state map keyed by processor ID, not by instance identity.
+   */
+  async createOMProcessor(configuredProcessors = [], context) {
+    const hasObservationalMemory = configuredProcessors.some(
+      (p) => !("workflow" in p) && p.id === "observational-memory"
+    );
+    const memoryContext = context?.get("MastraMemory");
+    const runtimeMemoryConfig = memoryContext?.memoryConfig;
+    const effectiveConfig = runtimeMemoryConfig ? this.getMergedThreadConfig(runtimeMemoryConfig) : this.threadConfig;
+    const omConfig = normalizeObservationalMemoryConfig(effectiveConfig.observationalMemory);
+    if (!omConfig || hasObservationalMemory) {
+      return null;
+    }
+    const coreSupportsOM = features.coreFeatures.has("observationalMemory");
+    if (!coreSupportsOM) {
+      throw new Error(
+        "Observational memory is enabled but the installed version of @mastra/core does not support it. Please upgrade @mastra/core to a version that includes observational memory support."
+      );
+    }
+    const memoryStore = await this.storage.getStore("memory");
+    if (!memoryStore) {
+      throw new Error(
+        "Using Mastra Memory observational memory requires a storage adapter but no attached adapter was detected."
+      );
+    }
+    if (!memoryStore.supportsObservationalMemory) {
+      throw new Error(
+        `Observational memory is enabled but the storage adapter (${memoryStore.constructor.name}) does not support it. If you're using @mastra/libsql, @mastra/pg, or @mastra/mongodb, upgrade to the latest version. Otherwise, use one of those adapters or disable observational memory.`
+      );
+    }
+    const { ObservationalMemory } = await import('./observational-memory-3Q42SITP.cjs');
+    return new ObservationalMemory({
+      storage: memoryStore,
+      scope: omConfig.scope,
+      shareTokenBudget: omConfig.shareTokenBudget,
+      model: omConfig.model,
+      observation: omConfig.observation ? {
+        model: omConfig.observation.model,
+        messageTokens: omConfig.observation.messageTokens,
+        modelSettings: omConfig.observation.modelSettings,
+        maxTokensPerBatch: omConfig.observation.maxTokensPerBatch,
+        providerOptions: omConfig.observation.providerOptions
+      } : void 0,
+      reflection: omConfig.reflection ? {
+        model: omConfig.reflection.model,
+        observationTokens: omConfig.reflection.observationTokens,
+        modelSettings: omConfig.reflection.modelSettings,
+        providerOptions: omConfig.reflection.providerOptions
+      } : void 0
+    });
+  }
 };
 
 Object.defineProperty(exports, "extractWorkingMemoryContent", {