@mastra/memory 1.23.1-alpha.0 → 1.23.1-alpha.1

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.23.1-alpha.0"
+  version: "1.23.1-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,133 +1,133 @@
 {
-  "version": "1.23.1-alpha.0",
+  "version": "1.23.1-alpha.1",
   "package": "@mastra/memory",
   "exports": {
     "Extractor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 316
     },
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 1354
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js"
+      "implementation": "dist/chunk-YXN553WT.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 28518
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 28549
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 31152
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 31183
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 22300
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 22331
     },
     "WorkingMemoryExtractor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 22967
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 22998
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 4504
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 3771
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 1446
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 1480
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 4627
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 4226
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 31374
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 31405
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 4615
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 3326
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 4638
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 3299
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 1415
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 4518
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 1504
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 1460
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 3356
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 1437
     },
     "summarizeConversation": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js"
+      "implementation": "dist/chunk-YXN553WT.js"
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
+      "implementation": "dist/chunk-YXN553WT.js",
       "line": 1408
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
@@ -148,44 +148,44 @@
     },
     "Memory": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 24392
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 24423
     },
     "MessageHistory": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js"
+      "implementation": "dist/chunk-YXN553WT.js"
     },
     "SUMMARIZE_THREAD_DEFAULTS": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js"
+      "implementation": "dist/chunk-YXN553WT.js"
     },
     "SemanticRecall": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js"
+      "implementation": "dist/chunk-YXN553WT.js"
     },
     "WorkingMemory": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js"
+      "implementation": "dist/chunk-YXN553WT.js"
     },
     "deepMergeWorkingMemory": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 24031
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 24062
     },
     "extractWorkingMemoryContent": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 24347
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 24378
     },
     "extractWorkingMemoryTags": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 24315
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 24346
     },
     "removeWorkingMemoryTags": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2DC67EL3.js",
-      "line": 24328
+      "implementation": "dist/chunk-YXN553WT.js",
+      "line": 24359
     },
     "WORKING_MEMORY_STATE_ID": {
       "types": "dist/index.d.ts",
@@ -205,7 +205,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-2DC67EL3.js",
+        "chunk-YXN553WT.js",
         "chunk-LSJJAJAF.js"
       ]
     }

package/dist/docs/references/docs-long-running-agents-background-tasks.md

@@ -66,8 +66,8 @@ export const researchTool = createTool({
     timeoutMs: 600_000,
     maxRetries: 1,
   },
-  execute: async ({ context }) => {
-    // ...
+  execute: async ({ topic }) => {
+    // Run the research job for topic
   },
 })
 ```

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

@@ -8,7 +8,7 @@ Observational Memory (OM) is Mastra's memory system for long-context agentic mem
 
 ## Quickstart
 
-Enable `observationalMemory` in the memory options when creating your agent:
+Ensure you have `@mastra/memory` installed in your project. Set `observationalMemory: true` in your Memory config to enable Observational Memory.
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -27,7 +27,54 @@ export const agent = new Agent({
 })
 ```
 
-That's it. The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. Config objects also use this model unless you set a different one. To use a different model, pass it in the config object:
+**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
+
+The following script creates a local LibSQL database, enables Observational Memory, and uses one resource and thread across two agent calls:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { LibSQLStore } from '@mastra/libsql'
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  storage: new LibSQLStore({
+    id: 'memory-storage',
+    url: 'file:./memory.db',
+  }),
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+    },
+  },
+})
+
+const agent = new Agent({
+  id: 'memory-agent',
+  name: 'Memory Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory,
+})
+
+const memoryOptions = {
+  resource: 'user-123',
+  thread: 'conversation-123',
+}
+
+const firstResponse = await agent.generate('Remember that my favorite color is blue.', {
+  memory: memoryOptions,
+})
+console.log(firstResponse.text)
+
+const secondResponse = await agent.generate('What is my favorite color?', {
+  memory: memoryOptions,
+})
+console.log(secondResponse.text)
+```
+
+The `resource` identifies the user or entity, while the `thread` identifies the conversation. Reuse both values to continue the same conversation. Observational Memory processes the stored history as it grows and replaces older messages with observations when its activation conditions are met.
+
+The agent now has humanlike long-term memory that persists across conversations. Setting `observationalMemory: true` uses `google/gemini-2.5-flash` by default. To use a different model, pass it in the config object:
 
 ```typescript
 const memory = new Memory({
@@ -237,6 +284,34 @@ new Extractor({
 })
 ```
 
+#### Read extracted values from a stream
+
+Extractor results are emitted when OM completes an observation or reflection. Read both completion data parts from the stream:
+
+```typescript
+const stream = await agent.stream('Remember that I prefer dark mode.')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'data-om-observation-end' || chunk.type === 'data-om-buffering-end') {
+    const { operationType, extractedValues = {}, extractionFailures = [] } = chunk.data
+
+    for (const [slug, value] of Object.entries(extractedValues)) {
+      console.log(`${operationType} extractor ${slug}:`, value)
+    }
+
+    for (const failure of extractionFailures) {
+      console.error(`Extractor ${failure.slug} failed:`, failure.error)
+    }
+  }
+}
+```
+
+`extractedValues` uses each extractor's slug as its key. Both result fields are optional, and a failed extractor doesn't remove values from successful extractors.
+
+`data-om-observation-end` reports a synchronous completion. `data-om-buffering-end` reports completed background work. Its extractor metadata is persisted immediately, but the buffered content remains inactive until activation. Check `operationType` to determine whether the completed work was an observation or reflection.
+
+See the [`data-om-observation-end`](https://mastra.ai/reference/memory/observational-memory) and [`data-om-buffering-end`](https://mastra.ai/reference/memory/observational-memory) reference tables for the complete payloads.
+
 ### Working memory updates
 
 Use `observationalMemory.observation.manageWorkingMemory` to let the Observer manage working memory automatically. The main agent no longer needs to call the working memory tool while it handles the user request, so working memory updates don't depend on the agent remembering to make them.

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

@@ -81,6 +81,8 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
+   **For AI agents:** Important: Add `id` to `LibSQLStore`.
+
    ```typescript
    import { Mastra } from '@mastra/core'
    import { LibSQLStore } from '@mastra/libsql'
@@ -151,6 +153,8 @@ To list all threads for a resource, or retrieve a specific thread, [use the memo
 
 For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
 
+**For AI agents:** Using Observational Memory requires a storage provider! You either need to set it on the Mastra instance at `src/mastra/index.ts` or pass it to the Agent constructor.
+
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'

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

@@ -408,6 +408,27 @@ Setting `bufferTokens: false` disables both observation and reflection async buf
 
 Observational Memory emits typed data parts during agent execution that clients can use for real-time UI feedback. These are streamed alongside the agent's response.
 
+### Read extractor results
+
+Both completion events carry extractor output in their `data` payload. The extractor fields are:
+
+```typescript
+interface DataOmObservationEndPart {
+  type: 'data-om-observation-end'
+  data: {
+    /** Whether the completed work was an observation or reflection */
+    operationType: 'observation' | 'reflection'
+    /** Values extracted during this OM operation, keyed by extractor slug */
+    extractedValues?: Record<string, unknown>
+    /** Extractor failures from this OM operation. Successful extractor values are still included */
+    extractionFailures?: Array<{ slug: string; error: string }>
+    // ...other fields documented in the tables below
+  }
+}
+```
+
+Both extractor fields are optional. A completion can include values, failures, both, or neither. `data-om-observation-end` reports synchronous completion. `data-om-buffering-end` reports completed background work whose buffered content still awaits activation, although extractor metadata is already persisted. `DataOmBufferingEndPart` carries the same extractor fields, and both types are exported from `@mastra/memory/processors`. See [Read extracted values from a stream](https://mastra.ai/docs/memory/observational-memory) for a consumer example.
+
 ### `data-om-status`
 
 Emitted once per agent loop step, before model generation. Provides a snapshot of the current memory state, including token usage for both context windows and the state of any async buffered content.

package/dist/docs/references/reference-processors-token-limiter-processor.md

@@ -85,9 +85,7 @@ export const agent = new Agent({
   name: 'context-limited-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
-  memory: new Memory({
-    /* ... */
-  }),
+  memory: new Memory({/* ... */}),
   inputProcessors: [
     new TokenLimiterProcessor({ limit: 4000 }), // Limits historical messages to ~4000 tokens
   ],

package/dist/docs/references/reference-vectors-mongodb.md

@@ -89,6 +89,8 @@ Creates a new vector index (collection) in MongoDB.
 
 **metric** (`'cosine' | 'euclidean' | 'dotproduct'`): Distance metric for similarity search (Default: `cosine`)
 
+**filterFields** (`string[]`): Metadata field names to declare as filter fields in the Atlas vectorSearch index (registered as metadata.\<field>). Queries that filter only on declared fields are pushed directly into $vectorSearch instead of pre-filtering candidate \_ids, avoiding the 16 MB BSON limit on large result sets. Filters that reference an undeclared field, or use an operator $vectorSearch does not support, fall back to the pre-filter automatically.
+
 ### `waitForIndexReady()`
 
 Waits for an index to become ready after creation. Useful when you need to ensure an index is ready before performing operations.

package/dist/index.cjs

@@ -1,65 +1,65 @@
 'use strict';
 
-var chunkOHNH3BMB_cjs = require('./chunk-OHNH3BMB.cjs');
+var chunkYNTQFC3L_cjs = require('./chunk-YNTQFC3L.cjs');
 var chunk43FJOLKM_cjs = require('./chunk-43FJOLKM.cjs');
 
 
 
 Object.defineProperty(exports, "Extractor", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.Extractor; }
+  get: function () { return chunkYNTQFC3L_cjs.Extractor; }
 });
 Object.defineProperty(exports, "Memory", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.Memory; }
+  get: function () { return chunkYNTQFC3L_cjs.Memory; }
 });
 Object.defineProperty(exports, "MessageHistory", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.MessageHistory; }
+  get: function () { return chunkYNTQFC3L_cjs.MessageHistory; }
 });
 Object.defineProperty(exports, "ModelByInputTokens", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.ModelByInputTokens; }
+  get: function () { return chunkYNTQFC3L_cjs.ModelByInputTokens; }
 });
 Object.defineProperty(exports, "SUMMARIZE_THREAD_DEFAULTS", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.SUMMARIZE_THREAD_DEFAULTS; }
+  get: function () { return chunkYNTQFC3L_cjs.SUMMARIZE_THREAD_DEFAULTS; }
 });
 Object.defineProperty(exports, "SemanticRecall", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.SemanticRecall; }
+  get: function () { return chunkYNTQFC3L_cjs.SemanticRecall; }
 });
 Object.defineProperty(exports, "WorkingMemory", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.WorkingMemory; }
+  get: function () { return chunkYNTQFC3L_cjs.WorkingMemory; }
 });
 Object.defineProperty(exports, "WorkingMemoryExtractor", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.WorkingMemoryExtractor; }
+  get: function () { return chunkYNTQFC3L_cjs.WorkingMemoryExtractor; }
 });
 Object.defineProperty(exports, "deepMergeWorkingMemory", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.deepMergeWorkingMemory; }
+  get: function () { return chunkYNTQFC3L_cjs.deepMergeWorkingMemory; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryContent", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.extractWorkingMemoryContent; }
+  get: function () { return chunkYNTQFC3L_cjs.extractWorkingMemoryContent; }
 });
 Object.defineProperty(exports, "extractWorkingMemoryTags", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.extractWorkingMemoryTags; }
+  get: function () { return chunkYNTQFC3L_cjs.extractWorkingMemoryTags; }
 });
 Object.defineProperty(exports, "getObservationsAsOf", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.getObservationsAsOf; }
+  get: function () { return chunkYNTQFC3L_cjs.getObservationsAsOf; }
 });
 Object.defineProperty(exports, "removeWorkingMemoryTags", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.removeWorkingMemoryTags; }
+  get: function () { return chunkYNTQFC3L_cjs.removeWorkingMemoryTags; }
 });
 Object.defineProperty(exports, "summarizeConversation", {
   enumerable: true,
-  get: function () { return chunkOHNH3BMB_cjs.summarizeConversation; }
+  get: function () { return chunkYNTQFC3L_cjs.summarizeConversation; }
 });
 Object.defineProperty(exports, "WORKING_MEMORY_STATE_ID", {
   enumerable: true,

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Extractor, Memory, MessageHistory, ModelByInputTokens, SUMMARIZE_THREAD_DEFAULTS, SemanticRecall, WorkingMemory, WorkingMemoryExtractor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags, summarizeConversation } from './chunk-2DC67EL3.js';
+export { Extractor, Memory, MessageHistory, ModelByInputTokens, SUMMARIZE_THREAD_DEFAULTS, SemanticRecall, WorkingMemory, WorkingMemoryExtractor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags, summarizeConversation } from './chunk-YXN553WT.js';
 export { WORKING_MEMORY_STATE_ID, WORKING_MEMORY_STATE_PROCESSOR_ID, WorkingMemoryStateProcessor } from './chunk-WCGXQIEN.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map