@mastra/memory 1.31.0-alpha.3 → 1.32.0-alpha.0

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

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.31.0-alpha.3",
+  "version": "1.32.0-alpha.0",
   "package": "@mastra/memory",
   "exports": {},
   "modules": {

package/dist/docs/references/docs-agents-human-in-the-loop.md

@@ -116,7 +116,44 @@ const stream = await agent.stream('Clean up old records', {
 })
 ```
 
-A tool's own `requireApproval` setting takes precedence over the function above. Its rule decides whether that tool needs approval. If the function throws, the call requires approval as a fail-safe.
+The function can be asynchronous. For decisions that depend on the tool name and arguments, use a [classifier](https://mastra.ai/reference/classifier/classifier) to estimate whether the call needs human review:
+
+```typescript
+import { Classifier } from '@mastra/core/classifier'
+import { model } from '../models/evaluation-model'
+import { agent } from './agent'
+
+const approvalClassifier = new Classifier({
+  id: 'tool-approval-classifier',
+  model,
+  questions: {
+    requiresApproval: {
+      type: 'boolean',
+      instructions:
+        'Does this tool call need human approval because it is destructive, irreversible, expensive, or handles sensitive data?',
+    },
+  },
+})
+
+const stream = await agent.stream('Clean up old records', {
+  requireToolApproval: async ({ toolName, args }) => {
+    const result = await approvalClassifier.evaluate({
+      state: {
+        toolName,
+        argumentNames: Object.keys(args),
+      },
+    })
+
+    return result.answers.requiresApproval.probability >= 0.7
+  },
+})
+```
+
+The example sends argument names rather than values because the classifier forwards its state to the configured evaluation model. If the decision requires argument values, redact sensitive data first or use an evaluation model and provider that meet the protected tool's data-handling requirements.
+
+Returning `true` pauses the tool call for human approval. It doesn't approve or decline the call automatically. Choose a threshold that matches the risk of the tools available to the agent. If this `requireToolApproval` function throws, it defaults to requiring approval.
+
+The runtime then combines that result with the tool's `requireApproval` setting. A boolean `true` requires approval, while `false` doesn't disable approval required by `requireToolApproval`. A tool-level `requireApproval` function is authoritative and replaces the combined result for that tool.
 
 > **Note:** Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
 

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

@@ -14,6 +14,12 @@ Memory processors are [processors](https://mastra.ai/docs/agents/processors) tha
 
 Mastra automatically adds these processors when memory is enabled:
 
+### `MemoryInputFilter`
+
+Trims client-echoed history before memory loaders run. For an existing thread, it keeps only the current user turn or new tool results. For an empty thread, it keeps the full initial input and removes provider item metadata from assistant parts that could refer to items that don't exist in storage.
+
+This processor runs first so `MessageHistory`, `SemanticRecall`, and Observational Memory receive only the new input they need.
+
 ### `MessageHistory`
 
 Retrieves message history and persists new messages.
@@ -206,7 +212,7 @@ Understanding the execution order is important when combining guardrails with me
 [Memory Processors] → [Your inputProcessors]
 ```
 
-1. **Memory processors run FIRST**: `WorkingMemory`, `MessageHistory`, `SemanticRecall`
+1. **Memory processors run FIRST**: `MemoryInputFilter`, then `WorkingMemory`, `MessageHistory`, and `SemanticRecall`
 2. **Your input processors run AFTER**: guardrails, filters, validators
 
 As a result, memory loads message history before your processors can validate or filter the input.

package/dist/docs/references/docs-memory-message-history.md

@@ -12,7 +12,9 @@ You can also retrieve message history to display past conversations in your UI.
 
 > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
 >
-> Sending the full history is redundant because Mastra loads messages from storage, and it can cause message ordering bugs when client-side timestamps conflict with stored timestamps.
+> Sending the full history is redundant because Mastra loads messages from storage. Mastra filters client-echoed history before loading stored messages and uses the stored copy as the base when message IDs match, preserving stored timestamps and provider metadata while retaining new tool results.
+>
+> If you assemble the request input yourself and need it processed exactly as sent, set `retainFullInput: true` on `memory.options` for that call, or in the memory constructor options to apply it agent-wide. This disables the filtering described above. History still loads underneath. Every input message that isn't already stored is saved to the thread, including few-shot examples.
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/integrations/agentic-ui/ai-sdk-ui).
 
@@ -170,6 +172,43 @@ export const supportAgent = new Agent({
 
 Title generation runs asynchronously after the agent responds and doesn't affect response time.
 
+### Streaming the generated title
+
+By default title generation runs in the background and the run's stream doesn't wait for it, so HTTP clients only see the title on their next thread fetch. Set `emitEvent: true` to deliver the title on the run's stream instead: the stream waits for the title and emits a transient `data-thread-title` chunk before `finish`.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    options: {
+      generateTitle: {
+        emitEvent: true,
+      },
+    },
+  }),
+})
+```
+
+Stream consumers receive the chunk with the persisted title, so a chat UI can rename its thread list entry without polling:
+
+```typescript
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'data-thread-title') {
+    renameThreadInSidebar(chunk.data.threadId, chunk.data.title)
+  }
+}
+```
+
+The chunk is transient: it's delivered to stream consumers but never persisted as part of the conversation's messages. Because the stream waits for the title, `emitEvent` delays the stream's `finish` on the turn that generates the title: the first turn of a thread, or a later turn when `minMessages` sets a higher threshold. Leave it off to keep title generation fully non-blocking.
+
+> **Note:** `emitEvent` applies to `stream()` runs. `generate()` returns JSON and can't carry the chunk, so it keeps non-blocking title generation. [Durable and evented agents](https://mastra.ai/docs/harness/durable-agents) don't emit this chunk yet. In all of these cases the title is still generated and persisted.
+
 To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`:
 
 ```typescript

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

@@ -92,7 +92,9 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 
 > **Warning:** When you use OM with a client application, send **only the new message** from the client instead of the full conversation history.
 >
-> Observational memory still relies on stored conversation history. Sending the full history is redundant and can cause message ordering bugs when client-side timestamps conflict with stored timestamps.
+> Observational memory still relies on stored conversation history. Sending the full history is redundant and can cause message ordering bugs when client-side timestamps conflict with stored timestamps. Mastra filters client-echoed history before loading stored messages and uses the stored copy as the base when message IDs match, preserving stored timestamps and provider metadata while retaining new tool results.
+>
+> If you assemble the request input yourself and need it processed exactly as sent, set `retainFullInput: true` on `memory.options` for that call, or in the memory constructor options to apply it agent-wide. This disables that filtering. History still loads underneath. Every input message that isn't already stored is saved to the thread, including few-shot examples.
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/integrations/agentic-ui/ai-sdk-ui).
 

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

@@ -45,13 +45,15 @@ export const agent = new Agent({
 
 **options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
 
+**options.retainFullInput** (`boolean`): When true, the request input is processed exactly as supplied instead of being filtered against stored history. Use this when you assemble the input yourself and need the message sequence preserved. Stored history is still loaded underneath, and every input message that isn't already stored is saved to the thread, including few-shot examples. Can be set per call on memory.options or agent-wide in the memory constructor options.
+
 **options.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured. Default topK is 4, default messageRange is {before: 1, after: 1}.
 
 **options.workingMemory** (`WorkingMemory`): Configuration for working memory feature. Can be { enabled: boolean; template?: string; schema?: ZodObject\<any> | JSONSchema7; scope?: 'thread' | 'resource' } or { enabled: boolean } to disable.
 
 **options.observationalMemory** (`boolean | ObservationalMemoryOptions`): Enable Observational Memory for long-context agentic memory. Set to true for defaults, or pass a config object to customize token budgets, models, and scope. See Observational Memory reference for configuration details.
 
-**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): Controls automatic thread title generation from the conversation transcript. Can be a boolean or an object with custom model and instructions.
+**options.generateTitle** (`boolean | { model?: DynamicArgument<MastraModelConfig>; instructions?: DynamicArgument<string>; minMessages?: number; emitEvent?: boolean }`): Controls automatic thread title generation from the conversation transcript. Accepts a boolean or an object with a custom model (any MastraModelConfig: a model instance, a "provider/model" ID, or an OpenAI-compatible config; defaults to the agent's own model), custom instructions, a minimum message count, and emitEvent. With emitEvent: true the run's stream waits for the title and emits it as a transient data-thread-title chunk before finish (durable and evented agents persist the title but don't emit the chunk yet).
 
 ## Returns
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-QqTmOY5X.cjs");
+const require_src = require("./src-DmZEArj1.cjs");
 let _mastra_core_processors = require("@mastra/core/processors");
 exports.Extractor = require_src.Extractor;
 exports.KnowledgeSemanticIndexCoordinator = require_src.KnowledgeSemanticIndexCoordinator;

package/dist/index.js

@@ -1,2 +1,2 @@
-import { C as SUMMARIZE_THREAD_DEFAULTS, G as ModelByInputTokens, H as KnowledgeSemanticIndexCoordinator, S as WorkingMemoryExtractor, U as StaleKnowledgeSemanticIndexError, V as Subconscious, X as Extractor, a as extractWorkingMemoryContent, b as WorkingMemoryStateProcessor, c as getObservationsAsOf, i as WorkingMemory, n as MessageHistory, o as extractWorkingMemoryTags, r as SemanticRecall, s as removeWorkingMemoryTags, t as Memory, v as WORKING_MEMORY_STATE_ID, w as summarizeConversation, x as deepMergeWorkingMemory, y as WORKING_MEMORY_STATE_PROCESSOR_ID } from "./src-CSVmHSng.js";
+import { C as SUMMARIZE_THREAD_DEFAULTS, G as ModelByInputTokens, H as KnowledgeSemanticIndexCoordinator, S as WorkingMemoryExtractor, U as StaleKnowledgeSemanticIndexError, V as Subconscious, X as Extractor, a as extractWorkingMemoryContent, b as WorkingMemoryStateProcessor, c as getObservationsAsOf, i as WorkingMemory, n as MessageHistory, o as extractWorkingMemoryTags, r as SemanticRecall, s as removeWorkingMemoryTags, t as Memory, v as WORKING_MEMORY_STATE_ID, w as summarizeConversation, x as deepMergeWorkingMemory, y as WORKING_MEMORY_STATE_PROCESSOR_ID } from "./src-2UN5fCQ5.js";
 export { Extractor, KnowledgeSemanticIndexCoordinator, Memory, MessageHistory, ModelByInputTokens, SUMMARIZE_THREAD_DEFAULTS, SemanticRecall, StaleKnowledgeSemanticIndexError, Subconscious, WORKING_MEMORY_STATE_ID, WORKING_MEMORY_STATE_PROCESSOR_ID, WorkingMemory, WorkingMemoryExtractor, WorkingMemoryStateProcessor, deepMergeWorkingMemory, extractWorkingMemoryContent, extractWorkingMemoryTags, getObservationsAsOf, removeWorkingMemoryTags, summarizeConversation };

package/dist/processors/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("../src-QqTmOY5X.cjs");
+const require_src = require("../src-DmZEArj1.cjs");
 exports.Extractor = require_src.Extractor;
 exports.KnowledgeSemanticIndexCoordinator = require_src.KnowledgeSemanticIndexCoordinator;
 exports.ModelByInputTokens = require_src.ModelByInputTokens;

package/dist/processors/index.js

@@ -1,2 +1,2 @@
-import { A as formatMessagesForObserver, B as OBSERVATION_CONTINUATION_HINT, D as buildObserverPrompt, E as OBSERVER_SYSTEM_PROMPT, F as parseAnchorId, G as ModelByInputTokens, H as KnowledgeSemanticIndexCoordinator, I as stripEphemeralAnchorIds, J as publishSubconsciousActivity, K as SUBCONSCIOUS_ACTIVITY_STATE_ID, L as OBSERVATIONAL_MEMORY_DEFAULTS, M as optimizeObservationsForContext, N as parseObserverOutput, O as buildObserverSystemPrompt, P as injectAnchorIds, R as OBSERVATION_CONTEXT_INSTRUCTIONS, S as WorkingMemoryExtractor, T as TokenCounter, U as StaleKnowledgeSemanticIndexError, V as Subconscious, W as SubconsciousRemindExtractor, X as Extractor, Y as renderSubconsciousActivity, _ as wrapInObservationGroup, c as getObservationsAsOf, d as combineObservationGroupRanges, f as deriveObservationGroupProvenance, g as stripObservationGroups, h as renderObservationGroupsForReflection, j as hasCurrentTaskSection, k as extractCurrentTask, l as ObservationalMemoryProcessor, m as reconcileObservationGroupsFromReflection, p as parseObservationGroups, q as buildSubconsciousActivitySnapshot, u as ObservationalMemory, w as summarizeConversation, z as OBSERVATION_CONTEXT_PROMPT } from "../src-CSVmHSng.js";
+import { A as formatMessagesForObserver, B as OBSERVATION_CONTINUATION_HINT, D as buildObserverPrompt, E as OBSERVER_SYSTEM_PROMPT, F as parseAnchorId, G as ModelByInputTokens, H as KnowledgeSemanticIndexCoordinator, I as stripEphemeralAnchorIds, J as publishSubconsciousActivity, K as SUBCONSCIOUS_ACTIVITY_STATE_ID, L as OBSERVATIONAL_MEMORY_DEFAULTS, M as optimizeObservationsForContext, N as parseObserverOutput, O as buildObserverSystemPrompt, P as injectAnchorIds, R as OBSERVATION_CONTEXT_INSTRUCTIONS, S as WorkingMemoryExtractor, T as TokenCounter, U as StaleKnowledgeSemanticIndexError, V as Subconscious, W as SubconsciousRemindExtractor, X as Extractor, Y as renderSubconsciousActivity, _ as wrapInObservationGroup, c as getObservationsAsOf, d as combineObservationGroupRanges, f as deriveObservationGroupProvenance, g as stripObservationGroups, h as renderObservationGroupsForReflection, j as hasCurrentTaskSection, k as extractCurrentTask, l as ObservationalMemoryProcessor, m as reconcileObservationGroupsFromReflection, p as parseObservationGroups, q as buildSubconsciousActivitySnapshot, u as ObservationalMemory, w as summarizeConversation, z as OBSERVATION_CONTEXT_PROMPT } from "../src-2UN5fCQ5.js";
 export { Extractor, KnowledgeSemanticIndexCoordinator, ModelByInputTokens, OBSERVATIONAL_MEMORY_DEFAULTS, OBSERVATION_CONTEXT_INSTRUCTIONS, OBSERVATION_CONTEXT_PROMPT, OBSERVATION_CONTINUATION_HINT, OBSERVER_SYSTEM_PROMPT, ObservationalMemory, ObservationalMemoryProcessor, SUBCONSCIOUS_ACTIVITY_STATE_ID, StaleKnowledgeSemanticIndexError, Subconscious, SubconsciousRemindExtractor, TokenCounter, WorkingMemoryExtractor, buildObserverPrompt, buildObserverSystemPrompt, buildSubconsciousActivitySnapshot, combineObservationGroupRanges, deriveObservationGroupProvenance, extractCurrentTask, formatMessagesForObserver, getObservationsAsOf, hasCurrentTaskSection, injectAnchorIds, optimizeObservationsForContext, parseAnchorId, parseObservationGroups, parseObserverOutput, publishSubconsciousActivity, reconcileObservationGroupsFromReflection, renderObservationGroupsForReflection, renderSubconsciousActivity, stripEphemeralAnchorIds, stripObservationGroups, summarizeConversation, wrapInObservationGroup };

package/dist/processors/observational-memory/observation-turn/load-memory-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load-memory-context.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-turn/load-memory-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,wBAAsB,yBAAyB,CAAC,EAC9C,MAAM,EACN,WAAW,EACX,QAAQ,EACR,UAAU,EACV,QAAQ,GACT,EAAE;IACD,MAAM,EAAE,qBAAqB,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,qBAAqB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAYpE"}
+{"version":3,"file":"load-memory-context.d.ts","sourceRoot":"","sources":["../../../../src/processors/observational-memory/observation-turn/load-memory-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,wBAAsB,yBAAyB,CAAC,EAC9C,MAAM,EACN,WAAW,EACX,QAAQ,EACR,UAAU,EACV,QAAQ,GACT,EAAE;IACD,MAAM,EAAE,qBAAqB,CAAC;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,qBAAqB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAUpE"}