@mastra/memory 1.22.0-alpha.3 → 1.22.1-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @mastra/memory
 
+## 1.22.1-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`cc440a3`](https://github.com/mastra-ai/mastra/commit/cc440a39400d8ce06655462b26c1666a1b3d4320), [`ea6327b`](https://github.com/mastra-ai/mastra/commit/ea6327ba2d63ca647804bc97b347e03a58617162), [`3439fa8`](https://github.com/mastra-ai/mastra/commit/3439fa836ecfcaa257b40c20b30ac2a8be22e9ea), [`85107f2`](https://github.com/mastra-ai/mastra/commit/85107f2758b527147fccbedff962961927c2d3b8), [`1042cb4`](https://github.com/mastra-ai/mastra/commit/1042cb4da227c0a1315a6362262be3058866c5f8), [`06ff9e0`](https://github.com/mastra-ai/mastra/commit/06ff9e0befd1d642ab87ff749285ee4091205c7e), [`7f5e1ff`](https://github.com/mastra-ai/mastra/commit/7f5e1ff695a92f672bb3976363925d1e9136b54a), [`b8375c1`](https://github.com/mastra-ai/mastra/commit/b8375c1f8fe905df8ae2ae9a893bb365f17aec4e), [`003f35d`](https://github.com/mastra-ai/mastra/commit/003f35d19e07b23b4bacc591c8bc0c59b42124ae)]:
+  - @mastra/core@1.49.0-alpha.1
+  - @mastra/schema-compat@1.3.3-alpha.0
+
+## 1.22.0
+
+### Minor Changes
+
+- add observational memory extractors ([#18653](https://github.com/mastra-ai/mastra/pull/18653))
+
+  Introduces a public Extractor API for Observational Memory
+  with inline XML extraction and structured follow-up modes.
+  Includes built-in extractors for current task, suggested
+  response, and thread title. Persists extracted values into
+  thread OM metadata with key-level merging and carry-forward
+  into future observer/reflector prompts.
+
+- add OM-managed working memory ([#18654](https://github.com/mastra-ai/mastra/pull/18654))
+
+  Adds `observationalMemory.observation.manageWorkingMemory` so the Observer can update working memory automatically instead of requiring the main agent to call the working memory tool.
+
+  ```ts
+  new Memory({
+    options: {
+      workingMemory: { enabled: true },
+      observationalMemory: {
+        enabled: true,
+        observation: { manageWorkingMemory: true },
+      },
+    },
+  });
+  ```
+
+  This option adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true` when working memory is enabled. Set `workingMemory.agentManaged: true` to keep the main agent's working memory tool and instructions enabled.
+
+### Patch Changes
+
+- Expose `providerMetadata` on Observational Memory `ObserveHooks` results ([#18563](https://github.com/mastra-ai/mastra/pull/18563))
+
+  `onObservationEnd` and `onReflectionEnd` now receive the OM model call's `providerMetadata` alongside `usage`, so you can read per-call provider details — for example the AI Gateway's cost and generation id — straight from the hook instead of wrapping the observer/reflector models in a model-stream middleware:
+
+  ```ts
+  const hooks: ObserveHooks = {
+    onObservationEnd: ({ usage, providerMetadata }) => {
+      const gateway = providerMetadata?.gateway;
+      recordCost({ tokens: usage?.totalTokens, cost: gateway?.cost, generationId: gateway?.generationId });
+    },
+    onReflectionEnd: ({ usage, providerMetadata }) => {
+      recordCost({ tokens: usage?.totalTokens, cost: providerMetadata?.gateway?.cost });
+    },
+  };
+  ```
+
+  The field is additive and optional, and is omitted entirely when the provider emits no metadata, so existing hook consumers are unaffected. For batched observations and multi-attempt reflections it reflects the last batch/attempt that emitted provider metadata.
+
+- add Studio support for observational memory extractors ([#18655](https://github.com/mastra-ai/mastra/pull/18655))
+
+  Adds `bufferedObservationChunks` and extraction metadata to the buffer-status API and client types so extracted values flow through during live streaming. Renders observational memory indicators from a normalized cycle model that preserves extraction data across streaming, refetch, reload, activation, and failure transitions.
+
+- Updated dependencies [[`b9a2961`](https://github.com/mastra-ai/mastra/commit/b9a2961c1be81e3639c0879e58588c26dd0ae866), [`b33c77d`](https://github.com/mastra-ai/mastra/commit/b33c77d5293f14a794f3ec38dc947a6676de2764), [`1274eb3`](https://github.com/mastra-ai/mastra/commit/1274eb3a9508f579ceb3187fbce34408222d4b71), [`cdd5f93`](https://github.com/mastra-ai/mastra/commit/cdd5f939cefa67390629704dce92563ccbf492b2), [`1274eb3`](https://github.com/mastra-ai/mastra/commit/1274eb3a9508f579ceb3187fbce34408222d4b71), [`0ac14ce`](https://github.com/mastra-ai/mastra/commit/0ac14cea48e1b0a7857782153c78f7242fdf7e1a), [`9566d27`](https://github.com/mastra-ai/mastra/commit/9566d27ead3d95bdbe5a69e5a082a68222829cf2), [`8be63b0`](https://github.com/mastra-ai/mastra/commit/8be63b015fb8d72cea1220f05e7dc3bb997cc249), [`1009f77`](https://github.com/mastra-ai/mastra/commit/1009f772aa40016b49267c8566d0c29f6a16aa3c), [`1b8728a`](https://github.com/mastra-ai/mastra/commit/1b8728a57fd844205a452b0b4216d20ff60c784a), [`23c31de`](https://github.com/mastra-ai/mastra/commit/23c31de96ed8153402dcf092ac84b27a0c3638c1), [`0368766`](https://github.com/mastra-ai/mastra/commit/0368766744c7ea3df4d6059e2cc15f7bdf55f5a6), [`d0702ee`](https://github.com/mastra-ai/mastra/commit/d0702eedc1594cb2d0d83476440cfc2ec8820adb), [`9feeaa0`](https://github.com/mastra-ai/mastra/commit/9feeaa0f9a1af07039e5b4f22b932b0cb18617e8), [`6f578ac`](https://github.com/mastra-ai/mastra/commit/6f578acba84930b406b2a0700b17cfdfaf5aae56), [`345eecc`](https://github.com/mastra-ai/mastra/commit/345eecce6ba519b5d987f0e10b5de4c8e5734580), [`1917c53`](https://github.com/mastra-ai/mastra/commit/1917c53b19dac43926f29c496893b0686462dca4), [`c01012f`](https://github.com/mastra-ai/mastra/commit/c01012f50368d29eb3fc3764df42d48291973d23), [`705ba98`](https://github.com/mastra-ai/mastra/commit/705ba98726d388a596e896225f237907ca6807a9), [`95857bc`](https://github.com/mastra-ai/mastra/commit/95857bcd6669da7193f503e803f0d72a2bd66be6), [`e62c108`](https://github.com/mastra-ai/mastra/commit/e62c108409dfd6a6cac0a48ec39c5cc81d24fd52), [`2866f04`](https://github.com/mastra-ai/mastra/commit/2866f04953edb78c1637fa45cc53abe24122edcb), [`ee14cae`](https://github.com/mastra-ai/mastra/commit/ee14cae244805783bde518a6142de28b744b169c), [`e84e791`](https://github.com/mastra-ai/mastra/commit/e84e79174031d7bc8793ca6c805eb38b06e7cfb1), [`c2f0b7f`](https://github.com/mastra-ai/mastra/commit/c2f0b7f1370f4428d165f51f0d1d9a48331cc257), [`213feb8`](https://github.com/mastra-ai/mastra/commit/213feb87bfdd1d8ec00ea660e218f9bcfcb34e7b), [`58e287b`](https://github.com/mastra-ai/mastra/commit/58e287b1edaf978b13745a1795989cad3826e82b), [`e420b3c`](https://github.com/mastra-ai/mastra/commit/e420b3c3ffc98bbc5b791897ea390bb47af99696), [`be875ed`](https://github.com/mastra-ai/mastra/commit/be875ed43f856742ce58529f531b5ea0ae6911f3), [`9eefdc0`](https://github.com/mastra-ai/mastra/commit/9eefdc0ac03f989718c6d835334940a977938895), [`bfbbb01`](https://github.com/mastra-ai/mastra/commit/bfbbb01bd845ba54cdc0c678c277d08a7cb847e4), [`7d112ca`](https://github.com/mastra-ai/mastra/commit/7d112ca17078479b2659b88ba1c85b936cfc111c)]:
+  - @mastra/core@1.48.0
+  - @mastra/schema-compat@1.3.2
+
 ## 1.22.0-alpha.3
 
 ### Minor Changes

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.22.0-alpha.3"
+  version: "1.22.1-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.22.0-alpha.3",
+  "version": "1.22.1-alpha.0",
   "package": "@mastra/memory",
   "exports": {
     "Extractor": {

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

@@ -2,7 +2,7 @@
 
 **Added in:** `@mastra/core@1.29.0`
 
-Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/agents/agent) option the agent is re-invoked automatically so the result is processed in the same call.
+Background tasks let an agent dispatch a long-running tool call without blocking the agentic loop. The tool returns an immediate acknowledgement, the LLM continues responding, and the task runs to completion in the background. When it finishes, its result is written to memory and if you use `stream()` with the [`untilIdle`](https://mastra.ai/reference/streaming/agents/stream) option the agent is re-invoked automatically so the result is processed in the same call.
 
 ## When to use background tasks
 
@@ -166,7 +166,7 @@ const stream = await agent.stream('Research solana for me', {
 })
 ```
 
-> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/agents/agent) for the full API.
+> **Note:** Visit [`Agent.stream()`](https://mastra.ai/reference/streaming/agents/stream) for the full API.
 
 ### Aggregate properties
 
@@ -372,7 +372,7 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 
 ## Related
 
-- [`Agent.stream()` reference](https://mastra.ai/reference/agents/agent)
+- [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
 - [Durable agents](https://mastra.ai/docs/agents/durable-agents)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)

package/dist/docs/references/docs-agents-goals.md

@@ -26,6 +26,7 @@ Goals require a configured [storage](https://mastra.ai/docs/memory/storage) back
 import { Agent } from '@mastra/core/agent'
 
 const worker = new Agent({
+  id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
   model: 'openai/gpt-5.5',
@@ -66,6 +67,7 @@ By default the step uses a built-in LLM-as-judge scorer that returns `1` when th
 
 ```typescript
 const worker = new Agent({
+  id: 'worker',
   name: 'worker',
   instructions: 'You complete software tasks end to end.',
   model: 'openai/gpt-5.5',

package/dist/docs/references/docs-agents-supervisor-agents.md

@@ -351,6 +351,7 @@ Each subagent should have a clear `description` that explains what it does, what
 
 ```typescript
 const supervisor = new Agent({
+  id: 'supervisor',
   instructions: `You coordinate research and writing tasks.
 
 Available resources:

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

@@ -248,6 +248,7 @@ const contentBlocker = {
 }
 
 const agent = new Agent({
+  id: 'safe-agent',
   name: 'safe-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
@@ -287,6 +288,7 @@ const inputValidator = {
 }
 
 const agent = new Agent({
+  id: 'validated-agent',
   name: 'validated-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

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

@@ -13,6 +13,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -57,6 +58,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -196,6 +198,7 @@ const memory = new Memory({
 })
 
 export const agent = new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -281,6 +284,7 @@ If your Observer model is text-only or its API rejects multimodal input, set `ob
 
 ```typescript
 new Agent({
+  id: 'assistant',
   name: 'assistant',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -130,6 +130,7 @@ The following options control semantic recall behavior:
 
 ```typescript
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     options: {
       semanticRecall: {
@@ -151,6 +152,7 @@ The `filter` option restricts semantic recall results to messages with matching
 
 ```typescript
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     options: {
       semanticRecall: {
@@ -217,6 +219,7 @@ import { Agent } from '@mastra/core/agent'
 import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
     options: {
@@ -238,6 +241,7 @@ import { Memory } from '@mastra/memory'
 import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel({
       providerId: 'openrouter',
@@ -259,6 +263,7 @@ import { Agent } from '@mastra/core/agent'
 import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
 
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   }),
@@ -301,6 +306,7 @@ import { Agent } from '@mastra/core/agent'
 import { fastembed } from '@mastra/fastembed'
 
 const agent = new Agent({
+  id: 'agent',
   memory: new Memory({
     embedder: fastembed,
   }),

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

@@ -9,6 +9,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'test-agent',
   name: 'test-agent',
   instructions: 'You are an agent with memory.',
   model: 'openai/gpt-5.5',

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

@@ -11,6 +11,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -203,6 +204,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -232,6 +234,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -261,6 +264,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5.5',
@@ -281,6 +285,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5.5',
@@ -308,6 +313,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'health-assistant',
   name: 'health-assistant',
   instructions: 'You are a health and wellness assistant.',
   model: 'openai/gpt-5.5',
@@ -351,6 +357,7 @@ import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
@@ -666,6 +673,7 @@ const om = new ObservationalMemory({
 })
 
 export const agent = new Agent({
+  id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',

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

@@ -79,6 +79,7 @@ import { Memory } from '@mastra/memory'
 import { TokenLimiterProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'context-limited-agent',
   name: 'context-limited-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',
@@ -100,6 +101,7 @@ import { Agent } from '@mastra/core/agent'
 import { TokenLimiterProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'multi-step-agent',
   name: 'multi-step-agent',
   instructions: 'You are a helpful research assistant with access to tools',
   model: 'openai/gpt-5.5',
@@ -123,6 +125,7 @@ import { Agent } from '@mastra/core/agent'
 import { TokenLimiterProcessor } from '@mastra/core/processors'
 
 export const agent = new Agent({
+  id: 'response-limited-agent',
   name: 'response-limited-agent',
   instructions: 'You are a helpful assistant',
   model: 'openai/gpt-5.5',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/memory",
-  "version": "1.22.0-alpha.3",
+  "version": "1.22.1-alpha.0",
   "description": "",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,7 +45,7 @@
     "tokenx": "^1.3.0",
     "xxhash-wasm": "^1.1.0",
     "zod": "^4.4.3",
-    "@mastra/schema-compat": "1.3.2-alpha.1"
+    "@mastra/schema-compat": "1.3.3-alpha.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^1.3.24",
@@ -61,12 +61,12 @@
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.57.0",
     "vitest": "4.1.8",
-    "@internal/ai-sdk-v5": "0.0.56",
-    "@internal/ai-v6": "0.0.56",
-    "@internal/ai-sdk-v4": "0.0.56",
-    "@internal/types-builder": "0.0.84",
-    "@mastra/core": "1.48.0-alpha.10",
-    "@internal/lint": "0.0.109"
+    "@internal/ai-sdk-v5": "0.0.57",
+    "@internal/ai-sdk-v4": "0.0.57",
+    "@internal/ai-v6": "0.0.57",
+    "@internal/lint": "0.0.110",
+    "@internal/types-builder": "0.0.85",
+    "@mastra/core": "1.49.0-alpha.1"
   },
   "peerDependencies": {
     "@mastra/core": ">=1.4.1-0 <2.0.0-0"