@mastra/mcp-docs-server 1.1.35-alpha.2 → 1.1.35-alpha.21

package/.docs/course/03-agent-memory/18-advanced-configuration-semantic-recall.md

@@ -1,6 +1,6 @@
-# Advanced Configuration of Semantic Recall
+# Advanced configuration of semantic recall
 
-We can configure semantic recall in more detail by setting options for the `semanticRecall` option:
+Configure semantic recall with the `semanticRecall` option:
 
 ```typescript
 const memory = new Memory({
@@ -19,11 +19,55 @@ const memory = new Memory({
         before: 2,
         after: 1,
       },
+      scope: 'resource', // Search all threads for this resource
+      filter: { projectId: { $eq: 'project-a' } },
     },
   },
 })
 ```
 
-The `topK` parameter controls how many semantically similar messages are retrieved. A higher value will retrieve more messages, which can be helpful for complex topics but may also include less relevant information. The default value is `4`.
+The `topK` parameter controls how many similar messages Mastra retrieves. A higher value retrieves more messages, which can help with complex topics but may include less relevant information. The default value is `4`.
 
-The `messageRange` parameter controls how much context is included with each match. This is important because the matching message alone might not provide enough context to understand the conversation. Including messages before and after the match helps the agent understand the context of the matched message.
+The `messageRange` parameter controls how much context Mastra includes with each match. Messages before and after the match help the agent understand the matched message.
+
+The `scope` parameter controls whether Mastra searches the current thread (`'thread'`) or all threads owned by a resource (`'resource'`). Use `scope: 'resource'` to let the agent recall information from past conversations for the same resource.
+
+The `filter` parameter restricts semantic recall results to messages with matching thread metadata, such as a project ID or category.
+
+Filters match metadata stored on message embeddings when messages are saved. If thread metadata changes later, existing embeddings keep their previous metadata until those messages are saved or indexed again.
+
+Supported filter operators:
+
+- `$and`: Logical AND
+- `$eq`: Equal to
+- `$gt`: Greater than
+- `$gte`: Greater than or equal
+- `$in`: In array
+- `$lt`: Less than
+- `$lte`: Less than or equal
+- `$ne`: Not equal to
+- `$nin`: Not in array
+- `$or`: Logical OR
+
+The following example demonstrates metadata filters for common use cases:
+
+```typescript
+// Filter by project
+const options = {
+  semanticRecall: { filter: { projectId: { $eq: 'my-project' } } },
+}
+
+// Filter by multiple categories
+const options = {
+  semanticRecall: { filter: { category: { $in: ['work', 'research'] } } },
+}
+
+// Filter by project and priority
+const options = {
+  semanticRecall: {
+    filter: {
+      $and: [{ projectId: { $eq: 'project-a' } }, { priority: { $gte: 3 } }],
+    },
+  },
+}
+```

package/.docs/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/.docs/docs/agents/processors.md

@@ -211,6 +211,22 @@ The method receives the current `stepNumber`, `model`, `tools`, `toolChoice`, `m
 
 See the [`Processor` reference](https://mastra.ai/reference/processors/processor-interface) for all available arguments and return types.
 
+### Rewrite the LLM request before the provider call
+
+Use `processLLMRequest()` when you need to rewrite the final prompt that Mastra sends to the model. This hook runs after Mastra converts the `MessageList` into the provider-facing prompt format (`LanguageModelV2Prompt`) and immediately before the provider call.
+
+Use the message-based hooks for conversation changes:
+
+- `processInput()`: Change the conversation once before the agentic loop starts.
+- `processInputStep()`: Change messages or step configuration before each LLM call.
+- `processLLMRequest()`: Change only the outbound prompt for the current provider call.
+
+Changes returned from `processLLMRequest()` are transient. They don't persist back to `MessageList`, memory, UI history, or future provider calls. This makes the hook a good fit for provider compatibility rewrites, role/content normalization, or other model-specific prompt changes that shouldn't alter stored conversation history.
+
+The method receives `prompt`, `model`, `stepNumber`, `steps`, `state`, and the shared processor context. Calling `abort()` from `processLLMRequest()` emits the normal tripwire response and stops the call.
+
+See the [`Processor` reference](https://mastra.ai/reference/processors/processor-interface) for all available arguments and return types.
+
 ### Use the `prepareStep()` callback
 
 The `prepareStep()` callback on `generate()` or `stream()` is a shorthand for `processInputStep()`. Internally, Mastra wraps it in a processor that calls your function at each step. It accepts the same arguments and return type as `processInputStep()`, but doesn't require creating a class:
@@ -317,7 +333,7 @@ For more on retry behavior, see [Retry mechanism](#retry-mechanism) in Advanced
 
 ### Persist data across chunks and steps
 
-Output methods receive a `state` object that persists for the lifetime of one request. State is keyed by the processor's `id`, so each processor sees only its own data, and it is shared between `processOutputStream`, `processOutputStep`, and `processOutputResult`. A new state object is created for every new `agent.generate()` or `agent.stream()` call.
+Output methods receive a `state` object that persists for the lifetime of one request. State is keyed by the processor's `id`, so each processor sees only its own data, and it's shared between `processOutputStream`, `processOutputStep`, and `processOutputResult`. A new state object is created for every new `agent.generate()` or `agent.stream()` call.
 
 ```typescript
 import type { Processor } from '@mastra/core/processors'
@@ -375,6 +391,14 @@ new ToolCallFilter({
 })
 ```
 
+Set `preserveModelOutput: true` to keep compact `toModelOutput` history for filtered completed tool results. The filter keeps only the model-facing output and removes raw tool args and raw results.
+
+```typescript
+new ToolCallFilter({
+  preserveModelOutput: true,
+})
+```
+
 See the [`ToolCallFilter` reference](https://mastra.ai/reference/processors/tool-call-filter) for configuration options and the [Memory Processors](https://mastra.ai/docs/memory/memory-processors) page for pre-memory filtering.
 
 ### `ToolSearchProcessor`
@@ -383,6 +407,14 @@ Enables dynamic tool discovery for agents with large tool libraries. Instead of
 
 See the [`ToolSearchProcessor` reference](https://mastra.ai/reference/processors/tool-search-processor) for configuration options and usage examples.
 
+### `ProviderHistoryCompat`
+
+Handles provider-specific history incompatibilities when agents reuse messages across model providers. It can rewrite the outbound LLM request before the provider call, or recover from known provider API errors and retry.
+
+Add `ProviderHistoryCompat` explicitly when you need provider history compatibility rules, reactive API error recovery, custom compatibility rules, or predictable processor ordering.
+
+See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processors/provider-history-compat) for setup, built-in rules, and custom rule options.
+
 ## Advanced patterns
 
 ### Ensure a final response with `maxSteps`
@@ -494,7 +526,7 @@ for await (const chunk of stream.fullStream) {
 
 Custom chunk types must use the `data-` prefix (e.g., `data-moderation-update`, `data-status`).
 
-By default, `processOutputStream()` skips `data-*` chunks so it does not accidentally operate on tool telemetry or other processors' output. To inspect, modify, or block these chunks in a processor, set `processDataParts = true` on that processor:
+By default, `processOutputStream()` skips `data-*` chunks so it doesn't accidentally operate on tool telemetry or other processors' output. To inspect, modify, or block these chunks in a processor, set `processDataParts = true` on that processor:
 
 ```typescript
 class ModerationCollector implements Processor {

package/.docs/docs/agents/response-caching.md

@@ -0,0 +1,148 @@
+# Response caching
+
+Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to drop latency to single-digit milliseconds and avoid paying for repeated calls.
+
+Caching is implemented as the [`ResponseCache`](https://mastra.ai/reference/processors/response-cache) input processor. There is no agent-level option — to enable caching, register the processor explicitly. This keeps the API surface small while we collect feedback; per-call overrides flow through `RequestContext`.
+
+## When to use response caching
+
+Reach for it when the same request shape repeats across users or sessions, for example prompt templates, suggested-prompt buttons, agentic search re-asks, or guardrail LLMs that classify the same input over and over. Skip it when calls trigger external side effects through tools, since cache hits replay tool calls without re-executing them.
+
+## Quickstart
+
+Add a `ResponseCache` to the agent's `inputProcessors` and pass any `MastraServerCache` as the backend. For development, `InMemoryServerCache` works out of the box:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { InMemoryServerCache } from '@mastra/core/cache'
+import { ResponseCache } from '@mastra/core/processors'
+
+const cache = new InMemoryServerCache()
+
+export const searchAgent = new Agent({
+  name: 'Search Agent',
+  instructions: 'You answer questions concisely.',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache, ttl: 600 })], // 10 minutes
+})
+```
+
+The first call runs the LLM normally and writes the response to the cache. Subsequent calls with an identical resolved prompt return the cached response without invoking the LLM.
+
+## Per-call overrides via RequestContext
+
+Per-call config flows through `RequestContext`. Use `ResponseCache.context()` to build a fresh context, or `ResponseCache.applyContext()` to merge into one you already have:
+
+```typescript
+import { ResponseCache } from '@mastra/core/processors'
+import { RequestContext } from '@mastra/core/request-context'
+
+// Fresh context with the override
+await agent.stream('hello', {
+  requestContext: ResponseCache.context({ key: 'custom-key', bust: true }),
+})
+
+// Or merge into an existing context
+const ctx = new RequestContext()
+ctx.set('caller-meta', { userId: 'u-123' })
+ResponseCache.applyContext(ctx, { bust: true })
+await agent.stream('hello', { requestContext: ctx })
+```
+
+Three fields are overridable per call:
+
+- `key` — string or function. Overrides the auto-derived cache key for this request only.
+- `scope` — string or `null`. Overrides the tenant/user scope for this request only. `null` opts out of scoping.
+- `bust` — boolean. Skips the cache read but still writes on completion (useful for "force refresh" buttons).
+
+`cache`, `ttl`, and `agentId` stay on the constructor — they are instance-level concerns and not safe to vary per call.
+
+## Tenant scoping
+
+By default, `ResponseCache` looks up `MASTRA_RESOURCE_ID_KEY` on the request context and uses it as the cache scope. This means an agent that already populates the resource id (e.g. via memory) gets per-user isolation automatically — two users never see each other's cached responses.
+
+Override explicitly when you need a different scope:
+
+```typescript
+new Agent({
+  // ...
+  inputProcessors: [
+    new ResponseCache({
+      cache,
+      scope: 'org-123', // explicit tenant scope
+    }),
+  ],
+})
+```
+
+Pass `scope: null` to deliberately share entries across all callers — only use this for known-public, non-personalized content.
+
+## Custom cache backend
+
+`ResponseCache` accepts any `MastraServerCache`. For production, use `RedisCache` from `@mastra/redis`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ResponseCache } from '@mastra/core/processors'
+import { RedisCache } from '@mastra/redis'
+
+const cache = new RedisCache({ url: process.env.REDIS_URL })
+
+export const agent = new Agent({
+  name: 'Cached Agent',
+  instructions: '...',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache })],
+})
+```
+
+For a custom backend, extend `MastraServerCache` and implement its abstract methods (the processor only calls `get` and `set`).
+
+## How caching is implemented
+
+`ResponseCache` hooks into `processLLMRequest` (cache lookup, short-circuits on hit) and `processLLMResponse` (cache write on completion). Both run inside the agentic loop _after_ memory has loaded and earlier input processors have transformed the prompt.
+
+This means the cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have run — and each step in an agentic tool loop is independently cached.
+
+## What's in the cache key
+
+When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
+
+### Customize the cache key
+
+Pass `key` as a function on the constructor or per-call to derive your own cache key from any subset of those inputs. The function receives the same inputs the deterministic hash would have consumed and returns a string (or a `Promise<string>`):
+
+```typescript
+import { ResponseCache, buildResponseCacheKey } from '@mastra/core/processors'
+
+await agent.stream(input, {
+  requestContext: ResponseCache.context({
+    // Cache only on the model id and the resolved prompt tail — ignore
+    // step number, scope, etc.
+    key: ({ model, prompt }) => `qa:${model.modelId}:${JSON.stringify(prompt).slice(-200)}`,
+  }),
+})
+
+// Or reuse the deterministic helper while overriding individual fields:
+await agent.stream(input, {
+  requestContext: ResponseCache.context({
+    key: inputs => buildResponseCacheKey({ ...inputs, scope: 'global' }),
+  }),
+})
+```
+
+If the function throws, the processor falls back to the default key derivation so the call still benefits from caching.
+
+## How cache hits work
+
+When the processor finds a cache hit, it short-circuits the LLM call by returning the cached chunks from `processLLMRequest`. The agentic loop synthesizes a stream from those chunks instead of calling the model. `agent.generate()` collects them into a `FullOutput`; `agent.stream()` returns a `MastraModelOutput` whose chunks come from the cached buffer, so consumers iterating `fullStream` or awaiting `text`, `usage`, and `finishReason` see the cached values.
+
+Cache writes happen after the response completes. Failed runs (errors, tripwire activations) are not cached, so the next call retries cleanly.
+
+## Related
+
+- [`ResponseCache` reference](https://mastra.ai/reference/processors/response-cache)
+- [Processors](https://mastra.ai/docs/agents/processors)
+- [Guardrails](https://mastra.ai/docs/agents/guardrails)
+- [Agent.stream()](https://mastra.ai/reference/streaming/agents/stream)
+- [Agent.generate()](https://mastra.ai/reference/agents/generate)

package/.docs/docs/agents/using-tools.md

@@ -224,6 +224,14 @@ export const weatherTool = createTool({
 })
 ```
 
+## Transform tool payloads for UI and transcripts
+
+Use `transform` when a tool returns raw data your application needs, but browser-facing streams or user-visible transcript messages should receive a smaller or safer shape. `transform` is separate from `toModelOutput`: `toModelOutput` shapes the payload sent back to the model, while `transform` shapes tool input, output, errors, approval payloads, and suspension payloads for `display` and `transcript` targets.
+
+If a transform is configured and it fails, Mastra does not fall back to the raw payload for display or transcript targets. Input deltas are suppressed when no safe `inputDelta` transform is available.
+
+See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for a `transform` example. For shared rules across several tools, configure the agent-level `transform` policy in the [`Agent` constructor](https://mastra.ai/reference/agents/agent).
+
 ## Control tool selection
 
 Pass `toolChoice` or `activeTools` to `.generate()` or `.stream()` to control which tools the agent uses at runtime.

package/.docs/docs/editor/tools.md

@@ -73,7 +73,7 @@ Integration providers connect external tool platforms to the editor. Once regist
    })
    ```
 
-   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. Tool calls are scoped to a `userId` passed through request context for per-user authentication.
+   Composio tool slugs use a format like `GITHUB_CREATE_ISSUE`. Tool calls are scoped to the `resourceId` passed through request context for per-user authentication.
 
 ### Arcade
 

package/.docs/docs/index.md

@@ -126,8 +126,8 @@ Templates: [Customer Feedback Summarization](https://mastra.ai/templates/custome
 
 Browse [templates](https://mastra.ai/templates) for working examples.
 
-## Not ready to build yet?
+## Want to learn more?
 
-Watch this quick introduction:
+Here's a quick introduction:
 
 [YouTube video player](https://www.youtube-nocookie.com/embed/1qnmnRICX50)

package/.docs/docs/mastra-platform/configuration.md

@@ -55,4 +55,4 @@ MASTRA_PROJECT_ID="<staging-id>" mastra studio deploy --env-file .env.staging --
 MASTRA_PROJECT_ID="<production-id>" mastra studio deploy --env-file .env.production --yes
 ```
 
-Each project has its own Studio URL and its own observability data. When using [`CloudExporter`](https://mastra.ai/docs/observability/tracing/exporters/cloud), set `MASTRA_PROJECT_ID` and `MASTRA_CLOUD_ACCESS_TOKEN` per environment so traces route to the matching Studio project.
+Each project has its own Studio URL and its own observability data. When using [`MastraPlatformExporter`](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform), set `MASTRA_PROJECT_ID` and `MASTRA_CLOUD_ACCESS_TOKEN` per environment so traces route to the matching Studio project.

package/.docs/docs/mastra-platform/overview.md

@@ -75,4 +75,4 @@ Once you're ready to deploy your application to production, use [`mastra studio
 
 Follow the [Studio deployment guide](https://mastra.ai/docs/studio/deployment) and [Server deployment guide](https://mastra.ai/guides/deployment/mastra-platform) for step-by-step instructions.
 
-If you host your Mastra application on your own infrastructure, you can still send observability data to Studio using the [CloudExporter](https://mastra.ai/docs/observability/tracing/exporters/cloud).
+If you host your Mastra application on your own infrastructure, you can still send observability data to Studio using the [MastraPlatformExporter](https://mastra.ai/docs/observability/tracing/exporters/mastra-platform).

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

@@ -77,6 +77,48 @@ The observer also sees these markers when it processes the thread, so the observ
 
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
+## Early activation
+
+OM can activate buffered observations before the token threshold is reached. This is useful when a prompt cache is likely to expire, or when the agent changes model providers.
+
+Top-level early activation settings apply to observations by default:
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      activateOnProviderChange: true,
+    },
+  },
+})
+```
+
+Use nested `observation` and `reflection` settings for per-phase control. Reflection early activation is opt-in, so top-level settings affect only observations.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      activateAfterIdle: '5m',
+      observation: {
+        activateAfterIdle: false,
+      },
+      reflection: {
+        activateAfterIdle: '10m',
+        activateOnProviderChange: true,
+      },
+    },
+  },
+})
+```
+
+In this example, the top-level idle setting is disabled for observations, while reflections opt into idle and provider-change activation.
+
+See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
+
 ## 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.
@@ -216,7 +258,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 +272,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`
@@ -364,17 +410,19 @@ Reflection works similarly — the Reflector runs in the background when observa
 
 ### 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.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.                                                                                                                                                                   |
-| `activateAfterIdle`            | none    | Forces buffered observations and buffered reflections to activate after a period of inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like `300_000`, `"5m"`, or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
-| `activateOnProviderChange`     | `false` | Forces buffered observations and reflections 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.                                                                                                                                                                                                   |
-| `reflection.blockAfter`        | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                            |
+| 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.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.                                                                                                                                                          |
+| `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`, or duration strings like `"5m"` or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
+| `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.                                                                                                                                                                                          |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                      |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                    |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                   |
 
-If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations or reflections first and send a smaller compressed context window.
+If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
 
 ```typescript
 const memory = new Memory({
@@ -388,9 +436,9 @@ const memory = new Memory({
 })
 ```
 
-With a 5-minute prompt cache TTL, this activates buffered context after 5 minutes of inactivity so the next uncached prompt uses observations and reflections instead of a larger raw message window. If you prefer, `300_000` works the same way.
+With a 5-minute prompt cache TTL, this activates buffered observations after 5 minutes of inactivity so the next uncached prompt uses compressed observations instead of a larger raw message window. If you prefer, `300_000` works the same way.
 
-Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered context to activate before the new provider runs. That avoids sending a large raw window to a provider that cannot reuse the previous prompt cache.
+Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered observations to activate before the new provider runs. That avoids sending a large raw window to a provider that can't reuse the previous prompt cache.
 
 ### Disabling
 
@@ -458,4 +506,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/.docs/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