@mastra/memory 1.21.3-alpha.1 → 1.22.0-alpha.3

package/dist/chunk-NKIQRCOM.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=chunk-NKIQRCOM.cjs.map
+//# sourceMappingURL=chunk-NKIQRCOM.cjs.map

package/dist/{chunk-Q7SFCCGT.cjs.map → chunk-NKIQRCOM.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-Q7SFCCGT.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-NKIQRCOM.cjs"}

package/dist/{constants-DVRTNEGY.js → constants-RMCTOZE3.js}

@@ -1,3 +1,3 @@
 export { OBSERVATIONAL_MEMORY_DEFAULTS, OBSERVATION_CONTEXT_INSTRUCTIONS, OBSERVATION_CONTEXT_PROMPT, OBSERVATION_CONTINUATION_HINT, OBSERVATION_RETRIEVAL_INSTRUCTIONS } from './chunk-LSJJAJAF.js';
-//# sourceMappingURL=constants-DVRTNEGY.js.map
-//# sourceMappingURL=constants-DVRTNEGY.js.map
+//# sourceMappingURL=constants-RMCTOZE3.js.map
+//# sourceMappingURL=constants-RMCTOZE3.js.map

package/dist/{constants-DVRTNEGY.js.map → constants-RMCTOZE3.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"constants-DVRTNEGY.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"constants-RMCTOZE3.js"}

package/dist/{constants-JS5SS7GS.cjs → constants-ZEKSZ4UM.cjs}

@@ -24,5 +24,5 @@ Object.defineProperty(exports, "OBSERVATION_RETRIEVAL_INSTRUCTIONS", {
   enumerable: true,
   get: function () { return chunkD4J4XPGM_cjs.OBSERVATION_RETRIEVAL_INSTRUCTIONS; }
 });
-//# sourceMappingURL=constants-JS5SS7GS.cjs.map
-//# sourceMappingURL=constants-JS5SS7GS.cjs.map
+//# sourceMappingURL=constants-ZEKSZ4UM.cjs.map
+//# sourceMappingURL=constants-ZEKSZ4UM.cjs.map

package/dist/{constants-JS5SS7GS.cjs.map → constants-ZEKSZ4UM.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"constants-JS5SS7GS.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"constants-ZEKSZ4UM.cjs"}

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.21.3-alpha.1"
+  version: "1.22.0-alpha.3"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,120 +1,130 @@
 {
-  "version": "1.21.3-alpha.1",
+  "version": "1.22.0-alpha.3",
   "package": "@mastra/memory",
   "exports": {
+    "Extractor": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 316
+    },
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 795
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 1354
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js"
+      "implementation": "dist/chunk-KKP6DG65.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 7213
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 27526
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 9798
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 30157
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 6544
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 26857
+    },
+    "WorkingMemoryExtractor": {
+      "types": "dist/processors/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 20684
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 3787
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 4465
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 3058
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 3732
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 887
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 1446
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 921
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 1480
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 3901
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 4588
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 3513
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 4187
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 10018
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 30379
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 3889
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 4576
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 2606
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 3287
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 3912
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 4599
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 2579
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 3260
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 856
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 1415
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 3797
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 4479
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 945
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 1504
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 901
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 1460
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 2636
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 3317
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 878
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 1437
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-X7DOZRJK.js",
-      "line": 849
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 1408
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
@@ -132,6 +142,43 @@
       "types": "dist/processors/index.d.ts",
       "implementation": "dist/chunk-LSJJAJAF.js"
     },
+    "Memory": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 22108
+    },
+    "MessageHistory": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js"
+    },
+    "SemanticRecall": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js"
+    },
+    "WorkingMemory": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js"
+    },
+    "deepMergeWorkingMemory": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 21747
+    },
+    "extractWorkingMemoryContent": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 22063
+    },
+    "extractWorkingMemoryTags": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 22031
+    },
+    "removeWorkingMemoryTags": {
+      "types": "dist/index.d.ts",
+      "implementation": "dist/chunk-KKP6DG65.js",
+      "line": 22044
+    },
     "WORKING_MEMORY_STATE_ID": {
       "types": "dist/index.d.ts",
       "implementation": "dist/chunk-WCGXQIEN.js"
@@ -144,25 +191,13 @@
       "types": "dist/index.d.ts",
       "implementation": "dist/chunk-WCGXQIEN.js",
       "line": 7
-    },
-    "MessageHistory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/processors"
-    },
-    "SemanticRecall": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/processors"
-    },
-    "WorkingMemory": {
-      "types": "dist/index.d.ts",
-      "implementation": "dist/processors"
     }
   },
   "modules": {
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-X7DOZRJK.js",
+        "chunk-KKP6DG65.js",
         "chunk-LSJJAJAF.js"
       ]
     }

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

@@ -163,6 +163,120 @@ OM uses fast local token estimation for this thresholding work. Text is estimate
 
 The Observer can also see attachments in the history it reviews. OM keeps readable placeholders like `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript for readability, and forwards the actual attachment parts alongside the text. Image-like `file` parts are upgraded to image inputs for the Observer when possible, while non-image attachments are forwarded as file parts with normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
 
+### Extractors
+
+Use extractors when you want OM to persist specific values alongside observations. Built-in values such as **current task**, **suggested response**, and **thread title** use the same extraction pipeline as custom values.
+
+The following example extracts a compact user profile from observations:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Extractor, Memory } from '@mastra/memory'
+import { z } from 'zod'
+
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+      observation: {
+        extract: [
+          new Extractor({
+            name: 'User profile',
+            instructions: 'Extract stable user profile facts that should be remembered.',
+            schema: z.object({
+              preferredName: z.string().optional(),
+              timezone: z.string().optional(),
+              tools: z.array(z.string()).optional(),
+            }),
+          }),
+        ],
+      },
+    },
+  },
+})
+
+export const agent = new Agent({
+  name: 'assistant',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory,
+})
+```
+
+Adding a `schema` makes the extractor run as a follow-up structured output request. Schema-less extractors are inline string extractors emitted directly in the Observer or Reflector response.
+
+```typescript
+new Extractor({
+  name: 'Mood',
+  instructions: 'Extract the user mood as a short phrase.',
+})
+```
+
+By default, OM shows the last extracted value to the extractor on later runs. Set `includePreviousExtraction: false` when the Observer should not see the previous value.
+
+```typescript
+new Extractor({
+  name: 'Latest blocker',
+  instructions: 'Extract any blockers the agent is running into.',
+  includePreviousExtraction: false,
+})
+```
+
+Use dynamic `instructions` or `schema` functions when an extractor needs runtime context, such as the active memory instance or request context:
+
+```typescript
+new Extractor({
+  name: 'Workspace summary',
+  instructions: ({ memory }) =>
+    memory ? 'Extract workspace facts for this memory instance.' : 'Extract workspace facts.',
+})
+```
+
+### 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.
+
+This also keeps working memory prompt-cache friendly. Working memory normally lives in the system prompt, so updates can invalidate the prompt cache. OM-managed working memory defaults `workingMemory.useStateSignals` to `true`, which moves working memory into state signals instead.
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  options: {
+    workingMemory: {
+      enabled: true,
+    },
+    observationalMemory: {
+      enabled: true,
+      observation: {
+        manageWorkingMemory: true,
+      },
+    },
+  },
+})
+```
+
+This setting adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true`. Set `workingMemory.agentManaged: true` if the main agent should still receive working memory tool and instruction injection.
+
+Use `onExtracted` to normalize or react to custom extracted values before they are persisted:
+
+```typescript
+new Extractor({
+  name: 'Project status',
+  instructions: 'Extract the current project status.',
+  schema: z.string(),
+  async onExtracted({ current, sendSignal }) {
+    await sendSignal?.({
+      type: 'user-message',
+      contents: `Project status extracted: ${current}`,
+    })
+    return current.trim().toLowerCase()
+  },
+})
+```
+
+Extractor failures are reported in OM markers and do not block other successful extractor values. See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full `Extractor` shape.
+
 If your Observer model is text-only or its API rejects multimodal input, set `observation.observeAttachments` to `false` to drop attachments before they reach the Observer. The readable placeholders (`[Image #1: ...]`, `[File #1: ...]`) are kept in the transcript so the Observer can still reason about what was shared without receiving the binary payload. The same filter applies to tool results that contain image or file parts:
 
 ```typescript

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

@@ -6,6 +6,8 @@ Think of it as the agent's active thoughts or scratchpad – the key information
 
 This is useful for maintaining ongoing state that's always relevant and should always be available to the agent.
 
+If you use [Observational Memory](https://mastra.ai/docs/memory/observational-memory), `observationalMemory.observation.manageWorkingMemory` lets OM update working memory for the agent.
+
 Working memory can persist at two different scopes:
 
 - **Resource-scoped** (default): Memory persists across all conversation threads for the same user

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

@@ -54,6 +54,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.threadTitle** (`boolean`): When \`true\`, the Observer suggests short thread titles and updates the thread title when the conversation topic meaningfully changes. This is opt-in and defaults to disabled.
 
+**observation.extract** (`Extractor[]`): Custom values to extract after observation. Schema-less extractors are requested inline in the Observer output. Schema-backed extractors run as a follow-up structured output call and are stored in thread OM metadata.
+
 **observation.observeAttachments** (`boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. \`true\` (default) forwards all attachments. \`false\` drops all attachments while keeping placeholders visible. An array is a case-insensitive mimeType allowlist supporting exact matches (\`'application/pdf'\`), wildcard subtypes (\`'image/\*'\`), and bare \`'\*'\` for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model. Tool-result attachments are filtered using the same rule.
 
 **observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. Text is estimated locally with \`tokenx\`. Image parts are included with model-aware heuristics when possible, with deterministic fallbacks when image metadata is incomplete. Image-like \`file\` parts are counted the same way when uploads are normalized as files.
@@ -86,6 +88,8 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.instruction** (`string`): Custom instruction appended to the Reflector's system prompt. Use this to customize how the Reflector consolidates observations, such as prioritizing certain types of information.
 
+**reflection.extract** (`Extractor[]`): Custom values to extract after reflection. Schema-less extractors are requested inline in the Reflector output. Schema-backed extractors run as a follow-up structured output call and are stored in thread OM metadata.
+
 **reflection.observationTokens** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them.
 
 **reflection.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent.
@@ -112,8 +116,86 @@ OM persists token payload estimates so repeated counting can reuse prior token e
 - Per-message and per-conversation overhead are always recomputed at runtime and aren't cached.
 - `data-*` and `reasoning` parts are skipped and don't receive cache entries.
 
+## Extractor API
+
+`Extractor` defines a value that OM should extract during observation or reflection. Built-in OM values such as `current-task`, `suggested-response`, and `thread-title` use the same extractor pipeline as custom values.
+
+```typescript
+import { Memory, Extractor } from '@mastra/memory'
+import { z } from 'zod'
+
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+      observation: {
+        extract: [
+          new Extractor({
+            name: 'User profile',
+            instructions: 'Extract stable user profile facts that should be remembered.',
+            schema: z.object({
+              name: z.string().optional(),
+              timezone: z.string().optional(),
+            }),
+          }),
+        ],
+      },
+    },
+  },
+})
+```
+
+**name** (`string`): Human-readable extractor name. OM slugifies this value into the extractor slug. Names must be unique after slug generation.
+
+**slug** (`string`): Generated stable identifier for persisted values and XML tags. Slugs use lowercase letters, numbers, and hyphens. Built-in slugs and reserved XML tags cannot be used by custom extractors.
+
+**instructions** (`string | (context) => string`): Instructions for what to extract and when to update the value. Use a function to derive instructions from runtime context.
+
+**schema** (`ZodType<T> | (context) => ZodType<T> | undefined`): Optional Zod schema for structured extraction. When provided, OM runs a follow-up structured output call after the main OM operation. When omitted, the extractor is an inline string extractor emitted in the Observer or Reflector response. Use a function to derive the schema from runtime context.
+
+**includePreviousExtraction** (`boolean`): Controls whether the previous extraction is shown to the extractor on future OM runs. Set to \`false\` for values that should only come from the current OM run. (Default: `true`)
+
+**onExtracted** (`(context) => T | void | Promise<T | void>`): Optional hook called after a custom extractor returns a value and before metadata is persisted. Returning a value replaces the extracted value. Throwing records an extraction failure.
+
+### Extraction behavior
+
+- Extracted values are stored in thread OM metadata under `om.extracted`.
+- Built-in extractor values are also mirrored to the compatibility metadata fields `currentTask`, `suggestedResponse`, and `threadTitle`.
+- `thread-title` updates the thread title only when `observation.threadTitle` is enabled.
+- `observation.extract` runs during observation. `reflection.extract` runs during reflection.
+- Schema-backed extractors add a follow-up structured output request.
+- Schema-less extractors are inline string extractors emitted directly in the Observer or Reflector output.
+- Dynamic extractor functions receive runtime context, including `source`, `threadId`, `resourceId`, `mainAgent`, `memory`, and `requestContext` when available.
+- `WorkingMemoryExtractor` uses the normal extractor pipeline to update working memory through the active `Memory` instance. It uses structured extraction when working memory has a JSON schema and skips OM metadata persistence, so the working memory payload isn't duplicated under OM extracted metadata.
+- `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
+- Extraction failures are reported in OM marker data and do not discard other successful extracted values.
+
 ## Examples
 
+### Working memory updates
+
+Use `observationalMemory.observation.manageWorkingMemory` when OM should update working memory.
+
+```typescript
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({
+  options: {
+    workingMemory: {
+      enabled: true,
+    },
+    observationalMemory: {
+      enabled: true,
+      observation: {
+        manageWorkingMemory: true,
+      },
+    },
+  },
+})
+```
+
+Set `workingMemory.agentManaged: true` if the main agent should still receive working memory tool and instruction injection.
+
 ### Resource scope with custom thresholds (experimental)
 
 ```typescript
@@ -431,6 +513,10 @@ Emitted when observation or reflection completes successfully.
 
 **suggestedResponse** (`string`): Suggested response extracted by the Observer.
 
+**extractedValues** (`Record<string, unknown>`): Values extracted during this OM operation, keyed by extractor slug.
+
+**extractionFailures** (`Array<{ slug: string; error: string }>`): Extractor failures from this OM operation. Successful extractor values are still included.
+
 **recordId** (`string`): The OM record ID.
 
 **threadId** (`string`): This thread's ID.
@@ -495,6 +581,10 @@ Emitted when async buffering completes. The content is stored but not yet activa
 
 **observations** (`string`): The buffered content.
 
+**extractedValues** (`Record<string, unknown>`): Values extracted during this buffered OM operation, keyed by extractor slug.
+
+**extractionFailures** (`Array<{ slug: string; error: string }>`): Extractor failures from this buffered OM operation. Successful extractor values are still included.
+
 **recordId** (`string`): The OM record ID.
 
 **threadId** (`string`): This thread's ID.