@mastra/memory 1.31.0 → 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"
+  version: "1.32.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.31.0",
+  "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).
 

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,6 +45,8 @@ 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.

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-DcZ7iuK6.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-zTE4189S.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-DcZ7iuK6.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-zTE4189S.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"}