@mastra/memory 1.39.1 → 1.40.0-alpha.1

package/dist/_types/@internal_ai-sdk-v4/dist/index.d.ts

@@ -35,6 +35,36 @@ export declare class AISDKError extends Error {
     protected static hasMarker(error: unknown, marker: string): boolean;
 }
 
+/**
+ * AnyValue can be:
+ * - a string, number, boolean value
+ * - a byte array (Uint8Array)
+ * - array of any value
+ * - map from string to any value (a plain Object)
+ * - null (an empty value)
+ *
+ * https://opentelemetry.io/docs/specs/otel/common/#anyvalue
+ *
+ * Notable JavaScript types that are excluded:
+ * - `undefined` - Excluding this means the common practice in instrumentations,
+ *   using `undefined` to mean "no value for this optional attribute", can
+ *   remain supported.
+ * - `BigInt`
+ * - TypedArrays other than `Uint8Array`
+ * - subclasses of Object, e.g. Date, Error
+ *
+ * The TypeScript type `unknown` is used for `AnyValue`. This has some
+ * implications:
+ * - Callers of `@opentelemetry/api` APIs using `AnyValue` can pass in
+ *   whatever type. This was always the case for (untyped) JavaScript usage.
+ * - SDK implementations of `@opentelemetry/api` need to document if/when they
+ *   support a subset of AnyValue types.
+ * - Using `unknown` allows future changes to support more types (e.g. BigInt).
+ *
+ * @since 1.10.0
+ */
+declare type AnyValue = unknown;
+
 export declare class APICallError extends AISDKError {
     private readonly [symbol$c_2];
     readonly url: string;
@@ -193,24 +223,20 @@ export declare interface Attachment {
 }
 
 /**
- * Attributes is a map from string to attribute values.
- *
- * Note: only the own enumerable keys are counted as valid attribute keys.
+ * Attributes is a mapping from string to attribute values.
+ * https://opentelemetry.io/docs/specs/otel/common/#attribute-collections
  *
- * @since 1.3.0
+ * @since 1.1.0
  */
 declare interface Attributes {
-    [attributeKey: string]: AttributeValue | undefined;
+    [attributeKey: string]: AnyValue;
 }
 
 /**
- * Attribute values may be any non-nullish primitive value except an object.
- *
- * null or undefined attribute values are invalid and will result in undefined behavior.
- *
- * @since 1.3.0
+ * @since 1.1.0
+ * @deprecated use AnyValue
  */
-declare type AttributeValue = string | number | boolean | Array<null | undefined | string> | Array<null | undefined | number> | Array<null | undefined | boolean>;
+declare type AttributeValue = AnyValue;
 
 declare type CallSettings = {
     /**
@@ -4281,7 +4307,11 @@ declare interface Link {
     context: SpanContext;
     /** A set of {@link SpanAttributes} on the link. */
     attributes?: SpanAttributes;
-    /** Count of attributes of the link that were dropped due to collection limits */
+    /**
+     * Count of attributes of the link that were dropped due to collection limits
+     *
+     * @since 1.4.1
+     */
     droppedAttributesCount?: number;
 }
 
@@ -5193,6 +5223,8 @@ declare interface Span {
      * It is preferred span links be added at span creation.
      *
      * @param link the link to add.
+     *
+     * @since 1.9.0
      */
     addLink(link: Link): this;
     /**
@@ -5202,6 +5234,8 @@ declare interface Span {
      * It is preferred span links be added at span creation.
      *
      * @param links the links to add.
+     *
+     * @since 1.9.0
      */
     addLinks(links: Link[]): this;
     /**
@@ -6995,6 +7029,11 @@ declare interface Tracer {
      * Additionally the new span gets set in context and this context is activated
      * for the duration of the function call.
      *
+     * **Important**: The callback function is responsible for calling `span.end()`
+     * to finish the span. Unlike some other OpenTelemetry implementations, the span
+     * is NOT automatically ended when the callback returns. If `span.end()` is not
+     * called, the span will never be exported and will be silently lost.
+     *
      * @param name The name of the span
      * @param [options] SpanOptions used for span creation
      * @param [context] Context to use to extract parent

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.39.1"
+  version: "1.40.0-alpha.1"
 ---
 
 ## When to use
@@ -67,11 +67,6 @@ Read the individual reference documents for detailed explanations and code examp
 - [Migration: AgentNetwork to .network()](references/reference-migrations-agentnetwork.md) - Migrate deprecated AgentNetwork usage to supervisor agents and the standard Agent.generate() or Agent.stream() APIs in current Mastra releases.
 - [Memory](references/reference-migrations-upgrade-to-v1-memory.md) - Memory configuration now requires explicit parameters, and default settings have been updated for better performance and predictability.
 - [Reference: TokenLimiterProcessor](references/reference-processors-token-limiter-processor.md) - Use TokenLimiterProcessor to constrain message tokens during prompt, input, or output processing with configurable limits and strategies.
-- [Reference: libSQL vector store](references/reference-vectors-libsql.md) - Configure LibSQLVector for similarity search and metadata filtering with local libSQL, SQLite-compatible vector extensions, or Turso databases.
-- [Reference: MongoDB vector store](references/reference-vectors-mongodb.md) - The MongoDBVector class provides vector search using MongoDB Vector Search. It enables efficient similarity search and metadata filtering within your MongoDB collections.
-- [Reference: OracleDB vector store](references/reference-vectors-oracledb.md) - OracleVector stores embeddings in Oracle Database VECTOR columns and exposes them through Mastra's vector interface.
-- [Reference: PG vector store](references/reference-vectors-pg.md) - The PgVector class provides vector search using PostgreSQL with pgvector extension. It provides reliable vector similarity search capabilities within your existing PostgreSQL database.
-- [Reference: Upstash vector store](references/reference-vectors-upstash.md) - Configure UpstashVector for serverless similarity and hybrid search, metadata filtering, index management, and vector operations with Upstash Vector.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,229 +1,229 @@
 {
-  "version": "1.39.1",
+  "version": "1.40.0-alpha.1",
   "package": "@mastra/memory",
   "exports": {
     "d": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "et": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "K": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "Y": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "z": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "B": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "V": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "H": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "U": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "O": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "u": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "l": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "X": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "q": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "G": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "J": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "D": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "C": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "k": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "A": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "Z": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "g": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "_": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "j": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "M": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "W": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "c": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "N": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "I": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "P": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "L": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "v": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "F": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "Q": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "y": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "b": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "$": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "f": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "R": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "x": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "E": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "S": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "t": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "n": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "T": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "r": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "p": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "m": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "i": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "h": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "w": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "a": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "o": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     },
     "s": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/src-CLQXrKvR.js"
+      "implementation": "dist/src-DhDMOGBn.js"
     }
   },
   "modules": {
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "src-CLQXrKvR.js"
+        "src-DhDMOGBn.js"
       ]
     }
   }

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

@@ -116,7 +116,7 @@ const stream = await agent.stream('Clean up old records', {
 })
 ```
 
-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:
+The function can be asynchronous. For decisions that depend on the tool name and arguments, use a [classifier](https://mastra.ai/docs/classifier) to estimate whether the call needs human review:
 
 ```typescript
 import { Classifier } from '@mastra/core/classifier'
@@ -589,6 +589,31 @@ A [supervisor agent](https://mastra.ai/docs/subagents) coordinates multiple suba
 
 Tool approvals also propagate through multiple levels of delegation. If a supervisor delegates to subagent A, which delegates to subagent B that has a tool with `requireApproval: true`, the approval request still surfaces at the top-level supervisor.
 
+### Identify which subagent tool paused
+
+The supervisor raises a subagent's pause on its own delegation call, so `toolCallId` on the `tool-call-approval` or `tool-call-suspended` chunk is the supervisor's call to the subagent. Always pass that `toolCallId` when you approve, decline, or resume.
+
+To show which of the subagent's tool calls paused, read these fields from the same payload:
+
+- `delegatedToolCallId`: The ID of the subagent's tool call that paused. Use it to tell apart two pauses from the same delegation, such as a question followed by an approval.
+- `delegatedToolName`: The name of the subagent's tool that paused.
+
+With several levels of delegation, both fields name the deepest tool call, the one that actually paused. Memory saves them with the pause, so they're still there when you reload the conversation, and `generate()` returns them on `suspendPayload`.
+
+```typescript
+const stream = await supervisorAgent.stream('Draft and publish the report')
+
+for await (const chunk of stream.fullStream) {
+  if (chunk.type === 'tool-call-approval' || chunk.type === 'tool-call-suspended') {
+    // Label the pause with the subagent tool call that caused it
+    console.log('Paused:', chunk.payload.delegatedToolName, chunk.payload.delegatedToolCallId)
+
+    // Pass the supervisor's delegation call when you approve, decline, or resume
+    console.log('Resume with:', chunk.payload.toolCallId)
+  }
+}
+```
+
 ### Approve and decline in supervisor agents
 
 The example below creates a subagent with a tool requiring approval. When the tool triggers an approval request, it surfaces in the supervisor's stream as a `tool-call-approval` chunk:

package/dist/docs/references/docs-guides-context-engineering.md

@@ -145,8 +145,8 @@ export const workspace = new Workspace({
   autoIndexPaths: ['**/*.md'],
 })
 
-// Agents receive tools including read_file, list_files, grep,
-// mastra_workspace_search, and mastra_workspace_index.
+// Agents receive tools including mastra_workspace_read_file, mastra_workspace_list_files,
+// mastra_workspace_grep, mastra_workspace_search, and mastra_workspace_index.
 await workspace.init()
 ```
 

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

@@ -292,6 +292,19 @@ await mastra.backgroundTaskManager?.resume(taskId, {
 })
 ```
 
+### Resume when no slot is free
+
+By default, `resume()` throws `Concurrency limit reached` when every concurrency slot is in use. Pass `{ onNoSlot: 'queue' }` to queue the resume instead:
+
+```typescript
+const task = await mastra.backgroundTaskManager?.resume(taskId, resumeData, { onNoSlot: 'queue' })
+// task.status is still 'suspended' until a slot frees up
+```
+
+The task stays `suspended` until a slot frees up, then resumes with the queued `resumeData`. Cancelling the task drops the queued resume.
+
+The queue lives in the memory of the process that called `resume()`. If that process exits before the resume runs, the task stays `suspended` and the `resumeData` is lost. To survive restarts, persist the resume data yourself and call `resume()` again.
+
 ### What happens to the agent loop
 
 When a task suspends mid-`stream()` with `untilIdle`, the wrapper treats it as terminal for the current iteration and closes. Once the resume payload is available, call `agent.resumeStream(resumeData, { runId, toolCallId, memory, untilIdle: true })` to continue immediately. The resumed background task completes and adds its result to the message list before the agent runs a follow-up turn on the same SSE connection. To drive the resume out of band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly. Its result is still written into the thread for the next user turn.
@@ -310,7 +323,7 @@ Each layer can register terminal-state callbacks. They don't replace one another
 
 - Tool-level `background.onComplete` / `onFailed`: scoped to one tool.
 - Agent-level `backgroundTasks.onTaskComplete` / `onTaskFailed`: scoped to all tasks dispatched by this agent.
-- Manager-level `onTaskComplete` / `onTaskFailed`: scoped globally.
+- Manager-level `onTaskComplete` / `onTaskFailed`: scoped globally. These fire for every task, including tasks from [non-agent owners](#non-agent-owners).
 
 ```typescript
 import { Mastra } from '@mastra/core'
@@ -398,6 +411,77 @@ const { tasks, total } = await mastra.backgroundTaskManager?.listTasks({
 
 These read from storage rather than the pubsub stream, so they're suitable for paginated lists and detail views.
 
+## Non-agent owners
+
+Code other than agents can run tasks through the manager. For example, an MCP server can run long tool calls as background tasks. The task's `agentId` is its owner key, and agent streams, `untilIdle`, and the end-of-step wait only see tasks whose `agentId` matches the agent. Use a namespaced owner key such as `mcp-server:<serverId>` so it can't collide with a real agent ID. Mastra doesn't enforce this.
+
+Non-agent owners usually register a static executor with `registerStaticExecutor()` so any process can run or recover their tasks. They can also set these optional task fields:
+
+- `expiresAt`: When cleanup deletes the task. Once a task completes, fails, is cancelled, or times out, cleanup deletes it after `expiresAt` passes instead of using `completedTtlMs` or `failedTtlMs`. Cleanup only runs when you set the `cleanup` option, and it never deletes a pending, running, or suspended task, so cancel expired work first. It also needs a storage adapter version that supports `expiresAt`. Older adapters keep using the global retention settings.
+- `metadata`: JSON stored with the task. The manager doesn't read it.
+
+```typescript
+mastra.backgroundTaskManager?.registerStaticExecutor('mcp-server:ops:deploy', {
+  execute: runDeploy,
+})
+
+await mastra.backgroundTaskManager?.enqueue({
+  agentId: 'mcp-server:ops',
+  toolName: 'mcp-server:ops:deploy',
+  toolCallId: taskId,
+  runId: taskId,
+  args,
+  resourceId: principalId,
+  expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
+  metadata: { ttlMs: 86_400_000 },
+})
+```
+
+Use `perOwnerConcurrency` to give an owner its own concurrency limit instead of `perAgentConcurrency`. Its tasks still count toward `globalConcurrency`:
+
+```typescript
+export const mastra = new Mastra({
+  storage,
+  backgroundTasks: {
+    enabled: true,
+    globalConcurrency: 60,
+    perOwnerConcurrency: { 'mcp-server:ops': 50 },
+  },
+})
+```
+
+Known limitations:
+
+- A recovered task runs without the original request. Store anything the executor needs, such as the principal in `resourceId` or other JSON in `metadata`, on the task itself.
+- A `pending` task that isn't pinned holds no lease. On startup, another process can pick it up and dispatch it. If its executor only existed in the original process, the task fails with `No executor registered`. Static executors registered in every process avoid this. Use `pinToWorker` when the original process already started the work.
+- The end-of-step wait in the agent loop only waits for `running` tasks, not `pending` ones. [#28228](https://github.com/mastra-ai/mastra/pull/28228) tracks the fix.
+
+### Pin a task to the current worker
+
+Sometimes work for a task is already running in this process before you enqueue it. For example, an MCP server may start a tool call inside the request and hand it to a background task only if it runs long. Pass `pinToWorker: true` with a task context so no other process starts the same work:
+
+```typescript
+await mastra.backgroundTaskManager?.enqueue(
+  {
+    agentId: 'mcp-server:ops',
+    toolName: 'mcp-server:ops:deploy',
+    toolCallId: taskId,
+    runId: taskId,
+    args,
+  },
+  { executor: { execute: adoptRunningDeploy } },
+  { pinToWorker: true },
+)
+```
+
+`pinToWorker` means work for this task is already in flight on this worker. The `pending` task records this worker as its owner and holds an execution lease, which the worker renews while the task waits for a free slot. Other processes don't recover or dispatch the task while the lease is live.
+
+If the worker dies or shuts down first, that work is lost. Recovery treats the task as a lost attempt, like a running task whose worker died. If `retryCount` is below `maxRetries`, the task uses a retry and runs on another worker, which needs a static executor for it. Otherwise the task fails with `Worker process terminated before task completed`. A task with `maxRetries: 0` never runs on another worker. Other processes check for lapsed pins at startup and then every `leaseDurationMs`, unless `recoverStaleTasksOnStart` is `false`.
+
+A lapsed lease only shows that the worker stopped renewing it, not that the work stopped. A worker whose event loop stalls past the lease can still be running the task when another worker retries it. Make pinned work idempotent, or guard its side effects, if it can be retried.
+
+`pinToWorker` throws without a task context. Tasks that aren't pinned, including all agent tasks, hold no lease while `pending`.
+
 ## Related
 
 - [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)

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

@@ -12,13 +12,13 @@ Memory processors are [processors](https://mastra.ai/docs/agents/processors) tha
 
 ## Built-in memory processors
 
-Mastra automatically adds these processors when memory is enabled:
+Mastra automatically adds these processors when memory is enabled. `MemoryInputFilter` is added only when a memory store is available and stored history will be loaded:
 
 ### `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.
+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. When `retainFullInput: true` is set, it skips both the trim and the metadata strip and processes the input exactly as supplied, while stored history still loads.
 
-This processor runs first so `MessageHistory`, `SemanticRecall`, and Observational Memory receive only the new input they need.
+By default, this processor runs first so `MessageHistory`, `SemanticRecall`, and Observational Memory receive only the new input they need.
 
 ### `MessageHistory`
 
@@ -320,6 +320,52 @@ const agent = new Agent({
 
 Both scenarios are safe - guardrails prevent inappropriate content from being persisted to memory
 
+## Aborted runs and saved messages
+
+Cancelling a run and blocking it with a processor `abort()` both stop generation, but they save different things:
+
+| What stops the run            | Memory processors | What's persisted                                             |
+| ----------------------------- | ----------------- | ------------------------------------------------------------ |
+| `abortSignal` from the caller | Still run         | The user message and the assistant text the user already saw |
+| `abort()` inside a processor  | Skipped           | Nothing; the tripwire blocks the save                        |
+
+A caller cancellation goes through output processors like any other run, so the built-in `MessageHistory` processor saves the thread. The partial answer is stored as an ordinary assistant message with no error part, which means the next turn starts from what the user actually read.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+const memory = new Memory({ options: { lastMessages: 20 } })
+const agent = new Agent({
+  id: 'writer',
+  name: 'writer',
+  instructions: 'You write step-by-step migration guides.',
+  model: 'openai/gpt-6.1-sol',
+  memory,
+})
+
+const controller = new AbortController()
+const stream = await agent.stream('Write the migration guide.', {
+  memory: { thread: 'thread-1', resource: 'user-1' },
+  abortSignal: controller.signal,
+  onAbort: ({ steps, text }) => {
+    console.log(`Aborted after ${steps.length} steps with ${text?.length ?? 0} characters streamed`)
+  },
+})
+
+let streamed = ''
+for await (const chunk of stream.fullStream) {
+  if (chunk.type !== 'text-delta') continue
+  streamed += chunk.payload.text
+  if (streamed.length > 200) controller.abort()
+}
+
+// The partial answer is already in the thread
+const { messages } = await memory.recall({ threadId: 'thread-1', resourceId: 'user-1' })
+```
+
+`onAbort` receives the steps that completed before the cancellation and the assistant text streamed for the in-flight step. For the abort lifecycle itself, including durable runs aborted by `runId`, see the [`stream()` reference](https://mastra.ai/reference/streaming/agents/stream).
+
 ## Handling large attachments
 
 Some storage providers enforce record size limits that base64-encoded file attachments can exceed: