@mastra/memory 1.24.0 → 1.25.0-alpha.1

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',

package/dist/docs/references/reference-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** that watches conversations and creates observations, and a **Reflector** that restructures observations by combining related items, reflecting on overarching patterns, and condensing where possible — maintain an observation log that replaces raw message history as it grows.
+Observational Memory (OM) is Mastra's memory system for long-context agentic memory. An **Observer** watches conversations and creates observations. A **Reflector** restructures those observations by combining related items and condensing overarching patterns. Together, they maintain an observation log that replaces raw message history as it grows.
 
 ## Usage
 
@@ -27,7 +27,7 @@ export const agent = new Agent({
 
 ## Configuration
 
-The `observationalMemory` option accepts `true`, a configuration object, or `false`. Setting `true` enables OM with `google/gemini-2.5-flash` as the default model. When passing a config object, a `model` must be explicitly set — either at the top level, or on `observation.model` and/or `reflection.model`.
+The `observationalMemory` option accepts `true`, a configuration object, or `false`. Setting `true` enables OM with `google/gemini-2.5-flash` as the default model. When passing a config object, set `model` at the top level or on `observation.model` and/or `reflection.model`; when all model fields are omitted, OM falls back to `google/gemini-2.5-flash`.
 
 Observer input is multimodal-aware. OM keeps text placeholders like `[Image #1: screenshot.png]` in the transcript it builds for the Observer, and also sends the underlying image parts when possible. This applies to both single-thread observation and batched multi-thread observation. Non-image files appear as placeholders only.
 
@@ -35,7 +35,7 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **enabled** (`boolean`): Enable or disable Observational Memory. When omitted from a config object, defaults to true. Only enabled: false explicitly disables it. (Default: `true`)
 
-**model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with observation.model or reflection.model — an error will be thrown if both are set. When using observationalMemory: true, defaults to google/gemini-2.5-flash. When passing a config object, this or observation.model/reflection.model must be set. Use "default" to explicitly use the default model (google/gemini-2.5-flash). (Default: `'google/gemini-2.5-flash' (when using observationalMemory: true)`)
+**model** (`string | LanguageModel | DynamicModel | ModelByInputTokens | ModelWithRetries[]`): Model for both the Observer and Reflector agents. Sets the model for both at once. Cannot be used together with observation.model or reflection.model — an error will be thrown if both are set. When this and observation.model/reflection.model are all omitted, OM falls back to google/gemini-2.5-flash. Use "default" to explicitly use the default model (google/gemini-2.5-flash). (Default: `'google/gemini-2.5-flash'`)
 
 **scope** (`'resource' | 'thread'`): Memory scope for observations. 'thread' keeps observations per-thread. 'resource' (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
@@ -47,7 +47,9 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **temporalMarkers** (`boolean`): Insert temporal-gap reminder markers before new user messages when the previous message in the thread is at least 10 minutes older. The marker is persisted in memory, emitted as an inline reminder event so clients can render it specially, and shown to the observer so it can anchor observations to when events occurred. (Default: `false`)
 
-**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): Enable retrieval-mode observation groups as durable pointers to raw message history. true enables cross-thread browsing by default. { vector: true } also enables semantic search using Memory's vector store and embedder. { scope: 'thread' } restricts the recall tool to the current thread only. Default scope is 'resource'. (Default: `false`)
+**retrieval** (`boolean | { vector?: boolean; scope?: 'thread' | 'resource' }`): Let the agent look up the raw message history behind its observations. Observation groups keep durable pointers to the original messages, and a recall tool is registered so the agent can browse them. true enables cross-thread browsing by default. { vector: true } also enables semantic search using Memory's vector store and embedder. { scope: 'thread' } restricts the recall tool to the current thread only. Default scope is 'resource'. (Default: `false`)
+
+**hooks** (`ObserveHooks`): Lifecycle hooks fired for every observation/reflection cycle — the manual observe()/reflect() APIs, turn-driven synchronous observation, and fire-and-forget async buffering. Callbacks receive threadId/resourceId/trigger call context ('manual' | 'turn-sync' | 'async-buffer'), and the end hooks (onObservationEnd/onReflectionEnd) additionally receive the OM model call's token usage and providerMetadata (where providers such as the AI Gateway report per-call cost), so apps can account for OM model spend without wrapping the observer/reflector models in middleware. Failed async-buffered cycles never throw; they report through the end hook's error field. Errors thrown by these hooks are caught and logged — they never fail the cycle.
 
 **observation** (`ObservationalMemoryObservationConfig`): Configuration for the observation step. Controls when the Observer agent runs and how it behaves.
 
@@ -59,29 +61,33 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.extract** (`Extractor[]`): Custom values to extract after observation. Schema-less extractors are requested inline in the Observer output. Schema-backed extractors run as a follow-up structured output call and are stored in thread OM metadata.
 
-**observation.observeAttachments** (`boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. true (default) forwards all attachments. false drops all attachments while keeping placeholders visible. An array is a case-insensitive mimeType allowlist supporting exact matches ('application/pdf'), wildcard subtypes ('image/\*'), and bare '\*' for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model. Tool-result attachments are filtered using the same rule.
+**observation.manageWorkingMemory** (`boolean`): Let the Observer manage working memory through OM extraction. Adds WorkingMemoryExtractor, defaults workingMemory.agentManaged to false, and defaults workingMemory.useStateSignals to true. See Working memory updates.
+
+**observation.observeAttachments** (`'auto' | boolean | string[]`): Controls which image/file attachments are forwarded to the Observer model alongside their placeholder text lines. true (default) forwards all attachments. false drops all attachments while keeping placeholders visible. 'auto' uses the provider capabilities registry to decide: attachments are forwarded when the Observer model supports multimodal input, dropped otherwise, and forwarded when no capability data is available for the model. An array is a case-insensitive mimeType allowlist supporting exact matches ('application/pdf'), wildcard subtypes ('image/\*'), and bare '\*' for everything. Useful when the Observer model is text-only (e.g. some DeepSeek endpoints) while the main agent uses a multimodal model. Tool-result attachments are filtered using the same rule.
 
 **observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. Text is estimated locally with tokenx. Image parts are included with model-aware heuristics when possible, with deterministic fallbacks when image metadata is incomplete. Image-like file parts are counted the same way when uploads are normalized as files.
 
 **observation.maxTokensPerBatch** (`number`): Maximum tokens per batch when observing multiple threads in resource scope. Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls.
 
-**observation.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent.
+**observation.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
 
 **observation.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output.
 
-**observation.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations.
+**observation.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations. The 100000 default is only applied with default model selection; custom models get no default.
 
-**observation.bufferTokens** (`number | false`): Token interval for async background observation buffering. Can be an absolute token count (e.g. 5000) or a fraction of messageTokens (e.g. 0.25 = buffer every 25% of threshold). When set, observations run in the background at this interval, storing results in a buffer. When the main messageTokens threshold is reached, buffered observations activate instantly without a blocking LLM call. Must resolve to less than messageTokens. Set to false to explicitly disable all async buffering (both observation and reflection).
+**observation.providerOptions** (`ProviderOptions`): Provider-specific options passed to the Observer agent, such as Google thinking configuration.
+
+**observation.bufferTokens** (`number | false`): How often background observation buffering runs. Values between 0 and 1 are fractions of messageTokens: 0.25 buffers every 25% of the threshold (7.5k tokens with the default 30k). Values of 1 or more are absolute token counts: 5000 buffers every 5k tokens. Buffered observations are stored until the messageTokens threshold is reached, then activate instantly without a blocking LLM call. Must resolve to less than messageTokens. Set to false to disable all async buffering (both observation and reflection).
 
 **observation.bufferOnIdle** (`boolean`): Run background observation buffering when an agent turn ends and the agent becomes idle. This is separate from bufferTokens, which controls step-time async buffering. Set this to true to buffer short idle turns without waiting for the next turn or the messageTokens threshold.
 
-**observation.bufferActivation** (`number`): Controls how much of the message window to retain after activation. Accepts a ratio (0-1) or an absolute token count (≥ 1000). For example, 0.8 means: activate enough buffers to remove 80% of messageTokens and leave 20% as active message history. An absolute token count like 4000 targets a goal of keeping \~4k message tokens remaining after activation. Higher values remove more message history per activation when using a ratio. Higher values keep more message history when using a token count.
+**observation.bufferActivation** (`number`): How much of the message window to clear when buffered observations activate. Values between 0 and 1 are the fraction of messageTokens to remove: 0.8 removes \~80% of the message history and keeps \~20% (6k tokens with the default 30k). Values of 1000 or more are the token count to keep: 4000 keeps \~4k message tokens after activation. Note the direction flips: a higher ratio removes more history, while a higher token count keeps more.
 
-**observation.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. If unset, the top-level activateAfterIdle value is used for observations. Set false to disable the top-level idle setting for observations.
+**observation.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. If unset, the top-level activateAfterIdle value is used for observations. Set false to disable the top-level idle setting for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateAfterIdle only.
 
-**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level activateOnProviderChange value is used for observations.
+**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level activateOnProviderChange value is used for observations. Currently only applied when using the standalone ObservationalMemory class; new Memory(...) applies the top-level activateOnProviderChange only.
 
-**observation.blockAfter** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between messageTokens and blockAfter, only async buffering/activation is used. Above blockAfter, a synchronous observation runs as a last resort, while buffered activation still preserves a minimum remaining context (min(1000, retention floor)). Accepts a multiplier (1 < value < 2, multiplied by messageTokens) or an absolute token count (≥ 2, must be greater than messageTokens). Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
+**observation.blockAfter** (`number`): Safety net that forces a synchronous (blocking) observation when background buffering can't keep up. Values from 1 up to (but not including) 100 are multipliers of messageTokens: 1.2 forces a blocking observation at 120% of the threshold (36k tokens with the default 30k). Values of 100 or more are absolute token counts and must be greater than messageTokens. Between messageTokens and blockAfter, only async buffering and activation run; buffered activation still preserves a minimum remaining context (the smaller of 1000 tokens or the retention floor). Only relevant when bufferTokens is set. Defaults to 1.2 when async buffering is enabled.
 
 **observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to 0 to omit previous observations entirely, or false to disable truncation explicitly.
 
@@ -95,19 +101,21 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.observationTokens** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them.
 
-**reflection.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent.
+**reflection.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
 
 **reflection.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output.
 
-**reflection.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations.
+**reflection.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations. The 100000 default is only applied with default model selection; custom models get no default.
+
+**reflection.providerOptions** (`ProviderOptions`): Provider-specific options passed to the Reflector agent, such as Google thinking configuration.
 
-**reflection.bufferActivation** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach observationTokens \* bufferActivation, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
+**reflection.bufferActivation** (`number`): When background reflection starts, as a ratio (0-1) of observationTokens: 0.5 starts reflecting in the background once observations reach 50% of the threshold (20k tokens with the default 40k). When the full threshold is reached, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
 
-**reflection.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. Reflections do not inherit top-level activateAfterIdle; set this explicitly to opt reflections into idle activation.
+**reflection.activateAfterIdle** (`number | string | false | "auto"`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, "auto" for a provider-aware prompt cache TTL, or false. Reflections do not inherit top-level activateAfterIdle; set this explicitly to opt reflections into idle activation. Currently only applied when using the standalone ObservationalMemory class; this setting has no effect through new Memory(...).
 
-**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level activateOnProviderChange; set this explicitly to opt reflections into provider-change activation.
+**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level activateOnProviderChange; set this explicitly to opt reflections into provider-change activation. Currently only applied when using the standalone ObservationalMemory class; this setting has no effect through new Memory(...).
 
-**reflection.blockAfter** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between observationTokens and blockAfter, only async buffering/activation is used. Above blockAfter, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by observationTokens) or an absolute token count (≥ 2, must be greater than observationTokens). Only relevant when bufferActivation is set. Defaults to 1.2 when async reflection is enabled.
+**reflection.blockAfter** (`number`): Safety net that forces a synchronous (blocking) reflection when background reflection can't keep up. Values from 1 up to (but not including) 100 are multipliers of observationTokens: 1.2 forces a blocking reflection at 120% of the threshold (48k tokens with the default 40k). Values of 100 or more are absolute token counts and must be greater than observationTokens. Between observationTokens and blockAfter, only async buffering and activation run. Only relevant when bufferActivation is set. Defaults to 1.2 when async reflection is enabled.
 
 ### Token estimate metadata cache
 
@@ -150,7 +158,7 @@ const memory = new Memory({
 
 **name** (`string`): Human-readable extractor name. OM slugifies this value into the extractor slug. Names must be unique after slug generation.
 
-**slug** (`string`): Generated stable identifier for persisted values and XML tags. Slugs use lowercase letters, numbers, and hyphens. Built-in slugs and reserved XML tags cannot be used by custom extractors.
+**slug** (`string`): Read-only property derived from name — not a constructor option. Generated stable identifier for persisted values and XML tags. Slugs use lowercase letters, numbers, and hyphens. Built-in slugs and reserved XML tags cannot be used by custom extractors.
 
 **instructions** (`string | (context) => string`): Instructions for what to extract and when to update the value. Use a function to derive instructions from runtime context.
 
@@ -158,6 +166,8 @@ const memory = new Memory({
 
 **includePreviousExtraction** (`boolean`): Controls whether the previous extraction is shown to the extractor on future OM runs. Set to false for values that should only come from the current OM run. (Default: `true`)
 
+**metadataKeyPath** (`string | false`): Dot-separated OM metadata path used to persist the extracted value. Set to false to skip OM metadata persistence entirely. (Default: `'extracted.<slug>'`)
+
 **onExtracted** (`(context) => T | void | Promise<T | void>`): Optional hook called after a custom extractor returns a value and before metadata is persisted. Returning a value replaces the extracted value. Throwing records an extraction failure.
 
 ### Extraction behavior
@@ -170,7 +180,7 @@ const memory = new Memory({
 - Schema-less extractors are inline string extractors emitted directly in the Observer or Reflector output.
 - Dynamic extractor functions receive runtime context, including `source`, `threadId`, `resourceId`, `mainAgent`, `memory`, and `requestContext` when available.
 - `WorkingMemoryExtractor` uses the normal extractor pipeline to update working memory through the active `Memory` instance. It uses structured extraction when working memory has a JSON schema and skips OM metadata persistence, so the working memory payload isn't duplicated under OM extracted metadata.
-- `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor`, defaults `workingMemory.agentManaged` to `false`, and defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
+- `observationalMemory.observation.manageWorkingMemory` adds `WorkingMemoryExtractor` and defaults `workingMemory.agentManaged` to `false`. It defaults `workingMemory.useStateSignals` to `true` when working memory is enabled.
 - Extraction failures are reported in OM marker data and don't discard other successful extracted values.
 
 ## Examples
@@ -269,7 +279,7 @@ export const agent = new Agent({
   id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     options: {
       observationalMemory: {
@@ -290,7 +300,7 @@ export const agent = new Agent({
   id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     options: {
       observationalMemory: {
@@ -318,7 +328,7 @@ export const agent = new Agent({
   id: 'health-assistant',
   name: 'health-assistant',
   instructions: 'You are a health and wellness assistant.',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({
     options: {
       observationalMemory: {
@@ -341,16 +351,16 @@ export const agent = new Agent({
 
 ### Async buffering
 
-Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows — when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
+Async buffering is **enabled by default**. It pre-computes observations in the background as the conversation grows: when the `messageTokens` threshold is reached, buffered observations activate instantly with no blocking LLM call.
 
-The lifecycle is: **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
+The lifecycle follows **buffer → activate → remove messages → repeat**. Background Observer calls run at `bufferTokens` intervals, each producing a chunk of observations. At threshold, chunks activate: observations move into the log, raw messages are removed from context. The `blockAfter` threshold forces a synchronous fallback if buffering can't keep up.
 
 Default settings:
 
-- `observation.bufferTokens: 0.2` — buffer every 20% of `messageTokens` (e.g. every \~6k tokens with a 30k threshold)
-- `observation.bufferActivation: 0.8` — on activation, remove enough messages to keep only 20% of the threshold remaining
+- `observation.bufferTokens: 0.2`: Buffer every 20% of `messageTokens` (e.g. every \~6k tokens with a 30k threshold)
+- `observation.bufferActivation: 0.8`: On activation, remove enough messages to keep only 20% of the threshold remaining
 - Buffered observations include continuation hints (`suggestedResponse`, `currentTask`) that survive activation to maintain conversational continuity
-- `reflection.bufferActivation: 0.5` — start background reflection at 50% of observation threshold
+- `reflection.bufferActivation: 0.5`: start background reflection at 50% of observation threshold
 
 To customize:
 
@@ -476,7 +486,7 @@ interface DataOmStatusPart {
 }
 ```
 
-`buffered.reflection.inputObservationTokens` is the size of the observations that were sent to the Reflector. `buffered.reflection.observationTokens` is the compressed result — the size of what will replace those observations when the reflection activates. A client can use these two values to show a compression ratio.
+`buffered.reflection.inputObservationTokens` is the size of the observations that were sent to the Reflector. `buffered.reflection.observationTokens` is the compressed result: the size of what will replace those observations when the reflection activates. A client can use these two values to show a compression ratio.
 
 Clients can derive percentages and post-activation estimates from the raw values:
 
@@ -643,7 +653,7 @@ Emitted when async buffering fails. The system falls back to synchronous process
 
 ### `data-om-activation`
 
-Emitted when buffered observations or reflections are activated (moved into the active context window). This is an instant operation — no LLM call is involved.
+Emitted when buffered observations or reflections are activated (moved into the active context window). This is an instant operation: no LLM call is involved.
 
 **cycleId** (`string`): Unique ID for this activation event.
 
@@ -663,18 +673,45 @@ Emitted when buffered observations or reflections are activated (moved into the
 
 **observations** (`string`): The activated observations text.
 
+**triggeredBy** (`'threshold' | 'ttl' | 'provider_change'`): Whether activation was triggered by threshold crossing, activateAfterIdle expiry, or a model/provider change.
+
+**lastActivityAt** (`number`): Unix-ms timestamp of the last assistant message part used for TTL checks.
+
+**ttlExpiredMs** (`number`): How long activateAfterIdle had been exceeded when activation fired.
+
+**previousModel** (`string`): Previous assistant model identifier that triggered activation (e.g. openai/gpt-4o).
+
+**currentModel** (`string`): Current actor model identifier that triggered activation.
+
 **recordId** (`string`): The OM record ID.
 
 **threadId** (`string`): This thread's ID.
 
 **config** (`ObservationMarkerConfig`): Snapshot of config at activation time.
 
+### `data-om-thread-update`
+
+Emitted when the Observer updates the thread title. Only emitted when `observation.threadTitle` is enabled.
+
+**cycleId** (`string`): Unique ID for this observation cycle — shared with observation markers.
+
+**threadId** (`string`): The thread ID that was updated.
+
+**oldTitle** (`string`): The previous thread title. Undefined if the thread had no title.
+
+**newTitle** (`string`): The new thread title.
+
+**timestamp** (`string`): When this update occurred.
+
 ## Standalone usage
 
 Most users should use the `Memory` class above. Using `ObservationalMemory` directly is mainly useful for benchmarking, experimentation, or when you need to control processor ordering with other processors (like [guardrails](https://mastra.ai/docs/agents/guardrails)).
 
+The `ObservationalMemory` class is the engine; to attach it to an agent, wrap it in an `ObservationalMemoryProcessor`, which needs a `Memory` instance for loading and persisting messages. Note that `stores.memory` is typed as optional on storage adapters, so a non-null assertion (or a runtime check) is needed:
+
 ```typescript
-import { ObservationalMemory } from '@mastra/memory/processors'
+import { ObservationalMemory, ObservationalMemoryProcessor } from '@mastra/memory/processors'
+import { Memory } from '@mastra/memory'
 import { Agent } from '@mastra/core/agent'
 import { LibSQLStore } from '@mastra/libsql'
 
@@ -683,8 +720,11 @@ const storage = new LibSQLStore({
   url: 'file:./memory.db',
 })
 
+const memory = new Memory({ storage })
+
 const om = new ObservationalMemory({
-  storage: storage.stores.memory,
+  storage: storage.stores.memory!,
+  memory,
   model: 'google/gemini-2.5-flash',
   scope: 'resource',
   observation: {
@@ -695,13 +735,15 @@ const om = new ObservationalMemory({
   },
 })
 
+const omProcessor = new ObservationalMemoryProcessor(om, memory)
+
 export const agent = new Agent({
   id: 'my-agent',
   name: 'my-agent',
   instructions: 'You are a helpful assistant.',
   model: 'openai/gpt-5-mini',
-  inputProcessors: [om],
-  outputProcessors: [om],
+  inputProcessors: [omProcessor],
+  outputProcessors: [omProcessor],
 })
 ```
 
@@ -717,7 +759,7 @@ The standalone `ObservationalMemory` class accepts all the same options as the `
 
 ## Recall tool
 
-When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list — no manual registration is needed.
+When `retrieval` is set (any truthy value), a `recall` tool is registered so the agent can page through raw messages behind observation group ranges. By default (scope `'resource'`), the tool supports listing threads (`mode: "threads"`), browsing other threads (`threadId`), and cross-thread search. With `retrieval: { vector: true }`, semantic search is available (`mode: "search"`). Set `scope: 'thread'` to restrict the tool to the current thread only. The tool is automatically added to the agent's tool list.
 
 ### Parameters
 
@@ -725,9 +767,11 @@ When `retrieval` is set (any truthy value), a `recall` tool is registered so the
 
 **query** (`string`): Search query for mode: "search". Finds messages semantically similar to this text across all threads for the current user.
 
-**cursor** (`string`): A message ID to anchor the recall query. Required for mode: "messages" when browsing the current thread. Extract the start or end ID from an observation group range (e.g. from \_range: \startId:endId\\\_, use either startId or endId). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID. Can be omitted when threadId is provided to start reading from the beginning of that thread.
+**cursor** (`string`): A message ID to anchor the recall query. Extract the start or end ID from an observation group range (e.g. from \_range: \startId:endId\\\_, use either startId or endId). If a range string is passed directly, the tool returns a hint explaining how to extract the correct ID. When both cursor and threadId are omitted for mode: "messages", the tool browses the current thread from the position set by anchor.
+
+**threadId** (`string`): Browse a different thread by its ID, or pass "current" for the active thread. Use mode: "threads" first to discover thread IDs. When provided without a cursor, reading starts from the beginning of the thread.
 
-**threadId** (`string`): Browse a different thread by its ID. Use mode: "threads" first to discover thread IDs. When provided without a cursor, reading starts from the beginning of the thread.
+**anchor** (`'start' | 'end'`): For mode: "messages" without a cursor, page from the start (oldest-first) or end (newest-first) of the thread. (Default: `'start'`)
 
 **page** (`number`): Pagination offset. For messages: positive values page forward from cursor, negative values page backward. For threads: page number (0-indexed). 0 is treated as 1 for messages. (Default: `1`)
 
@@ -735,6 +779,10 @@ When `retrieval` is set (any truthy value), a `recall` tool is registered so the
 
 **detail** (`'low' | 'high'`): Controls how much content is shown per message part. 'low' shows truncated text and tool names with positional indices (\[p0], \[p1]). 'high' shows full content including tool arguments and results, clamped to one part per call with continuation hints. (Default: `'low'`)
 
+**partType** (`'text' | 'tool-call' | 'tool-result' | 'reasoning' | 'image' | 'file'`): Filter results to only include message parts of this type. Only applies to mode: "messages".
+
+**toolName** (`string`): Filter results to only include tool-call and tool-result parts matching this tool name. Only applies to mode: "messages".
+
 **partIndex** (`number`): Fetch a single message part at full detail by its positional index. Use this when a low-detail recall shows an interesting part at \[p1] — call again with partIndex: 1 to see the full content without loading every part.
 
 **before** (`string`): For mode: "threads" only. Filter to threads created before this date. Accepts ISO 8601 format (e.g. "2026-03-15", "2026-03-10T00:00:00Z").
@@ -753,6 +801,8 @@ When `retrieval` is set (any truthy value), a `recall` tool is registered so the
 
 **limit** (`number`): The limit used for this query.
 
+**detail** (`'low' | 'high'`): The detail level used for this query.
+
 **hasNextPage** (`boolean`): Whether more messages exist after this page.
 
 **hasPrevPage** (`boolean`): Whether more messages exist before this page.
@@ -798,7 +848,7 @@ const selector = new ModelByInputTokens({
   upTo: {
     10_000: 'google/gemini-2.5-flash', // Fast for small inputs
     40_000: 'openai/gpt-5-mini', // Stronger for medium inputs
-    1_000_000: 'openai/gpt-5.5', // Most capable for large inputs
+    1_000_000: 'openai/gpt-5.6-sol', // Most capable for large inputs
   },
 })
 ```

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

@@ -2,11 +2,11 @@
 
 # summarizeConversation()
 
-The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — without Observational Memory attached to an agent, and without reading from or writing to storage.
+The standalone `summarizeConversation()` function summarizes a conversation in one shot. It distills the messages you pass in with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory): without Observational Memory attached to an agent, and without reading from or writing to storage.
 
-Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go: for example your own database.
 
-Use this when you already have the messages in hand and want explicit control over what gets summarized. To summarize a stored thread by ID instead, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
+Use this when you already have the messages in hand and want explicit control over what gets summarized. For a stored thread identified by ID, use [`Memory.summarizeThread()`](https://mastra.ai/reference/memory/summarizeThread), which loads the messages for you.
 
 ## Usage example
 

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

@@ -2,13 +2,13 @@
 
 # Memory.summarizeThread()
 
-The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory) — as a standalone call, without Observational Memory attached to an agent.
+The `.summarizeThread()` method summarizes a thread's conversation in one shot. It loads the thread's messages from storage and distills them with the same Observer plumbing that powers [Observational Memory](https://mastra.ai/reference/memory/observational-memory): as a standalone call, without Observational Memory attached to an agent.
 
 Messages load page-by-page starting from the newest, bounded by `lastMessages` and `maxInputTokens`, so summarizing a long thread doesn't read its entire history from storage.
 
-Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go — for example your own database.
+Nothing is written back to memory. The summary and extracted values are returned to you (and to each extractor's `onExtracted` hook), so you decide where they go: for example your own database.
 
-Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. To summarize messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead — it takes the same options with `messages` in place of `threadId`.
+Use this when a session ends and you want a summary or structured extraction of the whole conversation, such as a voice call at hang-up. For messages you already have in hand (without loading them from a thread), use the standalone [`summarizeConversation()`](https://mastra.ai/reference/memory/summarizeConversation) function instead. It takes the same options with `messages` in place of `threadId`.
 
 ## Usage example
 

package/dist/docs/references/reference-processors-token-limiter-processor.md

@@ -84,7 +84,7 @@ export const agent = new Agent({
   id: 'context-limited-agent',
   name: 'context-limited-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   memory: new Memory({/* ... */}),
   inputProcessors: [
     new TokenLimiterProcessor({ limit: 4000 }), // Limits historical messages to ~4000 tokens
@@ -94,7 +94,7 @@ export const agent = new Agent({
 
 ### As a per-step input processor (limit multi-step token growth)
 
-When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps. Use `inputProcessors` to also limit tokens at each step of the agentic loop — the `TokenLimiterProcessor` automatically applies to both the initial input and every subsequent step:
+When an agent uses tools across multiple steps (e.g. `maxSteps > 1`), each step accumulates conversation history from all previous steps. Use `inputProcessors` to also limit tokens at each step of the agentic loop. The `TokenLimiterProcessor` automatically applies to both the initial input and every subsequent step:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -104,7 +104,7 @@ export const agent = new Agent({
   id: 'multi-step-agent',
   name: 'multi-step-agent',
   instructions: 'You are a helpful research assistant with access to tools',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   inputProcessors: [
     new TokenLimiterProcessor({ limit: 8000 }), // Applied at every step
   ],
@@ -128,7 +128,7 @@ export const agent = new Agent({
   id: 'response-limited-agent',
   name: 'response-limited-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.5',
+  model: 'openai/gpt-5.6-sol',
   outputProcessors: [
     new TokenLimiterProcessor({
       limit: 1000,