@mastra/memory 1.6.1 → 1.6.2

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.6.1"
+  version: "1.6.2"
 ---
 
 ## When to use
@@ -16,40 +16,40 @@ Read the individual reference documents for detailed explanations and code examp
 
 ### Docs
 
-- [Agent Approval](references/docs-agents-agent-approval.md) - Learn how to require approvals, suspend tool execution, and automatically resume suspended tools while keeping humans in control of agent workflows.
-- [Agent Memory](references/docs-agents-agent-memory.md) - Learn how to add memory to agents to store message history and maintain context across interactions.
-- [Network Approval](references/docs-agents-network-approval.md) - Learn how to require approvals, suspend execution, and resume suspended networks while keeping humans in control of agent network workflows.
-- [Agent Networks](references/docs-agents-networks.md) - Learn how to coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
-- [Supervisor Agents](references/docs-agents-supervisor-agents.md) - Learn how to coordinate multiple agents using the supervisor pattern with delegation hooks, iteration monitoring, message filtering, and task completion scoring.
-- [Memory Processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
-- [Message History](references/docs-memory-message-history.md) - Learn how to configure message history in Mastra to store recent messages from the current conversation.
-- [Observational Memory](references/docs-memory-observational-memory.md) - Learn how Observational Memory keeps your agent's context window small while preserving long-term memory across conversations.
+- [Agent approval](references/docs-agents-agent-approval.md) - Learn how to require approvals, suspend tool execution, and automatically resume suspended tools while keeping humans in control of agent workflows.
+- [Agent memory](references/docs-agents-agent-memory.md) - Learn how to add memory to agents to store message history and maintain context across interactions.
+- [Network approval](references/docs-agents-network-approval.md) - Learn how to require approvals, suspend execution, and resume suspended networks while keeping humans in control of agent network workflows.
+- [Agent networks](references/docs-agents-networks.md) - Learn how to coordinate multiple agents, workflows, and tools using agent networks for complex, non-deterministic task execution.
+- [Supervisor agents](references/docs-agents-supervisor-agents.md) - Learn how to coordinate multiple agents using the supervisor pattern with delegation hooks, iteration monitoring, message filtering, and task completion scoring.
+- [Memory processors](references/docs-memory-memory-processors.md) - Learn how to use memory processors in Mastra to filter, trim, and transform messages before they're sent to the language model to manage context window limits.
+- [Message history](references/docs-memory-message-history.md) - Learn how to configure message history in Mastra to store recent messages from the current conversation.
+- [Observational memory](references/docs-memory-observational-memory.md) - Learn how Observational Memory keeps your agent's context window small while preserving long-term memory across conversations.
 - [Memory overview](references/docs-memory-overview.md) - Learn how Mastra's memory system works with working memory, message history, semantic recall, and observational memory.
-- [Semantic Recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
+- [Semantic recall](references/docs-memory-semantic-recall.md) - Learn how to use semantic recall in Mastra to retrieve relevant messages from past conversations using vector search and embeddings.
 - [Storage](references/docs-memory-storage.md) - Configure storage for Mastra's memory system to persist conversations, workflows, and traces.
-- [Working Memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
+- [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
 
 ### Reference
 
 - [Reference: Mastra.getMemory()](references/reference-core-getMemory.md) - Documentation for the `Mastra.getMemory()` method in Mastra, which retrieves a registered memory instance by its registry key.
 - [Reference: Mastra.listMemory()](references/reference-core-listMemory.md) - Documentation for the `Mastra.listMemory()` method in Mastra, which returns all registered memory instances.
-- [Reference: Cloned Thread Utilities](references/reference-memory-clone-utilities.md) - Documentation for utility methods to work with cloned threads in Mastra Memory.
+- [Reference: Cloned thread utilities](references/reference-memory-clone-utilities.md) - Documentation for utility methods to work with cloned threads in Mastra Memory.
 - [Reference: Memory.cloneThread()](references/reference-memory-cloneThread.md) - Documentation for the `Memory.cloneThread()` method in Mastra, which creates a copy of a conversation thread with all its messages.
 - [Reference: Memory.createThread()](references/reference-memory-createThread.md) - Documentation for the `Memory.createThread()` method in Mastra, which creates a new conversation thread in the memory system.
 - [Reference: Memory.getThreadById()](references/reference-memory-getThreadById.md) - Documentation for the `Memory.getThreadById()` method in Mastra, which retrieves a specific thread by its ID.
 - [Reference: Memory.listThreads()](references/reference-memory-listThreads.md) - Documentation for the `Memory.listThreads()` method in Mastra, which retrieves threads with optional filtering by resourceId and/or metadata.
-- [Reference: Memory Class](references/reference-memory-memory-class.md) - Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage.
-- [Reference: Observational Memory](references/reference-memory-observational-memory.md) - API reference for Observational Memory in Mastra — a three-tier memory system that uses Observer and Reflector agents to maintain long-term memory across conversations.
-- [Reference: Token Limiter Processor](references/reference-processors-token-limiter-processor.md) - Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in messages.
-- [Reference: DynamoDB Storage](references/reference-storage-dynamodb.md) - Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.
-- [Reference: libSQL Storage](references/reference-storage-libsql.md) - Documentation for the libSQL storage implementation in Mastra.
-- [Reference: MongoDB Storage](references/reference-storage-mongodb.md) - Documentation for the MongoDB storage implementation in Mastra.
-- [Reference: PostgreSQL Storage](references/reference-storage-postgresql.md) - Documentation for the PostgreSQL storage implementation in Mastra.
-- [Reference: Upstash Storage](references/reference-storage-upstash.md) - Documentation for the Upstash storage implementation in Mastra.
-- [Reference: libSQL Vector Store](references/reference-vectors-libsql.md) - Documentation for the LibSQLVector class in Mastra, which provides vector search using libSQL with vector extensions.
-- [Reference: MongoDB Vector Store](references/reference-vectors-mongodb.md) - Documentation for the MongoDBVector class in Mastra, which provides vector search using MongoDB Atlas and Atlas Vector Search.
-- [Reference: PG Vector Store](references/reference-vectors-pg.md) - Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
-- [Reference: Upstash Vector Store](references/reference-vectors-upstash.md) - Documentation for the UpstashVector class in Mastra, which provides vector search using Upstash Vector.
+- [Reference: Memory class](references/reference-memory-memory-class.md) - Documentation for the `Memory` class in Mastra, which provides a robust system for managing conversation history and thread-based message storage.
+- [Reference: Observational memory](references/reference-memory-observational-memory.md) - API reference for Observational Memory in Mastra — a three-tier memory system that uses Observer and Reflector agents to maintain long-term memory across conversations.
+- [Reference: TokenLimiterProcessor](references/reference-processors-token-limiter-processor.md) - Documentation for the TokenLimiterProcessor in Mastra, which limits the number of tokens in messages.
+- [Reference: DynamoDB storage](references/reference-storage-dynamodb.md) - Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.
+- [Reference: libSQL storage](references/reference-storage-libsql.md) - Documentation for the libSQL storage implementation in Mastra.
+- [Reference: MongoDB storage](references/reference-storage-mongodb.md) - Documentation for the MongoDB storage implementation in Mastra.
+- [Reference: PostgreSQL storage](references/reference-storage-postgresql.md) - Documentation for the PostgreSQL storage implementation in Mastra.
+- [Reference: Upstash storage](references/reference-storage-upstash.md) - Documentation for the Upstash storage implementation in Mastra.
+- [Reference: libSQL vector store](references/reference-vectors-libsql.md) - Documentation for the LibSQLVector class in Mastra, which provides vector search using libSQL with vector extensions.
+- [Reference: MongoDB vector store](references/reference-vectors-mongodb.md) - Documentation for the MongoDBVector class in Mastra, which provides vector search using MongoDB Atlas and Atlas Vector Search.
+- [Reference: PG vector store](references/reference-vectors-pg.md) - Documentation for the PgVector class in Mastra, which provides vector search using PostgreSQL with pgvector extension.
+- [Reference: Upstash vector store](references/reference-vectors-upstash.md) - Documentation for the UpstashVector class in Mastra, which provides vector search using Upstash Vector.
 
 
 Read [assets/SOURCE_MAP.json](assets/SOURCE_MAP.json) for source code references.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,71 +1,71 @@
 {
-  "version": "1.6.1",
+  "version": "1.6.2",
   "package": "@mastra/memory",
   "exports": {
     "OBSERVATIONAL_MEMORY_DEFAULTS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js"
+      "implementation": "dist/chunk-3CM4XQJO.js"
     },
     "OBSERVATION_CONTEXT_INSTRUCTIONS": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js"
+      "implementation": "dist/chunk-3CM4XQJO.js"
     },
     "OBSERVATION_CONTEXT_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js"
+      "implementation": "dist/chunk-3CM4XQJO.js"
     },
     "OBSERVATION_CONTINUATION_HINT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js"
+      "implementation": "dist/chunk-3CM4XQJO.js"
     },
     "OBSERVER_SYSTEM_PROMPT": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js"
+      "implementation": "dist/chunk-3CM4XQJO.js"
     },
     "ObservationalMemory": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 1642
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 2907
     },
     "TokenCounter": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 1401
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 2385
     },
     "buildObserverPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 822
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 993
     },
     "buildObserverSystemPrompt": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 570
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 573
     },
     "extractCurrentTask": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 951
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 1101
     },
     "formatMessagesForObserver": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 665
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 820
     },
     "hasCurrentTaskSection": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 939
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 1089
     },
     "optimizeObservationsForContext": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 962
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 1112
     },
     "parseObserverOutput": {
       "types": "dist/processors/index.d.ts",
-      "implementation": "dist/chunk-GBBQIJQF.js",
-      "line": 853
+      "implementation": "dist/chunk-3CM4XQJO.js",
+      "line": 1003
     },
     "extractWorkingMemoryContent": {
       "types": "dist/index.d.ts",
@@ -96,7 +96,7 @@
     "processors": {
       "index": "dist/processors/index.js",
       "chunks": [
-        "chunk-GBBQIJQF.js"
+        "chunk-3CM4XQJO.js"
       ]
     }
   }

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

@@ -92,7 +92,7 @@ const handleDecline = async () => {
 }
 ```
 
-## Tool approval with generate()
+## Tool approval with `generate()`
 
 Tool approval also works with the `generate()` method for non-streaming use cases. When a tool requires approval during a `generate()` call, the method returns immediately instead of executing the tool.
 
@@ -504,7 +504,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-### Using suspend() in supervisor pattern
+### Using `suspend()` in supervisor pattern
 
 Tools can also use [`suspend()`](#approval-using-suspend) to pause execution and return context to the user. This approach works through the supervisor delegation chain the same way `requireApproval` does — the suspension surfaces at the supervisor level:
 
@@ -553,7 +553,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-### Tool approval with generate()
+### Tool approval with `generate()`
 
 Tool approval propagation also works with `generate()` in supervisor pattern:
 

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

@@ -96,7 +96,7 @@ export const memoryAgent = new Agent({
 })
 ```
 
-> **Mastra Cloud Store limitation:** Agent-level storage is not supported when using [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation does not apply if you bring your own database.
+> **Mastra Cloud Store limitation:** Agent-level storage isn't supported when using [Mastra Cloud Store](https://mastra.ai/docs/mastra-cloud/deployment). If you use Mastra Cloud Store, configure storage on the Mastra instance instead. This limitation doesn't apply if you bring your own database.
 
 ## Message history
 
@@ -127,11 +127,11 @@ const response = await memoryAgent.generate("What's my favorite color?", {
 })
 ```
 
-> **Warning:** Each thread has an owner (`resourceId`) that cannot be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
+> **Warning:** Each thread has an owner (`resourceId`) that can't be changed after creation. Avoid reusing the same thread ID for threads with different owners, as this will cause errors when querying.
 
 To learn more about memory see the [Memory](https://mastra.ai/docs/memory/overview) documentation.
 
-## Observational Memory
+## Observational memory
 
 For long-running conversations, raw message history grows until it fills the context window, degrading agent performance. [Observational Memory](https://mastra.ai/docs/memory/observational-memory) solves this by running background agents that compress old messages into dense observations, keeping the context window small while preserving long-term memory.
 

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

@@ -1,4 +1,6 @@
-# Network Approval
+# Network approval
+
+> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use the [supervisor pattern](https://mastra.ai/docs/agents/supervisor-agents) instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
 Agent networks can require the same [human-in-the-loop](https://mastra.ai/docs/workflows/human-in-the-loop) oversight used in individual agents and workflows. When a tool, subagent, or workflow within a network requires approval or suspends execution, the network pauses and emits events that allow your application to collect user input before resuming.
 
@@ -269,7 +271,8 @@ Both approaches work with the same tool definitions. Automatic resumption trigge
 
 ## Related
 
-- [Agent Networks](https://mastra.ai/docs/agents/networks)
+- [Supervisor Agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Migration: .network() to Supervisor Pattern](https://mastra.ai/guides/migrations/network-to-supervisor)
 - [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
 - [Human-in-the-Loop](https://mastra.ai/docs/workflows/human-in-the-loop)
 - [Agent Memory](https://mastra.ai/docs/agents/agent-memory)

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

@@ -1,6 +1,6 @@
-# Agent Networks
+# Agent networks
 
-> **Supervisor Pattern Recommended:** The [supervisor pattern](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` is now the recommended approach for coordinating multiple agents. It provides the same multi-agent coordination capabilities as `.network()` with significant improvements:
+> **Agent Network Deprecated — Supervisor Pattern Recommended:** Agent networks are deprecated and will be removed in a future release. The [supervisor pattern](https://mastra.ai/docs/agents/supervisor-agents) using `agent.stream()` or `agent.generate()` is now the recommended approach for coordinating multiple agents. It provides the same multi-agent coordination capabilities as `.network()` with significant improvements:
 >
 > - **Better control**: Iteration hooks, delegation hooks, and task completion scoring give you fine-grained control over execution
 > - **Simpler API**: Uses familiar `stream()` and `generate()` methods instead of a separate `.network()` API

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

@@ -1,4 +1,4 @@
-# Supervisor Agents
+# Supervisor agents
 
 A supervisor agent coordinates multiple subagents using `agent.stream()` or `agent.generate()`. You configure subagents on the supervisor's `agents` property, and the supervisor uses its instructions and each subagent's `description` to decide when and how to delegate tasks.
 
@@ -57,7 +57,7 @@ for await (const chunk of stream.textStream) {
 
 Delegation hooks let you intercept, modify, or reject delegations as they happen. Configure them under the `delegation` option, either in the agent's `defaultOptions` or per-call.
 
-### onDelegationStart
+### `onDelegationStart`
 
 Called before the supervisor delegates to a subagent. Return an object to control the delegation:
 
@@ -104,7 +104,7 @@ The `context` object includes:
 | `prompt`      | The prompt the supervisor is sending      |
 | `iteration`   | Current iteration number                  |
 
-### onDelegationComplete
+### `onDelegationComplete`
 
 Called after a delegation finishes. Use it to inspect results, provide feedback, or stop execution:
 

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

@@ -1,4 +1,4 @@
-# Memory Processors
+# Memory processors
 
 Memory processors transform and filter messages as they pass through an agent with memory enabled. They manage context window limits, remove unnecessary content, and optimize the information sent to the language model.
 
@@ -6,11 +6,11 @@ When memory is enabled on an agent, Mastra adds memory processors to the agent's
 
 Memory processors are [processors](https://mastra.ai/docs/agents/processors) that operate specifically on memory-related messages and state.
 
-## Built-in Memory Processors
+## Built-in memory processors
 
 Mastra automatically adds these processors when memory is enabled:
 
-### MessageHistory
+### `MessageHistory`
 
 Retrieves message history and persists new messages.
 
@@ -56,7 +56,7 @@ const agent = new Agent({
 })
 ```
 
-### SemanticRecall
+### `SemanticRecall`
 
 Retrieves semantically relevant messages based on the current input and creates embeddings for new messages.
 
@@ -114,7 +114,7 @@ const agent = new Agent({
 })
 ```
 
-### WorkingMemory
+### `WorkingMemory`
 
 Manages working memory state across conversations.
 
@@ -159,9 +159,9 @@ const agent = new Agent({
 })
 ```
 
-## Manual Control and Deduplication
+## Manual control and deduplication
 
-If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra will **not** automatically add it. This gives you full control over processor ordering:
+If you manually add a memory processor to `inputProcessors` or `outputProcessors`, Mastra **won't** automatically add it. This gives you full control over processor ordering:
 
 ```typescript
 import { Agent } from '@mastra/core/agent'
@@ -192,7 +192,7 @@ const agent = new Agent({
 })
 ```
 
-## Processor Execution Order
+## Processor execution order
 
 Understanding the execution order is important when combining guardrails with memory:
 
@@ -218,7 +218,7 @@ This means memory loads message history before your processors can validate or f
 
 This ordering is designed to be **safe by default**: if your output guardrail calls `abort()`, the memory processors never run and **no messages are saved**.
 
-## Guardrails and Memory
+## Guardrails and memory
 
 The default execution order provides safe guardrail behavior:
 

package/dist/docs/references/docs-memory-message-history.md

@@ -1,4 +1,4 @@
-# Message History
+# Message history
 
 Message history is the most basic and important form of memory. It gives the LLM a view of recent messages in the context window, enabling your agent to reference earlier exchanges and respond coherently.
 
@@ -98,12 +98,12 @@ await agent.stream('Hello', {
 
 > **Info:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
 
-There are two ways to use this history:
+You can use this history in two ways:
 
 - **Automatic inclusion** - Mastra automatically fetches and includes recent messages in the context window. By default, it includes the last 10 messages, keeping agents grounded in the conversation. You can adjust this number with `lastMessages`, but in most cases you don't need to think about it.
 - [**Manual querying**](#querying) - For more control, use the `recall()` function to query threads and messages directly. This lets you choose exactly which memories are included in the context window, or fetch messages to render conversation history in your UI.
 
-## Accessing Memory
+## Accessing memory
 
 To access memory functions for querying, cloning, or deleting threads and messages, call `getMemory()` on an agent:
 
@@ -118,7 +118,7 @@ The `Memory` instance gives you access to functions for listing threads, recalli
 
 Use these methods to fetch threads and messages for displaying conversation history in your UI or for custom memory retrieval logic.
 
-> **Warning:** The memory system does not enforce access control. Before running any query, verify in your application logic that the current user is authorized to access the `resourceId` being queried.
+> **Warning:** The memory system doesn't enforce access control. Before running any query, verify in your application logic that the current user is authorized to access the `resourceId` being queried.
 
 ### Threads
 

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

@@ -1,10 +1,10 @@
-# Observational Memory
+# Observational memory
 
 **Added in:** `@mastra/memory@1.1.0`
 
 Observational Memory (OM) is Mastra's memory system for long-context agentic memory. Two background agents — an **Observer** and a **Reflector** — watch your agent's conversations and maintain a dense observation log that replaces raw message history as it grows.
 
-## Quick Start
+## Quick start
 
 Enable `observationalMemory` in the memory options when creating your agent:
 
@@ -46,7 +46,7 @@ See [configuration options](https://mastra.ai/reference/memory/observational-mem
 - **Compression**: Raw message history and tool results get compressed into a dense observation log. Smaller context means faster responses and longer coherent conversations.
 - **Zero context rot**: The agent sees relevant information instead of noisy tool calls and irrelevant tokens, so the agent stays on task over long sessions.
 
-## How It Works
+## How it works
 
 You don't remember every word of every conversation you've ever had. You observe what happened subconsciously, then your brain reflects — reorganizing, combining, and condensing into long-term memory. OM works the same way.
 
@@ -61,6 +61,10 @@ OM solves both problems by compressing old context into dense observations.
 
 When message history tokens exceed a threshold (default: 30,000), the Observer creates observations — concise notes about what happened:
 
+Image parts contribute to this threshold with model-aware estimates, so multimodal conversations trigger observation at the right time. The same applies to image-like `file` parts when a transport normalizes an uploaded image as a file instead of an image part. For example, OpenAI image detail settings can materially change when OM decides to observe.
+
+The Observer can also see attachments in the history it reviews. OM keeps readable placeholders like `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript for readability, and forwards the actual attachment parts alongside the text. Image-like `file` parts are upgraded to image inputs for the Observer when possible, while non-image attachments are forwarded as file parts with normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
+
 ```text
 Date: 2026-01-15
 - 🔴 12:10 User is building a Next.js app with Supabase auth, due in 1 week (meaning January 22nd 2026)
@@ -145,7 +149,7 @@ For your use-case this may not be a problem, so your mileage may vary.
 
 > **Warning:** In resource scope, unobserved messages across _all_ threads are processed together. For users with many existing threads, this can be slow. Use thread scope for existing apps.
 
-## Token Budgets
+## Token budgets
 
 OM uses token thresholds to decide when to observe and reflect. See [token budget configuration](https://mastra.ai/reference/memory/observational-memory) for details.
 
@@ -177,9 +181,9 @@ OM caches tiktoken part estimates in message metadata to reduce repeat counting
 - Per-part estimates are stored on `part.providerMetadata.mastra` and reused on subsequent passes when the cache version/tokenizer source matches.
 - For string-only message content (without parts), OM uses a message-level metadata fallback cache.
 - Message and conversation overhead are still recalculated on every pass. The cache only stores payload estimates, so counting semantics stay the same.
-- `data-*` and `reasoning` parts are still skipped and are not cached.
+- `data-*` and `reasoning` parts are still skipped and aren't cached.
 
-## Async Buffering
+## Async buffering
 
 Without async buffering, the Observer runs synchronously when the message threshold is reached — the agent pauses mid-conversation while the Observer LLM call completes. With async buffering (enabled by default), observations are pre-computed in the background as the conversation grows. When the threshold is hit, buffered observations activate instantly with no pause.
 
@@ -224,7 +228,7 @@ const memory = new Memory({
 
 Setting `bufferTokens: false` disables both observation and reflection async buffering. See [async buffering configuration](https://mastra.ai/reference/memory/observational-memory) for the full API.
 
-> **Note:** Async buffering is not supported with `scope: 'resource'`. It is automatically disabled in resource scope.
+> **Note:** Async buffering isn't supported with `scope: 'resource'`. It's automatically disabled in resource scope.
 
 ## Migrating existing threads
 

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

@@ -1,10 +1,10 @@
-# Semantic Recall
+# Semantic recall
 
 If you ask your friend what they did last weekend, they will search in their memory for events associated with "last weekend" and then tell you what they did. That's sort of like how semantic recall works in Mastra.
 
 > **Watch 📹:** What semantic recall is, how it works, and how to configure it in Mastra → [YouTube (5 minutes)](https://youtu.be/UVZtK8cK8xQ)
 
-## How Semantic Recall Works
+## How semantic recall works
 
 Semantic recall is RAG-based search that helps agents maintain context across longer interactions when messages are no longer within [recent message history](https://mastra.ai/docs/memory/message-history).
 
@@ -16,7 +16,7 @@ When it's enabled, new messages are used to query a vector DB for semantically s
 
 After getting a response from the LLM, all new messages (user, assistant, and tool calls/results) are inserted into the vector DB to be recalled in later interactions.
 
-## Quick Start
+## Quick start
 
 Semantic recall is enabled by default, so if you give your agent memory it will be included:
 
@@ -33,9 +33,9 @@ const agent = new Agent({
 })
 ```
 
-## Using the recall() Method
+## Using the `recall()` method
 
-While `listMessages` retrieves messages by thread ID with basic pagination, [`recall()`](https://mastra.ai/reference/memory/recall) adds support for **semantic search**. When you need to find messages by meaning rather than just recency, use `recall()` with a `vectorSearchString`:
+While `listMessages` retrieves messages by thread ID with basic pagination, [`recall()`](https://mastra.ai/reference/memory/recall) adds support for **semantic search**. When you need to find messages by meaning rather than recency, use `recall()` with a `vectorSearchString`:
 
 ```typescript
 const memory = await agent.getMemory()
@@ -182,7 +182,7 @@ const agent = new Agent({
 })
 ```
 
-### Using FastEmbed (Local)
+### Using FastEmbed (local)
 
 To use FastEmbed (a local embedding model), install `@mastra/fastembed`:
 
@@ -224,7 +224,7 @@ const agent = new Agent({
 })
 ```
 
-## PostgreSQL Index Optimization
+## PostgreSQL index optimization
 
 When using PostgreSQL as your vector store, you can optimize semantic recall performance by configuring the vector index. This is particularly important for large-scale deployments with thousands of messages.
 
@@ -264,7 +264,7 @@ For detailed information about index configuration options and performance tunin
 
 ## Disabling
 
-There is a performance impact to using semantic recall. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
+Semantic recall has a performance impact. New messages are converted into embeddings and used to query a vector database before new messages are sent to the LLM.
 
 Semantic recall is enabled by default but can be disabled when not needed:
 
@@ -283,6 +283,6 @@ You might want to disable semantic recall in scenarios like:
 - When message history provides sufficient context for the current conversation.
 - In performance-sensitive applications, like realtime two-way audio, where the added latency of creating embeddings and running vector queries is noticeable.
 
-## Viewing Recalled Messages
+## Viewing recalled messages
 
 When tracing is enabled, any messages retrieved via semantic recall will appear in the agent's trace output, alongside recent message history (if configured).

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

@@ -170,7 +170,7 @@ export const agent = new Agent({
 })
 ```
 
-Title generation runs asynchronously after the agent responds and does not affect response time.
+Title generation runs asynchronously after the agent responds and doesn't affect response time.
 
 To optimize cost or behavior, provide a smaller [`model`](https://mastra.ai/models) and custom `instructions`: