@mastra/memory 1.24.0-alpha.0 → 1.25.0-alpha.0

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

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/memory@1.1.0`
 
-Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Two background agents — an **Observer** and a **Reflector** — watch your agent's conversations and maintain a dense observation log that replaces raw message history as it grows.
+Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Background agents, an **Observer** and a **Reflector**, watch your agent's conversations and maintain a dense observation log that replaces raw message history as it grows.
 
 ## Quickstart
 
@@ -94,11 +94,11 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
-> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mongodb`, and `@mastra/convex` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
+> **Note:** OM currently only supports `@mastra/pg`, `@mastra/libsql`, `@mastra/mysql`, `@mastra/mongodb`, and `@mastra/convex` storage adapters. It uses background agents for managing memory. When no model is set, the default model is `google/gemini-2.5-flash`.
 
 ## Temporal gap markers
 
-Temporal gap markers insert a short reminder before a new user message when enough time has passed since the previous message in the thread. They help the agent and the UI see that the conversation resumed after a meaningful pause.
+Temporal gap markers insert a short reminder before a new user message when enough time has passed since the previous message in the thread. They help the agent and the UI see that the conversation resumed after a useful pause.
 
 Temporal gap markers are off by default. Enable them with `temporalMarkers: true` in the `observationalMemory` config:
 
@@ -191,15 +191,15 @@ See [the API reference](https://mastra.ai/reference/memory/observational-memory)
 
 ## Benefits
 
-- **Prompt caching**: OM's context is stable and observations append over time rather than being dynamically retrieved each turn. This keeps the prompt prefix cacheable, which reduces costs.
+- **Prompt caching**: OM's context is stable and observations append over time rather than being retrieved at runtime each turn. This keeps the prompt prefix cacheable, which reduces costs.
 - **Compression**: Raw message history and tool results get compressed into a dense observation log. Smaller context means faster responses and longer coherent conversations.
 - **Zero context rot**: The agent sees relevant information instead of noisy tool calls and irrelevant tokens, so the agent stays on task over long sessions.
 
 ## How it works
 
-You don't remember every word of every conversation you've ever had. You observe what happened subconsciously, then your brain reflects — reorganizing, combining, and condensing into long-term memory. OM works the same way.
+You don't remember every word of every conversation you've ever had. You observe what happened subconsciously, then your brain reflects, reorganizing, combining, and condensing into long-term memory. OM works the same way.
 
-Every time an agent responds, it sees a context window containing its system prompt, recent message history, and any injected context. The context window is finite; even models with large token limits perform worse when the window is full. This causes two problems:
+Every time an agent responds, it sees a context window containing its system prompt, recent message history, and any injected context. The context window is finite. Even models with large token limits perform worse when the window is full. This causes two problems:
 
 - **Context rot**: the more raw message history an agent carries, the worse it performs.
 - **Context waste**: most of that history contains tokens no longer needed to keep the agent on task.
@@ -274,7 +274,7 @@ new Extractor({
 })
 ```
 
-Use dynamic `instructions` or `schema` functions when an extractor needs runtime context, such as the active memory instance or request context:
+Use runtime `instructions` or `schema` functions when an extractor needs runtime context, such as the active memory instance or request context:
 
 ```typescript
 new Extractor({
@@ -378,7 +378,7 @@ new Agent({
 })
 ```
 
-You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle.
+You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle. Alternatively, set `observeAttachments: 'auto'` to let Mastra decide from the provider capabilities registry: attachments are forwarded when the Observer model supports multimodal input and dropped otherwise, falling back to `true` when no capability data is available for the model.
 
 ```md
 Date: 2026-01-15
@@ -389,7 +389,7 @@ Date: 2026-01-15
   - 🔴 12:15 User stated the app name is "Acme Dashboard"
 ```
 
-The compression is typically 5–40×. The Observer also tracks a **current task** and **suggested response** so the agent picks up where it left off.
+The compression is typically between 5x and 40x. The Observer also tracks a **current task** and **suggested response** so the agent picks up where it left off.
 
 If you enable `observation.threadTitle`, the Observer can also suggest a short thread title when the conversation topic meaningfully changes. Thread title generation is opt-in and updates the thread metadata, so apps like Mastra Code can show the latest title in thread lists and status UI.
 
@@ -397,7 +397,9 @@ Example: An agent using Playwright MCP might see 50,000+ tokens per page snapsho
 
 ### Reflections
 
-When observations exceed their threshold (default: 40,000 tokens), the Reflector condenses them, combines related items, and reflects on patterns.
+When observations exceed their threshold (default: 40,000 tokens), the Reflector condenses them and combines related items, plus reflects on patterns.
+
+Reflections don't accumulate as a separate, ever-growing layer. Each reflection rewrites the entire observation log: the Reflector's output becomes the new log, and new observations append after it. When the log next hits the threshold, the Reflector re-processes everything — including earlier reflections — condensing older information more aggressively while keeping recent detail. Memory stays bounded around the reflection threshold no matter how long the conversation runs.
 
 The result is a three-tier system:
 
@@ -405,6 +407,21 @@ The result is a three-tier system:
 2. **Observations**: A log of what the Observer has seen
 3. **Reflections**: Condensed observations when memory becomes too long
 
+### Context over time
+
+With default settings, the context window doesn't grow unbounded. It oscillates through an observe-and-shrink cycle:
+
+![Chart of context tokens over the course of a conversation with Observational Memory enabled: message history repeatedly grows toward the 30,000 token observation threshold, then shrinks back to around 6,000 tokens as observations activate, while the observation log steps up with each cycle until it reaches the 40,000 token reflection threshold and the Reflector condenses it into reflections](/img/memory/om-context-over-time-light.svg)
+
+1. **0 → 30k tokens**: Message history grows normally. In the background, the Observer buffers observations every \~6k tokens (`bufferTokens: 0.2`).
+2. **30k reached**: Buffered observations activate instantly. Observed messages are removed from the context window and only \~6k tokens of recent history remain (`bufferActivation: 0.8` retains 20% of the threshold). The \~24k tokens of removed messages become roughly 1-5k tokens of observations at typical 5-40x compression.
+3. **Repeat**: History grows from \~6k back toward 30k and shrinks again. Each cycle appends to the observation log, which grows much more slowly than raw history.
+4. **Observations reach 40k**: The Reflector condenses the observation log — including any earlier reflections — into a new, smaller log.
+
+The result: in the normal buffered cycle, raw history oscillates between roughly 6k and 30k tokens and the observation log stays around 40k tokens, however long the conversation runs. These are activation thresholds rather than hard caps — if background buffering falls behind, history can grow past the threshold until `blockAfter` (default `1.2`) forces a synchronous observation at \~36k tokens (\~48k for reflection) as a safety ceiling.
+
+With [`shareTokenBudget`](https://mastra.ai/reference/memory/observational-memory) enabled, the two budgets pool together: while the observation log is small, message history can expand into the unused observation space (up to \~70k tokens with the defaults) before observation triggers, then shrinks back as observations accumulate.
+
 ### Retrieval mode
 
 Normal OM compresses messages into observations, which is great for staying on task, but the original wording is gone. Retrieval mode fixes this by keeping each observation group linked to the raw messages that produced it. When the agent needs exact wording, tool output, or chronology that the summary compressed away, it can call a `recall` tool to page through the source messages.
@@ -446,7 +463,7 @@ When vector search is configured, new observation groups are automatically index
 
 #### Restricting to the current thread
 
-By default, the recall tool scope is `'resource'` — the agent can list threads, browse other threads, and search across all conversations. Set `scope: 'thread'` to restrict the agent to only the current thread:
+By default, the recall tool scope is `'resource'`, the agent can list threads and browse other threads, plus search across all conversations. Set `scope: 'thread'` to restrict the agent to only the current thread:
 
 ```typescript
 const memory = new Memory({
@@ -481,7 +498,9 @@ See the [recall tool reference](https://mastra.ai/reference/memory/observational
 To see how it works in practice, open [Studio](https://mastra.ai/docs/studio/overview) and navigate to an agent with OM enabled. The **Memory** tab displays:
 
 - **Token progress bars**: Current token counts for messages and observations, showing how close each is to its threshold. Hover over the info icon to see the model and threshold for the Observer and Reflector.
-- **Active observations**: The current observation log, rendered inline. When previous observation or reflection records exist, expand "Previous observations" to browse them.
+
+- **Active observations**: The current observation log is shown inline. If earlier observation or reflection records exist, expand "Previous observations" to browse them.
+
 - **Background processing**: During a conversation, buffered observation chunks and reflection status appear as the agent processes in the background.
 
 The progress bars update live while the agent is observing or reflecting, showing elapsed time and a status badge.
@@ -490,7 +509,7 @@ The progress bars update live while the agent is observing or reflecting, showin
 
 The Observer and Reflector run in the background. Any model that works with Mastra's [model routing](https://mastra.ai/models) (`provider/model`) can be used. When no model is set, the default model is `google/gemini-2.5-flash`.
 
-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.
+Mastra recommends 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`, `deepseek/deepseek-v4-pro`, `deepseek/deepseek-v4-flash`, `xai/grok-4-1-fast`, `qwen3`, and `glm-4.7`.
 
@@ -508,7 +527,7 @@ See [model configuration](https://mastra.ai/reference/memory/observational-memor
 
 > **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).
+> 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
 
@@ -546,9 +565,9 @@ const memory = new Memory({
 })
 ```
 
-The `upTo` keys are inclusive upper bounds. OM computes the actual input token count for the Observer or Reflector call, resolves the matching tier directly, and uses that concrete model for the run.
+The `upTo` keys are inclusive upper bounds. OM computes the actual input token count for the Observer or Reflector call and resolves the matching tier directly, plus uses that concrete model for the run.
 
-If the input exceeds the largest configured threshold, an error is thrown — ensure your thresholds cover the full range of possible input sizes, or use a model with a sufficiently large context window at the highest tier.
+If the input exceeds the largest configured threshold, an error is thrown, ensure your thresholds cover the full range of possible input sizes, or use a model with a sufficiently large context window at the highest tier.
 
 ## Scopes
 
@@ -651,10 +670,10 @@ const filePart = {
 
 The `tokenEstimate` object follows the same shape the Token Counter uses internally for cached estimates:
 
-- `v` — cache schema version. Set to `0`. Caller-supplied entries are exempt from the framework's version check, so the value isn't read.
-- `source` — cache lineage marker. Must be `'client'`. This is what tells the Token Counter the entry is authoritative and should be honored verbatim instead of being recomputed or overwritten.
-- `key` — content fingerprint slot. Set to `'client'`. Framework entries use a content hash here so they invalidate when the payload changes; the `'client'` sentinel keeps caller estimates stable across writes.
-- `tokens` — the token count to use. Must be a finite non-negative number.
+- `v`: cache schema version. Set to `0`. Caller-supplied entries are exempt from the framework's version check, so the value isn't read.
+- `source`: cache lineage marker. Must be `'client'`. This is what tells the Token Counter the entry is authoritative and should be honored verbatim instead of being recomputed or overwritten.
+- `key`: content fingerprint slot. Set to `'client'`. Framework entries use a content hash here so they invalidate when the payload changes. The `'client'` sentinel keeps caller estimates stable across writes.
+- `tokens`: the token count to use. Must be a finite non-negative number.
 
 Additional notes:
 
@@ -662,7 +681,7 @@ Additional notes:
 
 ## Async buffering
 
-Without async buffering, the Observer runs synchronously when the message threshold is reached — the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.
+Without async buffering, the Observer runs synchronously when the message threshold is reached, the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.
 
 ### How it works
 
@@ -670,19 +689,19 @@ As the agent converses, message tokens accumulate. At regular intervals (`buffer
 
 When message tokens reach the `messageTokens` threshold, buffered chunks activate: their observations move into the active observation log, and the corresponding raw messages are removed from the context window. The agent never pauses.
 
-Buffered observations also include continuation hints — a suggested next response and the current task — so the main agent maintains conversational continuity after activation shrinks the context window.
+Buffered observations also include continuation hints, a suggested next response and the current task, so the main agent maintains conversational continuity after activation shrinks the context window.
 
 If the agent produces messages faster than the Observer can process them, a `blockAfter` safety threshold forces a synchronous observation as a last resort. Buffered activation still preserves a minimum remaining context (the smaller of \~1k tokens or the configured retention floor).
 
-Reflection works similarly — the Reflector runs in the background when observations reach a fraction of the reflection threshold.
+Reflection works similarly, the Reflector runs in the background when observations reach a fraction of the reflection threshold.
 
 ### Settings
 
 | Setting                               | Default | What it controls                                                                                                                                                                                                                                                              |
 | ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                            |
+| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens`. With the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                             |
 | `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                         |
-| `observation.blockAfter`              | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                          |
+| `observation.blockAfter`              | `1.2`   | Safety net if buffering can't keep up. Values from 1 up to (but not including) 100 multiply `messageTokens`: at `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Values of 100 or more are absolute token counts (e.g. `50_000`).                          |
 | `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL. |
 | `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                          |
 | `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                          |
@@ -694,16 +713,16 @@ If you're relying on prompt caching, set `activateAfterIdle` to `"auto"` or to a
 
 With `"auto"`, Mastra chooses an idle activation TTL from the active model provider:
 
-| Provider                                                                                | Auto TTL  |
-| --------------------------------------------------------------------------------------- | --------- |
-| Anthropic, OpenRouter, unknown providers, xAI                                           | 5 minutes |
-| DeepSeek                                                                                | 1 hour    |
-| Google Gemini                                                                           | 24 hours  |
-| Groq                                                                                    | 2 hours   |
-| OpenAI with `providerOptions.openai.promptCacheRetention: "24h"`                        | 1 hour    |
-| OpenAI with `providerOptions.openai.promptCacheRetention: "in_memory"`                  | 5 minutes |
-| OpenAI `gpt-4*`, `gpt-5`, `gpt-5-*`, `gpt-5.1*`, `gpt-5.2*`, `gpt-5.3*`, and `gpt-5.4*` | 5 minutes |
-| Other OpenAI models                                                                     | 1 hour    |
+| Provider                                                                                               | Auto TTL  |
+| ------------------------------------------------------------------------------------------------------ | --------- |
+| Anthropic, OpenRouter, unknown providers, xAI                                                          | 5 minutes |
+| DeepSeek                                                                                               | 1 hour    |
+| Google Gemini                                                                                          | 24 hours  |
+| Groq                                                                                                   | 2 hours   |
+| OpenAI with `providerOptions.openai.promptCacheRetention: "24h"`                                       | 1 hour    |
+| OpenAI with `providerOptions.openai.promptCacheRetention: "in_memory"`                                 | 5 minutes |
+| OpenAI `gpt-4*`, `gpt-5`, `gpt-5-*`, and `gpt-5.1` through `gpt-5.4` (including `-` suffixed variants) | 5 minutes |
+| Other OpenAI models                                                                                    | 1 hour    |
 
 ```typescript
 const memory = new Memory({
@@ -761,7 +780,7 @@ const memory = new Memory({
 })
 ```
 
-- `previousObserverTokens: 2000` → default; keeps \~2k tokens of recent observations.
+- `previousObserverTokens: 2000` → default. Keeps \~2k tokens of recent observations.
 - `previousObserverTokens: 0` → omit previous observations completely.
 - `previousObserverTokens: false` → disable truncation and keep full previous observations.
 
@@ -770,7 +789,7 @@ const memory = new Memory({
 No manual migration needed. OM reads existing messages and observes them lazily when thresholds are exceeded.
 
 - **Thread scope**: The first time a thread exceeds `observation.messageTokens`, the Observer processes the backlog.
-- **Resource scope**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take significant time.
+- **Resource scope**: All unobserved messages across all threads for a resource are processed together. For users with many existing threads, this could take substantial time.
 
 ## Comparing OM with other memory features
 
@@ -779,7 +798,7 @@ No manual migration needed. OM reads existing messages and observes them lazily
 - **[Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)**: RAG-based retrieval of relevant past messages
 - **[Multi-user threads](https://mastra.ai/docs/memory/multi-user-threads)**: How OM attributes facts to individual users when several people share a single thread
 
-If you're using working memory to store conversation summaries or ongoing state that grows over time, OM is a better fit. Working memory is for small, structured data; OM is for long-running event logs. OM also manages message history automatically—the `messageTokens` setting controls how much raw history remains before observation runs.
+If you're using working memory to store conversation summaries or ongoing state that grows over time, OM is a better fit. Working memory is for small, structured data. OM is for long-running event logs. OM also manages message history automatically, the `messageTokens` setting controls how much raw history remains before observation runs.
 
 In practical terms, OM replaces both working memory and message history, and has greater accuracy (and lower cost) than Semantic Recall.
 

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

@@ -2,7 +2,7 @@
 
 # Memory
 
-Memory enables your agent to remember user messages, agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, and produce better answers over time.
+Memory enables your agent to remember user messages and agent replies, and tool results across interactions, giving it the context it needs to stay consistent, maintain conversation flow, plus produce better answers over time.
 
 Mastra agents can be configured to store [message history](https://mastra.ai/docs/memory/message-history). Additionally, you can enable:
 
@@ -19,7 +19,7 @@ Memory results will be stored in one or more of your configured [storage provide
 
 ## When to use memory
 
-Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges, recall user preferences or facts from earlier in a session, or build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.
+Use memory when your agent needs to maintain multi-turn conversations that reference prior exchanges or recall user preferences or facts from earlier in a session, or alternatively build context over time within a conversation thread. Skip memory for single-turn requests where each interaction is independent.
 
 ## Quickstart
 
@@ -172,6 +172,20 @@ export const memoryAgent = new Agent({
 
 See [Observational Memory](https://mastra.ai/docs/memory/observational-memory) for details on how observations and reflections work, and [the reference](https://mastra.ai/reference/memory/observational-memory) for all configuration options.
 
+## What the model sees
+
+Each memory feature lands in one of two places in the request sent to the model: the system messages or the conversation messages. Which layers are present depends on which features you've enabled — working memory, semantic recall, and Observational Memory only appear when configured, while message history is on by default. The diagram shows where each enabled layer is placed in the request; the list below describes what each layer contributes:
+
+![Diagram showing how Mastra assembles the model context: system messages containing agent instructions, call-time system messages, working memory, cross-thread semantic recall, and Observational Memory, followed by conversation messages where message history and same-thread semantic recall interleave by timestamp, then call-time context messages, and finally the new user message](/img/memory/memory-context-window-light.svg)
+
+- [Working memory](https://mastra.ai/docs/memory/working-memory) is injected as a system message containing the template and the stored data. With `useStateSignals`, it's delivered as a state signal instead.
+- [Semantic recall](https://mastra.ai/docs/memory/semantic-recall) matches from the current thread are inserted as regular messages and interleave with message history by timestamp. Matches from other threads are formatted into a system message instead.
+- [Message history](https://mastra.ai/docs/memory/message-history) adds the last N messages in chronological order. Your new message always comes last.
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory) replaces old raw history: reflections and observations live in a system message, and only messages that haven't been observed yet remain in the conversation. A short continuation reminder is placed at the start of the conversation messages.
+- Context messages are the optional `context` array passed on a call, for example `agent.generate(msg, { context: [...] })`. Use them for one-off background such as app state or your own RAG results. They appear as regular conversation messages for that request only and are never saved to memory.
+
+Conversation messages are ordered by timestamp and deduplicated by message ID, so recalled older messages appear before recent history. Context messages passed at call time are stamped with the current time, which places them after history and recall but before your new message. To inspect the exact context for a real request, use [Tracing](https://mastra.ai/docs/observability/tracing/overview) and open the LLM call spans, see [Observability](#observability) below.
+
 ## Memory in multi-agent systems
 
 When a [supervisor agent](https://mastra.ai/docs/agents/supervisor-agents) delegates to a subagent, Mastra isolates subagent memory automatically. No flag enables this as it happens on every delegation. Understanding how this scoping works lets you decide what stays private and what to share intentionally.
@@ -182,21 +196,21 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 
 - **Thread ID**: Unique per delegation. The subagent starts with a clean message history every time it's called.
 - **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
-- **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance, including all of its options. If the subagent defines its own, that takes precedence.
+- **Memory instance**: A subagent without its own memory inherits the supervisor's `Memory` instance and all configured options. If the subagent defines its own, that takes precedence.
 
 > **Note:** Title generation (`generateTitle`) is a top-level thread concern and **isn't** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
 
-The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
+The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved, the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
 
-> **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Two different subagents under the same supervisor never share a resource ID through delegation.
+> **Note:** Subagent resource IDs are always suffixed with the agent name (`{parentResourceId}-{agentName}`). Different subagents under the same supervisor never share a resource ID through delegation.
 
 To go beyond this default isolation, you can share memory between agents by passing matching identifiers when you call them directly.
 
 ### Share memory between agents
 
-When you call agents directly (outside the delegation flow), memory sharing is controlled by two identifiers: `resourceId` and `threadId`. Agents that use the same values read and write to the same data. This is useful when agents collaborate on a shared context — for example, a researcher that saves notes and a writer that reads them.
+When you call agents directly (outside the delegation flow), memory sharing is controlled by two identifiers: `resourceId` and `threadId`. Agents that use the same values read and write to the same data. This is useful when agents collaborate on a shared context, for example, a researcher that saves notes and a writer that reads them.
 
-**Resource-scoped sharing** is the most common pattern. [Working memory](https://mastra.ai/docs/memory/working-memory) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) default to `scope: 'resource'`. If two agents share a `resourceId`, they share observations, working memory, and embeddings — even across different threads:
+**Resource-scoped sharing** is the most common pattern. [Working memory](https://mastra.ai/docs/memory/working-memory) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) default to `scope: 'resource'`. If two agents share a `resourceId`, they share observations, working memory, and embeddings, even across different threads:
 
 ```typescript
 // Both agents share the same resource-scoped memory
@@ -209,15 +223,15 @@ await writer.generate('Write a summary from the research notes.', {
 })
 ```
 
-Because both calls use `resource: 'project-42'`, the writer can access the researcher's observations, working memory, and semantic embeddings. Each agent still has its own thread, so message histories stay separate.
+Because both calls use `resource: 'project-42'`, the writer can access the researcher's observations and working memory. Semantic embeddings are also shared through the resource. Each agent still has its own thread, so message histories stay separate.
 
-**Thread-scoped sharing** gives tighter coupling. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses `scope: 'thread'` by default. If two agents use the same `resource` _and_ `thread`, they share the full message history. Each agent sees every message the other has written. This is useful when agents need to build on each other's exact outputs.
+**Thread-scoped sharing** gives tighter coupling. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) uses `scope: 'thread'` by default. If two agents use the same `resource` and `thread`, they share the full message history. Each agent sees every message the other has written. This is useful when agents need to build on each other's exact outputs.
 
 ## Observability
 
 Enable [Tracing](https://mastra.ai/docs/observability/tracing/overview) to monitor and debug memory in action. Traces show you exactly which messages and observations the agent included in its context for each request, helping you understand agent behavior and verify that memory retrieval is working as expected.
 
-Open [Studio](https://mastra.ai/docs/studio/overview) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request, then look for spans of LLMs calls.
+Open [Studio](https://mastra.ai/docs/studio/overview) and select the **Observability** tab in the sidebar. Open the trace of a recent agent request and look for its LLM call spans.
 
 ## Switch memory per request
 

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -10,7 +10,7 @@ If you ask your friend what they did last weekend, they will search in their mem
 
 Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](https://mastra.ai/docs/memory/message-history).
 
-It uses vector embeddings of messages for similarity search, integrates with various vector stores, and has configurable context windows around retrieved messages.
+It uses vector embeddings of messages for similarity search and integrates with vector stores, plus has configurable context windows around retrieved messages.
 
 ![Diagram showing Mastra Memory semantic recall](/assets/images/semantic-recall-fd7b9336a6d0d18019216cb6d3dbe710.png)
 
@@ -34,7 +34,7 @@ const agent = new Agent({
   id: 'support-agent',
   name: 'SupportAgent',
   instructions: 'You are a helpful support agent.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'agent-storage',
@@ -64,7 +64,7 @@ const agent = new Agent({
   id: 'support-agent',
   name: 'SupportAgent',
   instructions: 'You are a helpful support agent.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     storage: new MongoDBStore({
       id: 'agent-storage',

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

@@ -4,7 +4,7 @@
 
 While [message history](https://mastra.ai/docs/memory/message-history) and [semantic recall](https://mastra.ai/docs/memory/semantic-recall) help agents remember conversations, working memory allows them to maintain persistent information about users across interactions.
 
-Think of it as the agent's active thoughts or scratchpad – the key information they keep available about the user or task. It's similar to how a person would naturally remember someone's name, preferences, or important details during a conversation.
+Working memory is the agent's active scratchpad: key information it keeps available about the user or task. It can retain a person's name, preferences, or other important details during a conversation.
 
 This is useful for maintaining ongoing state that's always relevant and should always be available to the agent.
 
@@ -17,7 +17,7 @@ Working memory can persist at two different scopes:
 - **Resource-scoped** (default): Memory persists across all conversation threads for the same user
 - **Thread-scoped**: Memory is isolated per conversation thread
 
-**Important:** Switching between scopes means the agent won't see memory from the other scope - thread-scoped memory is completely separate from resource-scoped memory.
+**Requirement:** Switching between scopes means the agent won't see memory from the other scope - thread-scoped memory is completely separate from resource-scoped memory.
 
 ## Quickstart
 
@@ -32,7 +32,7 @@ const agent = new Agent({
   id: 'personal-assistant',
   name: 'PersonalAssistant',
   instructions: 'You are a helpful personal assistant.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     options: {
       workingMemory: {
@@ -45,7 +45,7 @@ const agent = new Agent({
 
 ## How it works
 
-Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information.
+Working memory is a block of Markdown text that the agent can update over time to store continuously relevant information.
 
 ## Memory persistence scopes
 
@@ -134,7 +134,7 @@ Resource-scoped working memory requires specific storage adapters that support t
 
 ## Custom templates
 
-Templates guide the agent on what information to track and update in working memory. While a default template is used if none is provided, you'll typically want to define a custom template tailored to your agent's specific use case to ensure it remembers the most relevant information. For threads shared by multiple users, see [Multi-user threads](https://mastra.ai/docs/memory/multi-user-threads).
+Templates guide the agent on what information to track and update in working memory. Mastra uses a default template when you don't provide one. Define a custom template for your agent's use case so it remembers the most relevant information. For threads shared by multiple users, see [Multi-user threads](https://mastra.ai/docs/memory/multi-user-threads).
 
 Here's an example of a custom template. In this example the agent will store the users name, location, timezone, etc as soon as the user sends a message containing any of the info:
 
@@ -214,7 +214,7 @@ const paragraphMemory = new Memory({
 
 Working memory can also be defined using a structured schema instead of a Markdown template. This allows you to specify the exact fields and types that should be tracked, using a [Standard JSON Schema](https://standardschema.dev/json-schema) ([Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/), etc.). When using a schema, the agent will see and update working memory as a JSON object matching your schema.
 
-**Important:** You must specify either `template` or `schema`, but not both.
+**Requirement:** You must specify either `template` or `schema`, but not both.
 
 ### Example: Schema-Based Working Memory
 
@@ -271,8 +271,8 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 
 ## Choosing between template and schema
 
-- Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics** — the agent must provide the complete memory content on each update.
-- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON. The `workingMemory.schema` field accepts any `PublicSchema`-compatible schema (including Zod v3, Zod v4, JSON Schema, or already-standard schemas). Schemas use **merge semantics** — the agent only provides fields to update, and existing fields are preserved.
+- Use a **template** (Markdown) if you want the agent to maintain memory as a free-form text block, such as a user profile or scratchpad. Templates use **replace semantics**: the agent must provide the complete memory content on each update.
+- Use a **schema** if you need structured, type-safe data that can be validated and programmatically accessed as JSON. The `workingMemory.schema` field accepts any `PublicSchema`-compatible schema (including Zod v3, Zod v4, JSON Schema, or already-standard schemas). Schemas use **merge semantics**: the agent only provides fields to update, and existing fields are preserved.
 - Only one mode can be active at a time: setting both `template` and `schema` isn't supported.
 
 ## Example: Multi-step retention

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

@@ -14,7 +14,7 @@ Storage powers:
 
 ## When to configure storage
 
-Configure a persistent storage adapter when state must survive restarts, be shared across processes, or be visible in Studio across sessions. The default in-memory store is useful for tests and short local experiments, but it loses data when the process exits.
+Configure a persistent storage adapter when state must survive restarts or be shared across processes. Persistent storage also keeps state visible in Studio across sessions. The default in-memory store is useful for tests and short local experiments, but it loses data when the process exits.
 
 Use storage when your application needs any of these behaviors:
 
@@ -144,7 +144,7 @@ export const supportAgent = new Agent({
   id: 'support-agent',
   name: 'Support agent',
   instructions: 'Answer customer support questions.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     storage: new PostgresStore({
       id: 'support-agent-storage',

package/dist/docs/references/reference-memory-clone-utilities.md

@@ -2,7 +2,7 @@
 
 # Cloned thread utilities
 
-The Memory class provides utility methods for working with cloned threads. These methods help you check clone status, retrieve clone metadata, navigate clone relationships, and track clone history.
+The Memory class provides utility methods for working with cloned threads. These methods help you check clone status, retrieve clone metadata, traverse clone relationships, and track clone history.
 
 ## `isClone()`
 

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

@@ -2,7 +2,7 @@
 
 # Memory.cloneThread()
 
-The `.cloneThread()` method creates a copy of an existing conversation thread, including all its messages. This enables creating divergent conversation paths from a specific point in a conversation. When semantic recall is enabled, the method also creates vector embeddings for the cloned messages.
+The `.cloneThread()` method creates a copy of an existing conversation thread, including all its messages. It supports creating divergent conversation paths from a specific point in a conversation. When semantic recall is enabled, the method also creates vector embeddings for the cloned messages.
 
 ## Usage example
 
@@ -125,7 +125,7 @@ Pass the cloned `thread.id` and `thread.resourceId` to `agent.generate()` to con
 
 ## 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. It ensures that semantic search works correctly on the cloned thread.
 
 In this example, `embeddingModel` is the embedding model configured for the project.
 
@@ -170,4 +170,4 @@ When [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
 - **Resource-scoped OM (same `resourceId`)**: The OM record is shared between the source and cloned threads since they belong to the same resource. No duplication occurs.
 - **Resource-scoped OM (different `resourceId`)**: The OM record is cloned to the new resource. Message IDs are remapped and any thread-identifying tags within observations are updated to reference the cloned thread.
 
-Only the current (most recent) OM generation is cloned — older history generations aren't copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.
+Only the current (most recent) OM generation is cloned. Older history generations aren't copied. Transient processing state (observation/reflection in-progress flags) is reset on the cloned record.

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

@@ -19,7 +19,7 @@ const result = await memory.listThreads({
 
 Use `perPage: false` to retrieve all matching threads at once.
 
-> **Warning:** Generally speaking it's recommended to use pagination, especially for large datasets. Use this option cautiously.
+> **Warning:** Use pagination, especially for large datasets. Use this option cautiously.
 
 ```typescript
 const result = await memory.listThreads({

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

@@ -2,7 +2,7 @@
 
 # Memory class
 
-The `Memory` class provides a robust system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
+The `Memory` class provides a reliable system for managing conversation history and thread-based message storage in Mastra. It enables persistent storage of conversations, semantic search capabilities, and efficient message retrieval. You must configure a storage provider for conversation history, and if you enable semantic recall you will also need to provide a vector store and embedder.
 
 ## Usage example
 
@@ -14,7 +14,7 @@ export const agent = new Agent({
   id: 'test-agent',
   name: 'test-agent',
   instructions: 'You are an agent with memory.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     options: {
       workingMemory: {
@@ -63,7 +63,7 @@ import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
 export const agent = new Agent({
   name: 'test-agent',
   instructions: 'You are an agent with memory.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'test-agent-storage',
@@ -100,7 +100,7 @@ import { PgStore, PgVector } from '@mastra/pg'
 export const agent = new Agent({
   name: 'pg-agent',
   instructions: 'You are an agent with optimized PostgreSQL memory.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     storage: new PgStore({
       id: 'pg-agent-storage',