@mastra/memory 1.22.1 → 1.22.2-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.22.1"
+  version: "1.22.2-alpha.0"
 ---
 
 ## When to use
@@ -17,11 +17,11 @@ Read the individual reference documents for detailed explanations and code examp
 ### Docs
 
 - [Agent approval](references/docs-agents-agent-approval.md) - Learn how to require approvals, suspend tool execution, and automatically resume suspended tools while keeping humans in control of agent workflows.
-- [Background tasks](references/docs-agents-background-tasks.md) - Learn how to dispatch long-running tool calls in the background, keep the stream open until they complete, and orchestrate subagents asynchronously.
-- [Goals](references/docs-agents-goals.md) - Learn how to set a durable objective on an agent that is judged in the execution loop, so the agent keeps working until the goal is complete or the run budget is exhausted.
 - [Agent networks](references/docs-agents-networks.md) - Coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
 - [Supervisor agents](references/docs-agents-supervisor-agents.md) - Learn how to coordinate multiple agents with delegation hooks, iteration monitoring, message filtering, and task completion scoring.
 - [Evals with memory](references/docs-evals-evals-with-memory.md) - Run scorers against memory-enabled agents — including observational memory in thread scope — using runEvals and dataset experiments.
+- [Background tasks](references/docs-long-running-agents-background-tasks.md) - Learn how to dispatch long-running tool calls in the background, keep the stream open until they complete, and orchestrate subagents asynchronously.
+- [Goals](references/docs-long-running-agents-goals.md) - Learn how to set a durable objective on an agent that is judged in the execution loop, so the agent keeps working until the goal is complete or the run budget is exhausted.
 - [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
 - [Message history](references/docs-memory-message-history.md) - Learn how to configure message history in Mastra to store recent messages from the current conversation.
 - [Multi-user threads](references/docs-memory-multi-user-threads.md) - Share one Mastra thread between multiple users by carrying speaker identity in the message body.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,129 +1,129 @@
 {
-  "version": "1.22.1",
+  "version": "1.22.2-alpha.0",
   "package": "@mastra/memory",
   "exports": {
     "Extractor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 316
     },
     "ModelByInputTokens": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 1354
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js"
+      "implementation": "dist/chunk-TB6SV7QK.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 27532
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 27533
     },
     "ObservationalMemoryProcessor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 30163
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 30164
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 26857
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 26858
     },
     "WorkingMemoryExtractor": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 20684
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 4465
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 3732
     },
     "combineObservationGroupRanges": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 1446
     },
     "deriveObservationGroupProvenance": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 1480
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 4588
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 4187
     },
     "getObservationsAsOf": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 30385
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 30386
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 4576
     },
     "injectAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 3287
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 4599
     },
     "parseAnchorId": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 3260
     },
     "parseObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 1415
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 4479
     },
     "reconcileObservationGroupsFromReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 1504
     },
     "renderObservationGroupsForReflection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 1460
     },
     "stripEphemeralAnchorIds": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 3317
     },
     "stripObservationGroups": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 1437
     },
     "wrapInObservationGroup": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
+      "implementation": "dist/chunk-TB6SV7QK.js",
       "line": 1408
     },
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
@@ -144,40 +144,40 @@
     },
     "Memory": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 22108
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 22109
     },
     "MessageHistory": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js"
+      "implementation": "dist/chunk-TB6SV7QK.js"
     },
     "SemanticRecall": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js"
+      "implementation": "dist/chunk-TB6SV7QK.js"
     },
     "WorkingMemory": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js"
+      "implementation": "dist/chunk-TB6SV7QK.js"
     },
     "deepMergeWorkingMemory": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 21747
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 21748
     },
     "extractWorkingMemoryContent": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 22063
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 22064
     },
     "extractWorkingMemoryTags": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 22031
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 22032
     },
     "removeWorkingMemoryTags": {
       "types": "dist/index.d.ts",
-      "implementation": "dist/chunk-2NSPHF6Q.js",
-      "line": 22044
+      "implementation": "dist/chunk-TB6SV7QK.js",
+      "line": 22045
     },
     "WORKING_MEMORY_STATE_ID": {
       "types": "dist/index.d.ts",
@@ -197,7 +197,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-2NSPHF6Q.js",
+        "chunk-TB6SV7QK.js",
         "chunk-LSJJAJAF.js"
       ]
     }

package/dist/docs/references/docs-agents-agent-approval.md

@@ -49,6 +49,8 @@ for await (const chunk of stream.fullStream) {
 ```
 
 > **Note:** Agent approval uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/memory/storage) on your Mastra instance or you'll see a "snapshot not found" error.
+>
+> Snapshots for agent runs are minimal resume artifacts: they hold only what's needed to resume the suspended run and are deleted once the run finishes. Use [tracing](https://mastra.ai/docs/observability/overview) for the execution record and [memory](https://mastra.ai/docs/memory/overview) for the conversation history.
 
 ## How approval works
 
@@ -108,6 +110,29 @@ A tool can also pause _during_ its `execute` function by calling `suspend()`. Th
 
 The stream emits a `tool-call-suspended` chunk with a custom payload defined by the tool's `suspendSchema`. You resume by calling `resumeStream()` with data matching the tool's `resumeSchema`.
 
+```typescript
+const weatherTool = createTool({
+  id: 'get-weather',
+  inputSchema: z.object({
+    location: z.string().optional(),
+  }),
+  suspendSchema: z.object({
+    question: z.string(),
+  }),
+  resumeSchema: z.object({
+    location: z.string(),
+  }),
+  execute: async ({ location }, context) => {
+    if (!location) {
+      return await context?.agent?.suspend({
+        question: 'Which city would you like the weather for?',
+      })
+    }
+    return await fetchWeather(location)
+  },
+})
+```
+
 > **Note:** `suspend()` doesn't throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
 
 ## Tool approval with `generate()`

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

@@ -374,7 +374,7 @@ Success criteria:
 
 ## Running subagents in the background
 
-Subagent invocations are dispatched as tool calls, so they can run as [background tasks](https://mastra.ai/docs/agents/background-tasks). This is useful when one or more delegations are long-running and you don't want them to block the supervisor's response.
+Subagent invocations are dispatched as tool calls, so they can run as [background tasks](https://mastra.ai/docs/long-running-agents/background-tasks). This is useful when one or more delegations are long-running and you don't want them to block the supervisor's response.
 
 Enable the [backgroundTasks manager](https://mastra.ai/reference/configuration) on the Mastra instance, then opt subagents in on the supervisor:
 
@@ -399,7 +399,7 @@ const stream = await supervisor.streamUntilIdle('Research AI in education and wr
 
 Use [`streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle) instead of `stream()` so the stream stays open until the subagents complete and the supervisor has had a chance to respond to their results.
 
-If a subagent isn't listed on the supervisor but has its own background-eligible tools, the supervisor still dispatches the subagent as a background task and inherits its config. See [Inheriting from the subagent](https://mastra.ai/docs/agents/background-tasks) for details.
+If a subagent isn't listed on the supervisor but has its own background-eligible tools, the supervisor still dispatches the subagent as a background task and inherits its config. See [Inheriting from the subagent](https://mastra.ai/docs/long-running-agents/background-tasks) for details.
 
 ## Subagent versioning
 
@@ -420,7 +420,7 @@ Version overrides propagate automatically through delegation. See [Subagent vers
 
 ## Related
 
-- [Background tasks](https://mastra.ai/docs/agents/background-tasks)
+- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
 - [Subagent versioning](https://mastra.ai/docs/editor/overview)
 - [Guide: Research coordinator](https://mastra.ai/guides/guide/research-coordinator)
 - [Agent.stream() reference](https://mastra.ai/reference/streaming/agents/stream)

package/dist/docs/references/{docs-agents-background-tasks.md → docs-long-running-agents-background-tasks.md}

@@ -121,7 +121,7 @@ If the agent has `backgroundTasks.disabled: true`, every tool call runs synchron
 
 ## Background tasks related stream chunks
 
-When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/agents/background-tasks) SSE stream. Each stream covers a different set of chunk types:
+When a tool call dispatches as a background task, two streams may surface lifecycle events for it: the agent's own stream and the [`backgroundTaskManager.stream()`](https://mastra.ai/docs/long-running-agents/background-tasks) SSE stream. Each stream covers a different set of chunk types:
 
 | Chunk type                  | When it fires                                                                          | Emitted by     |
 | --------------------------- | -------------------------------------------------------------------------------------- | -------------- |
@@ -376,7 +376,7 @@ These read from storage rather than the pubsub stream, so they're suitable for p
 
 - [`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)
+- [Durable agents](https://mastra.ai/docs/long-running-agents/durable-agents)
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)
 - [Storage](https://mastra.ai/docs/memory/storage)

package/dist/docs/references/{docs-agents-goals.md → docs-long-running-agents-goals.md}

@@ -110,5 +110,5 @@ Per-objective values written by `setObjective` / `updateObjectiveOptions` take p
 ## Related
 
 - [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) — `isTaskComplete` and the rubric scorer
-- [Signal providers](https://mastra.ai/docs/agents/signal-providers) — how the objective is projected into context
+- [Signal providers](https://mastra.ai/docs/long-running-agents/signal-providers) — how the objective is projected into context
 - [Memory storage](https://mastra.ai/docs/memory/storage) — the storage backend goals require

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

@@ -399,7 +399,7 @@ const response = await agent.generate('What do you know about me?', {
 
 ## Opt in to state signals (experimental)
 
-By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/agents/signals) instead by setting `useStateSignals: true`:
+By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/long-running-agents/signals) instead by setting `useStateSignals: true`:
 
 ```typescript
 const memory = new Memory({

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

@@ -6,7 +6,16 @@ The `.cloneThread()` method creates a copy of an existing conversation thread, i
 
 ## Usage example
 
+The following example creates a `Memory` instance and clones an existing thread.
+
 ```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ id: 'memory-store', url: 'file:./memory.db' }),
+})
+
 const { thread, clonedMessages } = await memory.cloneThread({
   sourceThreadId: 'original-thread-123',
 })
@@ -20,7 +29,7 @@ const { thread, clonedMessages } = await memory.cloneThread({
 
 **resourceId** (`string`): Optional resource ID for the cloned thread. Defaults to the source thread's resourceId.
 
-**title** (`string`): Optional title for the cloned thread. Defaults to '\[source title] (Copy)'.
+**title** (`string`): Optional title for the cloned thread. If omitted, the clone uses Clone of ${sourceThread.title} when the source thread has a title. Otherwise, the title is empty.
 
 **metadata** (`Record<string, unknown>`): Optional metadata to merge with the source thread's metadata. Clone metadata is automatically added.
 
@@ -44,7 +53,7 @@ const { thread, clonedMessages } = await memory.cloneThread({
 
 **messageIdMap** (`Record<string, string>`): A mapping from source message IDs to their corresponding cloned message IDs.
 
-### Clone Metadata
+### Clone metadata
 
 The cloned thread's metadata includes a `clone` property with:
 
@@ -93,8 +102,18 @@ const { thread: dateFilteredClone } = await memory.cloneThread({
   },
 })
 
+// Clone specific messages
+const { thread: selectedMessagesClone } = await memory.cloneThread({
+  sourceThreadId: 'original-thread-123',
+  options: {
+    messageFilter: {
+      messageIds: ['message-1', 'message-2'],
+    },
+  },
+})
+
 // Continue conversation on the cloned thread
-const response = await agent.generate("Let's try a different approach", {
+const response = await agent.generate('Try a different approach', {
   memory: {
     thread: fullClone.id,
     resource: fullClone.resourceId,
@@ -102,9 +121,13 @@ const response = await agent.generate("Let's try a different approach", {
 })
 ```
 
+Pass the cloned `thread.id` and `thread.resourceId` to `agent.generate()` to continue the conversation from the cloned thread.
+
 ## Vector embeddings
 
-When the Memory instance has semantic recall enabled (with a vector store and embedder configured), `cloneThread()` automatically creates vector embeddings for all cloned messages. This ensures that semantic search works correctly on the cloned thread.
+When the Memory instance has semantic recall enabled with a vector store and embedder configured, `cloneThread()` automatically creates vector embeddings for all cloned messages. This ensures that semantic search works correctly on the cloned thread.
+
+In this example, `embeddingModel` is the embedding model configured for the project.
 
 ```typescript
 import { Memory } from '@mastra/memory'
@@ -131,6 +154,14 @@ const results = await memory.recall({
 })
 ```
 
+## Working memory
+
+When working memory is enabled, `cloneThread()` copies or shares working memory based on the working-memory scope and the clone's `resourceId`:
+
+- **Thread-scoped working memory**: The working memory is copied to the cloned thread.
+- **Resource-scoped working memory with the same `resourceId`**: The working memory is shared because the source and cloned threads belong to the same resource.
+- **Resource-scoped working memory with a different `resourceId`**: The working memory is copied to the cloned thread's resource.
+
 ## Observational Memory
 
 When [Observational Memory](https://mastra.ai/docs/memory/observational-memory) is enabled, `cloneThread()` automatically clones the OM records associated with the source thread. The behavior depends on the OM scope:

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

@@ -29,23 +29,23 @@ export const agent = new Agent({
 
 ## Constructor parameters
 
-**storage** (`MastraCompositeStore`): Storage implementation for persisting memory data. Defaults to \`new DefaultStorage({ config: { url: "file:memory.db" } })\` if not provided.
+**storage** (`MastraCompositeStore`): Storage implementation for persisting memory data. Defaults to new DefaultStorage({ config: { url: "file:memory.db" } }) if not provided.
 
-**vector** (`MastraVector | false`): Vector store for semantic search capabilities. Set to \`false\` to disable vector operations.
+**vector** (`MastraVector | false`): Vector store for semantic search capabilities. Set to false to disable vector operations.
 
 **embedder** (`EmbeddingModel<string> | EmbeddingModelV2<string>`): Embedder instance for vector embeddings. Required when semantic recall is enabled.
 
 **options** (`MemoryConfig`): Memory configuration options.
 
-**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to \`false\` to disable loading conversation history into context. Use \`Number.MAX\_SAFE\_INTEGER\` to retrieve all messages with no limit. To prevent saving new messages, use the \`readOnly\` option instead.
+**options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable loading conversation history into context. Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To prevent saving new messages, use the readOnly option instead.
 
 **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.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.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]\(/reference/memory/observational-memory) for configuration details.
+**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 user's first message. Can be a boolean or an object with custom model and instructions.