@mastra/memory 1.6.1 → 1.6.2-alpha.0

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-memory
 description: Documentation for @mastra/memory. Use when working with @mastra/memory APIs, configuration, or implementation.
 metadata:
   package: "@mastra/memory"
-  version: "1.6.1"
+  version: "1.6.2-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,71 +1,71 @@
 {
-  "version": "1.6.1",
+  "version": "1.6.2-alpha.0",
   "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-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,7 +127,7 @@ 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.
 

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

@@ -1,5 +1,7 @@
 # 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.
 
 ## Storage
@@ -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
 
-> **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-memory-memory-processors.md

@@ -161,7 +161,7 @@ const agent = new Agent({
 
 ## 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'

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

@@ -98,7 +98,7 @@ 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.
@@ -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

@@ -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)
@@ -177,7 +181,7 @@ 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
 
@@ -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

@@ -35,7 +35,7 @@ const agent = new Agent({
 
 ## 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()
@@ -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:
 

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`:
 

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

@@ -170,11 +170,11 @@ const memory = new Memory({
 
 ## Designing Effective Templates
 
-A well-structured template keeps the information easy for the agent to parse and update. Treat the template as a short form that you want the assistant to keep up to date.
+A well-structured template keeps the information straightforward for the agent to parse and update. Treat the template as a short form that you want the assistant to keep up to date.
 
-- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example `## Personal Info` or `- Name:`) so updates are easy to read and less likely to be truncated.
+- **Short, focused labels.** Avoid paragraphs or very long headings. Keep labels brief (for example `## Personal Info` or `- Name:`) so updates are readable and less likely to be truncated.
 - **Use consistent casing.** Inconsistent capitalization (`Timezone:` vs `timezone:`) can cause messy updates. Stick to Title Case or lower case for headings and bullet labels.
-- **Keep placeholder text simple.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM fill in the correct spots.
+- **Keep placeholder text minimal.** Use hints such as `[e.g., Formal]` or `[Date]` to help the LLM fill in the correct spots.
 - **Abbreviate very long values.** If you only need a short form, include guidance like `- Name: [First name or nickname]` or `- Address (short):` rather than the full legal text.
 - **Mention update rules in `instructions`.** You can instruct how and when to fill or clear parts of the template directly in the agent's `instructions` field.
 
@@ -263,13 +263,13 @@ Schema-based working memory uses **merge semantics**, meaning the agent only nee
 
 - **Object fields are deep merged:** Only provided fields are updated; others remain unchanged
 - **Set a field to `null` to delete it:** This explicitly removes the field from memory
-- **Arrays are replaced entirely:** When an array field is provided, it replaces the existing array (arrays are not merged element-by-element)
+- **Arrays are replaced entirely:** When an array field is provided, it replaces the existing array (arrays aren't merged element-by-element)
 
 ## 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. 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` is not supported.
+- Only one mode can be active at a time: setting both `template` and `schema` isn't supported.
 
 ## Example: Multi-step Retention
 
@@ -301,7 +301,7 @@ Below is a simplified view of how the `User Profile` template updates across a s
 
 The agent can now refer to `Sam` or `Berlin` in later responses without requesting the information again because it has been stored in working memory.
 
-If your agent is not properly updating working memory when you expect it to, you can add system instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
+If your agent isn't properly updating working memory when you expect it to, you can add system instructions on _how_ and _when_ to use this template in your agent's `instructions` setting.
 
 ## Setting Initial Working Memory
 

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

@@ -135,4 +135,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 are not 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-observational-memory.md

@@ -26,6 +26,8 @@ export const agent = new Agent({
 
 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`.
 
+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.
+
 **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 | 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)`)
@@ -40,7 +42,7 @@ The `observationalMemory` option accepts `true`, a configuration object, or `fal
 
 **observation.instruction** (`string`): Custom instruction appended to the Observer's system prompt. Use this to customize what the Observer focuses on, such as domain-specific preferences or priorities.
 
-**observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called.
+**observation.messageTokens** (`number`): Token count of unobserved messages that triggers observation. When unobserved message tokens exceed this threshold, the Observer agent is called. Image parts are included with model-aware estimates 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.
 
@@ -80,9 +82,9 @@ OM persists token payload estimates so repeated counting can reuse prior tiktoke
 
 - Part-level cache: `part.providerMetadata.mastra`.
 - String-content fallback cache: message-level metadata when no parts exist.
-- Cache entries are ignored and recomputed if cache version/tokenizer source does not match.
-- Per-message and per-conversation overhead are always recomputed at runtime and are not cached.
-- `data-*` and `reasoning` parts are skipped and do not receive cache entries.
+- Cache entries are ignored and recomputed if cache version/tokenizer source doesn't match.
+- Per-message and per-conversation overhead are always recomputed at runtime and aren't cached.
+- `data-*` and `reasoning` parts are skipped and don't receive cache entries.
 
 ## Examples
 
@@ -283,7 +285,7 @@ observationalMemory: {
 
 Setting `bufferTokens: false` disables both observation and reflection async buffering. Observations and reflections will run synchronously when their thresholds are reached.
 
-> **Note:** Async buffering is not supported with `scope: 'resource'` and is automatically disabled in resource scope.
+> **Note:** Async buffering isn't supported with `scope: 'resource'` and is automatically disabled in resource scope.
 
 ## Streaming data parts
 

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

@@ -47,8 +47,8 @@ const processor = new TokenLimiterProcessor({
 
 When used as an input processor, `TokenLimiterProcessor` throws a `TripWire` error in the following cases:
 
-- **Empty messages**: If there are no messages to process, a TripWire is thrown because you cannot send an LLM request with no messages.
-- **System messages exceed limit**: If system messages alone exceed the token limit, a TripWire is thrown because you cannot send an LLM request with only system messages and no user/assistant messages.
+- **Empty messages**: If there are no messages to process, a TripWire is thrown because you can't send an LLM request with no messages.
+- **System messages exceed limit**: If system messages alone exceed the token limit, a TripWire is thrown because you can't send an LLM request with only system messages and no user/assistant messages.
 
 ```typescript
 import { TripWire } from '@mastra/core/agent'

package/dist/docs/references/reference-storage-dynamodb.md

@@ -2,7 +2,7 @@
 
 The DynamoDB storage implementation provides a scalable and performant NoSQL database solution for Mastra, leveraging a single-table design pattern with [ElectroDB](https://electrodb.dev/).
 
-> **Observability Not Supported:** DynamoDB storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to DynamoDB, and Mastra Studio's observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** DynamoDB storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to DynamoDB, and Mastra Studio's observability features won't work with DynamoDB as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
 
 > **Item Size Limit:** DynamoDB enforces a **400 KB maximum item size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
 
@@ -211,7 +211,7 @@ aws dynamodb update-time-to-live \
 1. Go to the DynamoDB console
 2. Select your table
 3. Go to "Additional settings" tab
-4. Under "Time to Live (TTL)", click "Manage TTL"
+4. Under "Time to Live (TTL)", select "Manage TTL"
 5. Enable TTL and specify the attribute name (default: `ttl`)
 
 > **Note:** DynamoDB deletes expired items within 48 hours after expiration. Items remain queryable until actually deleted.

package/dist/docs/references/reference-storage-mongodb.md

@@ -136,7 +136,7 @@ const memoryStore = await storage.getStore('memory')
 const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
-> **Warning:** If `init()` is not called, collections won't be created and storage operations will fail silently or throw errors.
+> **Warning:** If `init()` isn't called, collections won't be created and storage operations will fail silently or throw errors.
 
 ## Vector Search Capabilities
 

package/dist/docs/references/reference-storage-postgresql.md

@@ -177,7 +177,7 @@ const memoryStore = await storage.getStore('memory')
 const thread = await memoryStore?.getThreadById({ threadId: '...' })
 ```
 
-> **Warning:** If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+> **Warning:** If `init()` isn't called, tables won't be created and storage operations will fail silently or throw errors.
 
 ### Using an Existing Pool
 
@@ -201,7 +201,7 @@ const storage = new PostgresStore({
 
 **Pool lifecycle behavior:**
 
-- When you **provide a pool**: Mastra uses your pool but does **not** close it when `store.close()` is called. You manage the pool lifecycle.
+- When you **provide a pool**: Mastra uses your pool but **doesn't** close it when `store.close()` is called. You manage the pool lifecycle.
 - When Mastra **creates a pool**: Mastra owns the pool and will close it when `store.close()` is called.
 
 ### Direct Database and Pool Access

package/dist/docs/references/reference-storage-upstash.md

@@ -4,7 +4,7 @@ The Upstash storage implementation provides a serverless-friendly storage soluti
 
 > **Pricing:** When using Mastra with Upstash, the pay-as-you-go model can result in unexpectedly high costs due to the high volume of Redis commands generated during agent conversations. We strongly recommend using a **fixed pricing plan** for predictable costs. See [Upstash pricing](https://upstash.com/pricing/redis) for details and [GitHub issue #5850](https://github.com/mastra-ai/mastra/issues/5850) for context.
 
-> **Observability Not Supported:** Upstash storage **does not support the observability domain**. Traces from the `DefaultExporter` cannot be persisted to Upstash, and Mastra Studio's observability features won't work with Upstash as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** Upstash storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to Upstash, and Mastra Studio's observability features won't work with Upstash as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
 
 ## Installation
 

package/dist/docs/references/reference-vectors-pg.md

@@ -82,6 +82,8 @@ const vectorStore = new PgVector({
 
 **buildIndex** (`boolean`): Whether to build the index (Default: `true`)
 
+**metadataIndexes** (`string[]`): Array of metadata field names to create btree indexes on. Improves query performance when filtering by these metadata fields.
+
 #### IndexConfig
 
 **type** (`'flat' | 'hnsw' | 'ivfflat'`): Index type (Default: `ivfflat`)

package/dist/index.cjs

@@ -9,11 +9,11 @@ var agent = require('@mastra/core/agent');
 var features = require('@mastra/core/features');
 var memory = require('@mastra/core/memory');
 var utils = require('@mastra/core/utils');
-var zodToJson = require('@mastra/schema-compat/zod-to-json');
+var schema = require('@mastra/schema-compat/schema');
 var asyncMutex = require('async-mutex');
 var xxhash = require('xxhash-wasm');
+var schema$1 = require('@mastra/core/schema');
 var tools = require('@mastra/core/tools');
-var schemaCompat = require('@mastra/schema-compat');
 var processors = require('@mastra/core/processors');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -15147,19 +15147,26 @@ function deepMergeWorkingMemory(existing, update) {
   return result;
 }
 var updateWorkingMemoryTool = (memoryConfig) => {
-  const schema = memoryConfig?.workingMemory?.schema;
+  const schema$2 = memoryConfig?.workingMemory?.schema;
   let inputSchema = zod.z.object({
     memory: zod.z.string().describe(`The Markdown formatted working memory content to store. This MUST be a string. Never pass an object.`)
   });
-  if (schema) {
-    inputSchema = zod.z.object({
-      memory: schema instanceof zod.ZodObject ? schema : schemaCompat.convertSchemaToZod({ jsonSchema: schema }).describe(
-        `The JSON formatted working memory content to store.`
-      )
+  if (schema$2) {
+    const standardSchema2 = schema$1.isStandardSchemaWithJSON(schema$2) ? schema$2 : schema$1.toStandardSchema(schema$2);
+    const jsonSchema4 = schema.standardSchemaToJSONSchema(standardSchema2, { io: "input" });
+    delete jsonSchema4.$schema;
+    inputSchema = schema$1.toStandardSchema({
+      $schema: "http://json-schema.org/draft-07/schema#",
+      type: "object",
+      description: "The JSON formatted working memory content to store.",
+      properties: {
+        memory: jsonSchema4
+      },
+      required: ["memory"]
     });
   }
-  const usesMergeSemantics = Boolean(schema);
-  const description = schema ? `Update the working memory with new information. Data is merged with existing memory - you only need to include fields you want to add or update. Set a field to null to remove it. Arrays are replaced entirely when provided.` : `Update the working memory with new information. Any data not included will be overwritten. Always pass data as string to the memory field. Never pass an object.`;
+  const usesMergeSemantics = Boolean(schema$2);
+  const description = schema$2 ? `Update the working memory with new information. Data is merged with existing memory - you only need to include fields you want to add or update. Set a field to null to remove it. Arrays are replaced entirely when provided.` : `Update the working memory with new information. Any data not included will be overwritten. Always pass data as string to the memory field. Never pass an object.`;
   return tools.createTool({
     id: "update-working-memory",
     description,
@@ -15206,26 +15213,28 @@ var updateWorkingMemoryTool = (memoryConfig) => {
             existingData = null;
           }
         }
-        if (inputData.memory === void 0 || inputData.memory === null) {
+        const memoryInput = inputData.memory;
+        if (memoryInput === void 0 || memoryInput === null) {
           return { success: true, message: "No memory data provided, existing memory unchanged." };
         }
         let newData;
-        if (typeof inputData.memory === "string") {
+        if (typeof memoryInput === "string") {
           try {
-            newData = JSON.parse(inputData.memory);
+            newData = JSON.parse(memoryInput);
           } catch (parseError) {
             const errorMessage = parseError instanceof Error ? parseError.message : String(parseError);
             throw new Error(
-              `Failed to parse working memory input as JSON: ${errorMessage}. Raw input: ${inputData.memory.length > 500 ? inputData.memory.slice(0, 500) + "..." : inputData.memory}`
+              `Failed to parse working memory input as JSON: ${errorMessage}. Raw input: ${memoryInput.length > 500 ? memoryInput.slice(0, 500) + "..." : memoryInput}`
             );
           }
         } else {
-          newData = inputData.memory;
+          newData = memoryInput;
         }
         const mergedData = deepMergeWorkingMemory(existingData, newData);
         workingMemory = JSON.stringify(mergedData);
       } else {
-        workingMemory = typeof inputData.memory === "string" ? inputData.memory : JSON.stringify(inputData.memory);
+        const memoryInput = inputData.memory;
+        workingMemory = typeof memoryInput === "string" ? memoryInput : JSON.stringify(memoryInput);
         const existingRaw = await memory.getWorkingMemory({
           threadId,
           resourceId,
@@ -15336,7 +15345,6 @@ var CHARS_PER_TOKEN = 4;
 var DEFAULT_MESSAGE_RANGE = { before: 1, after: 1 };
 var DEFAULT_TOP_K = 4;
 var VECTOR_DELETE_BATCH_SIZE = 100;
-var isZodObject = (v) => v instanceof zod.ZodObject;
 var Memory = class extends memory.MastraMemory {
   constructor(config = {}) {
     super({ name: "Memory", ...config });
@@ -15383,6 +15391,7 @@ var Memory = class extends memory.MastraMemory {
     const config = this.getMergedThreadConfig(threadConfig || {});
     if (resourceId) await this.validateThreadIsOwnedByResource(threadId, resourceId, config);
     const perPage = perPageArg !== void 0 ? perPageArg : config.lastMessages;
+    const historyDisabledByConfig = config.lastMessages === false && perPageArg === void 0;
     const shouldGetNewestAndReverse = !orderBy && perPage !== false;
     const effectiveOrderBy = shouldGetNewestAndReverse ? { field: "createdAt", direction: "DESC" } : orderBy;
     const vectorResults = [];
@@ -15393,7 +15402,8 @@ var Memory = class extends memory.MastraMemory {
       orderBy: effectiveOrderBy,
       hasWorkingMemorySchema: Boolean(config.workingMemory?.schema),
       workingMemoryEnabled: config.workingMemory?.enabled,
-      semanticRecallEnabled: Boolean(config.semanticRecall)
+      semanticRecallEnabled: Boolean(config.semanticRecall),
+      historyDisabledByConfig
     });
     const defaultRange = DEFAULT_MESSAGE_RANGE;
     const defaultTopK = DEFAULT_TOP_K;
@@ -15411,6 +15421,9 @@ var Memory = class extends memory.MastraMemory {
       );
     }
     let usage;
+    if (historyDisabledByConfig && (!config.semanticRecall || !vectorSearchString || !this.vector)) {
+      return { messages: [], usage: void 0, total: 0, page: page ?? 0, perPage: 0, hasMore: false };
+    }
     if (config?.semanticRecall && vectorSearchString && this.vector) {
       const result = await this.embedMessageContent(vectorSearchString);
       usage = result.usage;
@@ -15439,10 +15452,11 @@ var Memory = class extends memory.MastraMemory {
       );
     }
     const memoryStore = await this.getMemoryStore();
+    const effectivePerPage = historyDisabledByConfig ? 0 : perPage;
     const paginatedResult = await memoryStore.listMessages({
       threadId,
       resourceId,
-      perPage,
+      perPage: effectivePerPage,
       page,
       orderBy: effectiveOrderBy,
       filter: filter3,
@@ -15868,7 +15882,10 @@ ${workingMemory}`;
         return part;
       });
       if (newMessage.content.parts.length === 0) {
-        return null;
+        const hasContentText = typeof newMessage.content.content === "string" && newMessage.content.content.trim().length > 0;
+        if (!hasContentText) {
+          return null;
+        }
       }
     }
     return newMessage;
@@ -15923,12 +15940,13 @@ ${workingMemory}`;
     }
     if (config.workingMemory?.schema) {
       try {
-        const schema = config.workingMemory.schema;
+        const schema$1 = config.workingMemory.schema;
         let convertedSchema;
-        if (isZodObject(schema)) {
-          convertedSchema = zodToJson.zodToJsonSchema(schema);
+        if (schema.isStandardSchemaWithJSON(schema$1)) {
+          convertedSchema = schema$1["~standard"].jsonSchema.output({ target: "draft-07" });
         } else {
-          convertedSchema = schema;
+          const standardSchema2 = schema.toStandardSchema(schema$1);
+          convertedSchema = standardSchema2["~standard"].jsonSchema.output({ target: "draft-07" });
         }
         return { format: "json", content: JSON.stringify(convertedSchema) };
       } catch (error) {
@@ -16665,7 +16683,12 @@ Notes:
         "Observational memory async buffering is enabled by default but the installed version of @mastra/core does not support it. Either upgrade @mastra/core, @mastra/memory, and your storage adapter (@mastra/libsql, @mastra/pg, or @mastra/mongodb) to the latest version, or explicitly disable async buffering by setting `observation: { bufferTokens: false }` in your observationalMemory config."
       );
     }
-    const { ObservationalMemory } = await import('./observational-memory-AHVELJX4.cjs');
+    if (!features.coreFeatures.has("request-response-id-rotation")) {
+      throw new Error(
+        "Observational memory requires @mastra/core support for request-response-id-rotation. Please bump @mastra/core to a newer version."
+      );
+    }
+    const { ObservationalMemory } = await import('./observational-memory-C5LO7RBR.cjs');
     return new ObservationalMemory({
       storage: memoryStore,
       scope: omConfig.scope,