@mastra/memory 1.17.5 → 1.17.6-alpha.1

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.17.5"
+  version: "1.17.6-alpha.1"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,119 +1,119 @@
 {
-  "version": "1.17.5",
+  "version": "1.17.6-alpha.1",
   "package": "@mastra/memory",
   "exports": {
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
+      "implementation": "dist/chunk-QZGJY67D.js",
       "line": 745
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js"
+      "implementation": "dist/chunk-QZGJY67D.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 6598
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 6674
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 9140
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 9219
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 6068
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 6144
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 3567
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 3643
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 2950
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 2951
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
+      "implementation": "dist/chunk-QZGJY67D.js",
       "line": 837
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
+      "implementation": "dist/chunk-QZGJY67D.js",
       "line": 871
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 3681
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 3757
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 3293
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 3369
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 9346
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 9425
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 3669
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 3745
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 2498
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 2499
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 3692
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 3768
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 2471
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 2472
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
+      "implementation": "dist/chunk-QZGJY67D.js",
       "line": 806
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 3577
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 3653
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
+      "implementation": "dist/chunk-QZGJY67D.js",
       "line": 895
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
+      "implementation": "dist/chunk-QZGJY67D.js",
       "line": 851
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
-      "line": 2528
+      "implementation": "dist/chunk-QZGJY67D.js",
+      "line": 2529
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
+      "implementation": "dist/chunk-QZGJY67D.js",
       "line": 828
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-BPJLUC2F.js",
+      "implementation": "dist/chunk-QZGJY67D.js",
       "line": 799
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
@@ -149,7 +149,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-BPJLUC2F.js",
+        "chunk-QZGJY67D.js",
         "chunk-LSJJAJAF.js"
       ]
     }

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

@@ -127,10 +127,12 @@ When a tool call dispatches as a background task, two streams may surface lifecy
 | `background-task-completed` | The task finished successfully. The `payload.result` matches the eventual tool result. | Manager stream |
 | `background-task-failed`    | The task threw or timed out.                                                           | Manager stream |
 | `background-task-cancelled` | The task was cancelled before completing.                                              | Manager stream |
+| `background-task-suspended` | The tool called `suspend()` from inside its execute.                                   | Manager stream |
+| `background-task-resumed`   | A suspended task was resumed via `manager.resume(taskId, resumeData)`.                 | Manager stream |
 
-`agent.stream().fullStream` only emits the agent-loop chunks (`background-task-started`, `background-task-progress`) on its own. `agent.streamUntilIdle()` emits the same two chunks and additionally subscribes to the manager pubsub for the run's memory scope and pipes the five manager chunks (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`) into the same `fullStream`, so consumers of `streamUntilIdle().fullStream` see all seven types.
+`agent.stream().fullStream` only emits the agent-loop chunks (`background-task-started`, `background-task-progress`) on its own. `agent.streamUntilIdle()` emits the same two chunks and additionally subscribes to the manager pubsub for the run's memory scope and pipes the seven manager chunks (`background-task-running`, `background-task-output`, `background-task-completed`, `background-task-failed`, `background-task-cancelled`, `background-task-suspended`, `background-task-resumed`) into the same `fullStream`.
 
-`backgroundTaskManager.stream()` only emits the five manager chunks.
+`backgroundTaskManager.stream()` only emits the seven manager chunks.
 
 The full payload shapes are documented in the [background task chunks reference](https://mastra.ai/reference/streaming/ChunkType).
 
@@ -210,6 +212,64 @@ When this `researchAgent` is delegated to from a supervisor that has no backgrou
 
 Use this pattern when you want a subagent to behave consistently in the background regardless of which supervisor invokes it. Use the supervisor-side opt-in (above) when you want to tune background behavior centrally per supervisor.
 
+## Suspending and resuming
+
+A background task can pause itself mid-execution and wait for an external signal before continuing. This is useful for human approvals, webhooks, or any flow where the next step depends on data that arrives later.
+
+A tool calls `suspend(data)` from inside its `execute`, which:
+
+- Persists `status: 'suspended'` and the `data` payload on the task record.
+- Saves the workflow snapshot so the run survives process restarts.
+- Emits a `background-task-suspended` chunk on the manager stream.
+- Releases the concurrency slot so other tasks can run.
+
+Resume the task with `mastra.backgroundTaskManager.resume(taskId, resumeData)`. The `resumeData` arrives in the tool's `execute` options on the resumed run, and the task transitions back to `running`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const reviewTool = createTool({
+  id: 'review',
+  description: 'Submit a draft for human review.',
+  inputSchema: z.object({ draft: z.string() }),
+  outputSchema: z.object({ approvedBy: z.string(), edits: z.string().optional() }),
+  background: { enabled: true },
+  execute: async ({ draft }, context) => {
+    const { suspend, resumeData } = context.agent
+    if (!resumeData) {
+      await suspend?.({ awaiting: 'approval', draft })
+      return { approvedBy: '', edits: undefined }
+    }
+    const { reviewer, edits } = resumeData as { reviewer: string; edits?: string }
+    return { approvedBy: reviewer, edits }
+  },
+})
+```
+
+The first invocation of `execute` sees `resumeData === undefined` and calls `suspend`. After the task is resumed, the runtime restarts the tool with `resumeData` populated; the `if` branch falls through and the tool returns its real result.
+
+To resume the task once an approval arrives:
+
+```typescript
+await mastra.backgroundTaskManager?.resume(taskId, {
+  reviewer: 'alice@example.com',
+  edits: 'Reworded paragraph 3.',
+})
+```
+
+### What happens to the agent loop
+
+When a task suspends mid-`streamUntilIdle()`, the wrapper treats it as terminal for the current iteration and closes. To continue the agent immediately when the resume payload is in hand, call `agent.resumeStreamUntilIdle(resumeData, { runId, toolCallId, memory })`: the resumed bg task runs to completion, its result lands in the message list, and the agent runs a follow-up turn — all on the same SSE connection. If you'd rather drive the resume out-of-band, call `mastra.backgroundTaskManager.resume(taskId, resumeData)` directly and the result still writes into the thread for the next user turn to pick up.
+
+### Re-registering the executor on resume
+
+The manager keeps tool executors in process memory. If the process restarts while a task is suspended, the executor closure is gone — the caller of `resume()` must re-register it first via `manager.registerTaskContext(taskId, ...)`. Tasks dispatched and resumed inside the same process don't need this.
+
+### Cancelling a suspended task
+
+`manager.cancel(taskId)` works against suspended tasks the same way it works for running ones: the row flips to `cancelled`, the workflow snapshot is cleaned up, and a `task.cancelled` event fires.
+
 ## Lifecycle callbacks
 
 Each layer can register terminal-state callbacks. They don't replace one another, and success/failure hooks fire for their respective outcomes:

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

@@ -216,7 +216,7 @@ The Observer and Reflector run in the background. Any model that works with Mast
 
 Generally speaking, we recommend using a model that has a large context window (128K+ tokens) and is fast enough to run in the background without slowing down your actions.
 
-If you're unsure which model to use, start with the default `google/gemini-2.5-flash`. We've also successfully tested `openai/gpt-5-mini`, `anthropic/claude-haiku-4-5`, `deepseek/deepseek-reasoner`, `qwen3`, and `glm-4.7`.
+If you're unsure which model to use, start with the default `google/gemini-2.5-flash`. We've also successfully tested `openai/gpt-5-mini`, `anthropic/claude-haiku-4-5`, `deepseek/deepseek-reasoner`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `xai/grok-4-1-fast`, `qwen3`, and `glm-4.7`.
 
 ```typescript
 const memory = new Memory({
@@ -230,6 +230,10 @@ const memory = new Memory({
 
 See [model configuration](https://mastra.ai/reference/memory/observational-memory) for using different models per agent.
 
+> **Note:** `google/gemini-2.5-flash` is unusually good at preserving detail in long output. As a result, the Reflector can produce reflections that stay above the configured `reflection.observationTokens` threshold even after the maximum compression retry. When this happens, the Reflector returns the smallest non-degenerate candidate produced during retries so the loop terminates instead of running forever.
+>
+> If you'd rather have more aggressive compression on the Reflector, swap to a model that condenses more readily, such as `xai/grok-4-1-fast`, `deepseek/deepseek-v4-pro`, or `deepseek/deepseek-v4-flash`. You can keep `google/gemini-2.5-flash` for the Observer and use a different model for the Reflector — see [different models per agent](https://mastra.ai/reference/memory/observational-memory).
+
 ### Token-tiered model selection
 
 **Added in:** `@mastra/memory@1.10.0`
@@ -458,4 +462,5 @@ In practical terms, OM replaces both working memory and message history, and has
 - [Observational Memory Reference](https://mastra.ai/reference/memory/observational-memory)
 - [Memory Overview](https://mastra.ai/docs/memory/overview)
 - [Message History](https://mastra.ai/docs/memory/message-history)
-- [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
+- [Memory Processors](https://mastra.ai/docs/memory/memory-processors)
+- [Mastra Code](https://code.mastra.ai/): A coding agent using Observational Memory

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

@@ -237,4 +237,5 @@ export const memoryAgent = new Agent({
 
 - [`Memory` reference](https://mastra.ai/reference/memory/memory-class)
 - [Tracing](https://mastra.ai/docs/observability/tracing/overview)
-- [Request Context](https://mastra.ai/docs/server/request-context)
+- [Request Context](https://mastra.ai/docs/server/request-context)
+- [Mastra Code](https://code.mastra.ai/): A coding agent using Mastra's memory system