@mastra/libsql 1.15.1-alpha.0 → 1.16.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @mastra/libsql
 
+## 1.16.0-alpha.0
+
+### Minor Changes
+
+- Added `LibSQLVector.close()` to release the underlying libsql client. For local file databases it checkpoints the WAL and switches back to `journal_mode=DELETE` before closing (mirroring `LibSQLStore.close()`), so the `-wal`/`-shm` sidecar files and OS handles are released promptly. Safe to call more than once. ([#19059](https://github.com/mastra-ai/mastra/pull/19059))
+
+### Patch Changes
+
+- Updated dependencies [[`e955965`](https://github.com/mastra-ai/mastra/commit/e955965dce575a903e37cf054d28ea99aa48785e), [`860ef7e`](https://github.com/mastra-ai/mastra/commit/860ef7e77d92b63469cbe5857aa1e626197e43e9), [`17e818c`](https://github.com/mastra-ai/mastra/commit/17e818c51a958ba90641b1a959dc38faf8c034e9), [`4451dfe`](https://github.com/mastra-ai/mastra/commit/4451dfe857428e7abcc0261a507a2e186dae6d47), [`1d39058`](https://github.com/mastra-ai/mastra/commit/1d39058e548efd691799985d5c8af2737f1c3bd2)]:
+  - @mastra/core@1.51.0-alpha.2
+
+## 1.15.1
+
+### Patch Changes
+
+- Update `@mastra/core` peer dependency for the unified schedules API ([#18874](https://github.com/mastra-ai/mastra/pull/18874))
+
+- Schedule rows persisted with the legacy `target.type: 'heartbeat'` are now normalized to `target.type: 'agent'` when read, so existing agent schedules keep firing after the heartbeats-to-schedules rename in `@mastra/core`. ([#18874](https://github.com/mastra-ai/mastra/pull/18874))
+
+- Updated dependencies [[`b291760`](https://github.com/mastra-ai/mastra/commit/b291760df9d6c7e4fc72606c8f0a4af2cf6e946c), [`3ffb8b7`](https://github.com/mastra-ai/mastra/commit/3ffb8b720e90f5e6977129ec1f6707d43c2bebe0), [`6ef59fe`](https://github.com/mastra-ai/mastra/commit/6ef59fef1da52ed8da5fbb2a892c71cf4fb6c739), [`4039488`](https://github.com/mastra-ai/mastra/commit/403948898af7293198d9e8b3e7fb47f623c78b94), [`29b7ea6`](https://github.com/mastra-ai/mastra/commit/29b7ea64e72b5523d5bdcbd34ee03d2b854d54e1), [`b2c9d70`](https://github.com/mastra-ai/mastra/commit/b2c9d70757207fb01a9069549e69b6f0d73a6636), [`a51c63d`](https://github.com/mastra-ai/mastra/commit/a51c63d8ee639e4daeba2a0be093efa6a1b5e52f), [`252f63d`](https://github.com/mastra-ai/mastra/commit/252f63d8fec723955adb2202be2f01a75ad0e69c), [`5ea76a7`](https://github.com/mastra-ai/mastra/commit/5ea76a723d966c72da9aa3ab30ae20276e049765), [`6445560`](https://github.com/mastra-ai/mastra/commit/6445560327045d20b239585fc63fed72e9ce36ec), [`e2b9f33`](https://github.com/mastra-ai/mastra/commit/e2b9f33456fd638eca555f9466c6519d8d049666), [`10959d5`](https://github.com/mastra-ai/mastra/commit/10959d509d824f682d40ff96e05ee044aec3b0e5), [`c547a77`](https://github.com/mastra-ai/mastra/commit/c547a7729bdf64dfc2df29c965046c0712a18f10), [`a0085fa`](https://github.com/mastra-ai/mastra/commit/a0085fa0934e52c37c8c8b3d75a6bb5cd199af36), [`a2ba369`](https://github.com/mastra-ai/mastra/commit/a2ba369e796dfab610f41c6875965b488272fa55), [`ffc3c17`](https://github.com/mastra-ai/mastra/commit/ffc3c17274ea17c11aa6f73d3140649cd7fc8abc), [`81542c1`](https://github.com/mastra-ai/mastra/commit/81542c1835c35bc32f2ce4fa9136ee11993cd299), [`3908e53`](https://github.com/mastra-ai/mastra/commit/3908e53ce04bbea04f5e0c097d7aa298c35fabee), [`cb24ce7`](https://github.com/mastra-ai/mastra/commit/cb24ce76bd16ca88eb6a963f6277f8780e703029), [`02705fd`](https://github.com/mastra-ai/mastra/commit/02705fd2f5a9062210d64ea061adeeb10dc9452e), [`ae51e81`](https://github.com/mastra-ai/mastra/commit/ae51e818825582d42500338dfc1929a082eff0ba), [`6f304ef`](https://github.com/mastra-ai/mastra/commit/6f304ef319e99725e884bdb8d3193c001b6e5964), [`5f9858f`](https://github.com/mastra-ai/mastra/commit/5f9858f791f1137ca7d52d23559fb4568f7a9026)]:
+  - @mastra/core@1.50.0
+
 ## 1.15.1-alpha.0
 
 ### Patch Changes

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-libsql
 description: Documentation for @mastra/libsql. Use when working with @mastra/libsql APIs, configuration, or implementation.
 metadata:
   package: "@mastra/libsql"
-  version: "1.15.1-alpha.0"
+  version: "1.16.0-alpha.0"
 ---
 
 ## When to use
@@ -25,9 +25,9 @@ Read the individual reference documents for detailed explanations and code examp
 - [Multi-user threads](references/docs-memory-multi-user-threads.md) - Share one Mastra thread between multiple users by carrying speaker identity in the message body.
 - [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.
-- [Storage](references/docs-memory-storage.md) - Configure storage for Mastra to persist conversations and other runtime state.
 - [Working memory](references/docs-memory-working-memory.md) - Learn how to configure working memory in Mastra to store persistent user data, preferences.
 - [Retrieval, semantic search, reranking](references/docs-rag-retrieval.md) - Guide on retrieval processes in Mastra's RAG systems, including semantic search, filtering, and re-ranking.
+- [Storage overview](references/docs-storage-overview.md) - Configure storage for Mastra to persist runtime state across agents, workflows, observability, evals, schedules, and memory.
 - [Snapshots](references/docs-workflows-snapshots.md) - Learn how to save and resume workflow execution state with snapshots in Mastra
 
 ### Guides
@@ -39,6 +39,8 @@ Read the individual reference documents for detailed explanations and code examp
 - [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: Mastra class](references/reference-core-mastra-class.md) - Documentation for the `Mastra` class in Mastra, the core entry point for managing agents, workflows, MCP servers, and server endpoints.
+- [Memory](references/reference-file-based-agents-memory.md) - Give a file-based agent persistent memory with a memory.ts module.
+- [Storage](references/reference-file-based-agents-storage.md) - Set the default Mastra store by file convention with storage.ts.
 - [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: Composite storage](references/reference-storage-composite.md) - Documentation for combining multiple storage backends in Mastra.
 - [Reference: DynamoDB storage](references/reference-storage-dynamodb.md) - Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.15.1-alpha.0",
+  "version": "1.16.0-alpha.0",
   "package": "@mastra/libsql",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-agent-builder-overview.md

@@ -4,10 +4,10 @@
 
 > **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
 
-[YouTube video player](https://www.youtube-nocookie.com/embed/AbdgIu4Z07I)
-
 The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
 
+> **📹 Watch:** Watch [Mastra Agent Builder overview](https://www.youtube.com/watch?v=AbdgIu4Z07I) to see how teams create and configure agents from the UI.
+
 - [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.
 - [**Model policy**](https://mastra.ai/docs/agent-builder/model-policy): Restrict which providers and models the Builder exposes, and pin a default.
 - [**Memory**](https://mastra.ai/docs/agent-builder/memory): Configure the default memory shape for every Builder-created agent.
@@ -108,4 +108,5 @@ Omitting the `builder` field has the same effect.
 
 - [Configuration](https://mastra.ai/docs/agent-builder/configuration): Toggle Builder surfaces and pin defaults for new agents.
 - [Access control](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder with authentication and role-based access control.
-- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Replace local development primitives with production-ready storage, filesystems, and sandboxes.
+- [Deploying](https://mastra.ai/docs/agent-builder/deploying): Replace local development primitives with production-ready storage, filesystems, and sandboxes.
+- 📹 [Mastra Agent Builder workshop](https://www.youtube.com/watch?v=p2p_wb-rUPg\&t=666s)

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

@@ -48,7 +48,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-> **Note:** Agent approval uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/memory/storage) on your Mastra instance or you'll see a "snapshot not found" error.
+> **Note:** Agent approval uses snapshots to capture request state. Configure a [storage provider](https://mastra.ai/docs/storage/overview) on your Mastra instance or you'll see a "snapshot not found" error.
 >
 > Snapshots for agent runs are minimal resume artifacts: they hold only what's needed to resume the suspended run and are deleted once the run finishes. Use [tracing](https://mastra.ai/docs/observability/overview) for the execution record and [memory](https://mastra.ai/docs/memory/overview) for the conversation history.
 
@@ -110,6 +110,29 @@ A tool can also pause _during_ its `execute` function by calling `suspend()`. Th
 
 The stream emits a `tool-call-suspended` chunk with a custom payload defined by the tool's `suspendSchema`. You resume by calling `resumeStream()` with data matching the tool's `resumeSchema`.
 
+```typescript
+const weatherTool = createTool({
+  id: 'get-weather',
+  inputSchema: z.object({
+    location: z.string().optional(),
+  }),
+  suspendSchema: z.object({
+    question: z.string(),
+  }),
+  resumeSchema: z.object({
+    location: z.string(),
+  }),
+  execute: async ({ location }, context) => {
+    if (!location) {
+      return await context?.agent?.suspend({
+        question: 'Which city would you like the weather for?',
+      })
+    }
+    return await fetchWeather(location)
+  },
+})
+```
+
 > **Note:** `suspend()` doesn't throw — return immediately after calling it (e.g. `return await suspend({ ... })`). Code after `await suspend(...)` still runs before the tool pauses.
 
 ## Tool approval with `generate()`
@@ -397,7 +420,7 @@ Each returned run includes the suspended tool calls (`toolCallId`, `toolName`, `
 
 The same discovery is available over HTTP as `GET /agents/:agentId/suspended-runs` and in the client SDK as [`agent.listSuspendedRuns()`](https://mastra.ai/reference/client-js/agents), so browser-based approval UIs can rediscover pending runs directly.
 
-> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/memory/storage). The default in-memory store loses snapshots when the process exits.
+> **Note:** Suspended runs only survive restarts when your Mastra instance is configured with a persistent [storage provider](https://mastra.ai/docs/storage/overview). The default in-memory store loses snapshots when the process exits.
 
 ## Tool approval: Supervisor agents
 

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

@@ -95,7 +95,7 @@ console.log(final?.summary)
 
 When a primitive requires approval, the stream emits an `agent-execution-approval` or `tool-execution-approval` chunk. Use `approveNetworkToolCall()` or `declineNetworkToolCall()` to respond.
 
-Network approval uses snapshots to capture execution state. Ensure a [storage provider](https://mastra.ai/docs/memory/storage) is enabled in your Mastra instance.
+Network approval uses snapshots to capture execution state. Ensure a [storage provider](https://mastra.ai/docs/storage/overview) is enabled in your Mastra instance.
 
 ```typescript
 const stream = await routingAgent.network('Perform some sensitive action', {

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

@@ -309,6 +309,73 @@ const agent = new Agent({
 
 Both scenarios are safe - guardrails prevent inappropriate content from being persisted to memory
 
+## Handling large attachments
+
+Some storage providers enforce record size limits that base64-encoded file attachments can exceed:
+
+| Provider                                                           | Record size limit |
+| ------------------------------------------------------------------ | ----------------- |
+| [DynamoDB](https://mastra.ai/reference/storage/dynamodb)           | 400 KB            |
+| [Convex](https://mastra.ai/reference/storage/convex)               | 1 MiB             |
+| [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1) | 1 MiB             |
+
+PostgreSQL, MongoDB, and libSQL have higher limits and are usually unaffected.
+
+Use an input processor to upload attachments to external storage, then replace them with URL references before messages are persisted.
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+import type { MastraDBMessage } from '@mastra/core/memory'
+
+export class AttachmentUploader implements Processor {
+  id = 'attachment-uploader'
+
+  async processInput({ messages }: { messages: MastraDBMessage[] }) {
+    return Promise.all(messages.map(message => this.processMessage(message)))
+  }
+
+  async processMessage(message: MastraDBMessage) {
+    const attachments = message.content.experimental_attachments
+    if (!attachments?.length) return message
+
+    const uploaded = await Promise.all(
+      attachments.map(async attachment => {
+        if (!attachment.url?.startsWith('data:')) return attachment
+
+        const url = await this.upload(attachment.url, attachment.contentType)
+        return { ...attachment, url }
+      }),
+    )
+
+    return { ...message, content: { ...message.content, experimental_attachments: uploaded } }
+  }
+
+  async upload(dataUri: string, contentType?: string): Promise<string> {
+    const base64 = dataUri.split(',')[1]
+    const buffer = Buffer.from(base64, 'base64')
+
+    throw new Error('Implement upload() with your storage provider')
+  }
+}
+```
+
+Use the processor with your agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { AttachmentUploader } from '../processors/attachment-uploader'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({ lastMessages: 10 }),
+  inputProcessors: [new AttachmentUploader()],
+})
+```
+
 ## Related documentation
 
 - [Processors](https://mastra.ai/docs/agents/processors): General processor concepts and custom processor creation

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

@@ -6,7 +6,7 @@ Message history is the most basic and important form of memory. It gives the LLM
 
 You can also retrieve message history to display past conversations in your UI.
 
-> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](https://mastra.ai/docs/memory/storage) for more detail.
+> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
 
 > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
 >
@@ -14,9 +14,18 @@ You can also retrieve message history to display past conversations in your UI.
 >
 > For an AI SDK example, see [Using Mastra Memory](https://mastra.ai/guides/build-your-ui/ai-sdk-ui).
 
+## Threads and resources
+
+Mastra organizes conversations using two identifiers:
+
+- **Thread**: A conversation session containing a sequence of messages.
+- **Resource**: The entity that owns the thread, such as a user, organization, project, or another domain entity in your application.
+
+Studio automatically generates a thread and resource ID for you. When calling `stream()` or `generate()` yourself, provide these identifiers explicitly.
+
 ## Getting started
 
-Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/memory/storage) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
+Install the Mastra memory module along with a [storage adapter](https://mastra.ai/docs/storage/overview) for your database. The examples below use `@mastra/libsql`, which stores data locally in a `mastra.db` file.
 
 **npm**:
 
@@ -113,6 +122,51 @@ You can use this history in two ways:
 
 > **Tip:** When memory is enabled, [Studio](https://mastra.ai/docs/studio/overview) uses message history to display past conversations in the chat sidebar.
 
+## Thread title generation
+
+Mastra can automatically generate descriptive thread titles based on the user's first message when `generateTitle` is enabled. Use this option when you build a chat interface that renders conversation titles in a thread list or sidebar.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    options: {
+      generateTitle: true,
+    },
+  }),
+})
+```
+
+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`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    options: {
+      generateTitle: {
+        model: 'openai/gpt-5-mini',
+        instructions: 'Generate a one-word title.',
+      },
+    },
+  }),
+})
+```
+
 ## Accessing memory
 
 To access memory functions for querying, cloning, or deleting threads and messages, call `getMemory()` on an agent:

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

@@ -13,7 +13,9 @@ Mastra agents can be configured to store [message history](https://mastra.ai/doc
 
 If the combined memory exceeds the model's context limit, [memory processors](https://mastra.ai/docs/memory/memory-processors) can filter, trim, or prioritize content so the most relevant information is preserved.
 
-Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/memory/storage).
+Memory results will be stored in one or more of your configured [storage providers](https://mastra.ai/docs/storage/overview).
+
+> **📹 Watch:** Watch [Mastra memory concepts](https://www.youtube.com/watch?v=18iIHQtIPmc) for a conceptual overview of the memory layers agents can use.
 
 ## When to use memory
 
@@ -75,7 +77,7 @@ Use memory when your agent needs to maintain multi-turn conversations that refer
    bun add @mastra/libsql@latest
    ```
 
-   > **Note:** For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/memory/storage) documentation.
+   > **Note:** For more details on available providers and how storage works in Mastra, visit the [storage](https://mastra.ai/docs/storage/overview) documentation.
 
 3. Add the storage provider to your main Mastra instance to enable memory across all configured agents.
 
@@ -178,7 +180,7 @@ Each delegation creates a fresh `threadId` and a deterministic `resourceId` for
 - **Resource ID**: Derived as `{parentResourceId}-{agentName}`. Because the resource ID is stable across delegations, resource-scoped memory persists between calls. A subagent remembers facts from previous delegations by the same user.
 - **Memory instance**: If a subagent has no memory configured, it inherits the supervisor's `Memory` instance, including all of its options. If the subagent defines its own, that takes precedence.
 
-> **Note:** Title generation (`generateTitle`) is a top-level thread concern and is **not** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
+> **Note:** Title generation (`generateTitle`) is a top-level thread concern and **isn't** applied to inherited subagent threads. Because each delegation creates an ephemeral thread that no one sees, running title generation for it would waste an LLM call per delegation. To generate titles for a subagent's own threads, give that subagent its own memory configuration.
 
 The supervisor forwards its conversation context to the subagent so it has enough background to complete the task. Only the delegation prompt and the subagent's response are saved — the full parent conversation isn't stored. You can control which messages reach the subagent with the [`messageFilter`](https://mastra.ai/docs/agents/supervisor-agents) callback.
 

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

@@ -4,7 +4,7 @@
 
 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)
+> **📹 Watch:** Watch [Mastra semantic recall](https://www.youtube.com/watch?v=UVZtK8cK8xQ\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents retrieve relevant messages from past conversations.
 
 ## How semantic recall works
 
@@ -22,6 +22,8 @@ After getting a response from the LLM, all new messages (user, assistant, and to
 
 Semantic recall is disabled by default. To enable it, set `semanticRecall: true` in `options` and provide a `vector` store and `embedder`:
 
+**LibSQL**:
+
 ```typescript
 import { Agent } from '@mastra/core/agent'
 import { Memory } from '@mastra/memory'
@@ -50,6 +52,38 @@ const agent = new Agent({
 })
 ```
 
+**MongoDB**:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { MongoDBStore, MongoDBVector } from '@mastra/mongodb'
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+
+const agent = new Agent({
+  id: 'support-agent',
+  name: 'SupportAgent',
+  instructions: 'You are a helpful support agent.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    storage: new MongoDBStore({
+      id: 'agent-storage',
+      uri: process.env.MONGODB_URI,
+      dbName: process.env.MONGODB_DB_NAME,
+    }),
+    vector: new MongoDBVector({
+      id: 'agent-vector',
+      uri: process.env.MONGODB_URI,
+      dbName: process.env.MONGODB_DB_NAME,
+    }),
+    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
+    options: {
+      semanticRecall: true,
+    },
+  }),
+})
+```
+
 ## 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 recency, use `recall()` with a `vectorSearchString`:
@@ -146,7 +180,7 @@ const agent = new Agent({
 })
 ```
 
-> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, and Upstash storage adapters.
+> **Note:** `scope: 'resource'` is supported by the LibSQL, PostgreSQL, MongoDB, and Upstash storage adapters.
 
 ### Metadata filtering
 

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

@@ -10,6 +10,8 @@ This is useful for maintaining ongoing state that's always relevant and should a
 
 If you use [Observational Memory](https://mastra.ai/docs/memory/observational-memory), `observationalMemory.observation.manageWorkingMemory` lets OM update working memory for the agent.
 
+> **📹 Watch:** Watch [Mastra working memory](https://www.youtube.com/watch?v=UMy_JHLf1n8\&pp=ygUVbWFzdHJhIHdvcmtpbmcgbWVtb3J5) to see how agents keep persistent user context available across interactions.
+
 Working memory can persist at two different scopes:
 
 - **Resource-scoped** (default): Memory persists across all conversation threads for the same user
@@ -43,9 +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:
-
-[YouTube video player](https://www.youtube-nocookie.com/embed/UMy_JHLf1n8)
+Working memory is a block of Markdown text that the agent is able to update over time to store continuously relevant information.
 
 ## Memory persistence scopes
 

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

@@ -0,0 +1,214 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Storage overview
+
+Storage is the persistence layer for the Mastra runtime. It keeps memory, workflow state, observability data, eval results, schedules, and long-running agent state available after a process restarts.
+
+Storage powers:
+
+- [Memory](https://mastra.ai/docs/memory/overview): Message history, threads, resources, and working memory.
+- [Workflows](https://mastra.ai/docs/workflows/overview): Durable snapshots for suspended and resumed workflow runs.
+- [Observability](https://mastra.ai/docs/observability/overview): Traces, spans, metrics, logs, and feedback.
+- [Evals](https://mastra.ai/docs/evals/overview): Scores, datasets, experiments, and evaluation results.
+- [Long-running agents](https://mastra.ai/docs/long-running-agents/durable-agents): Background tasks, schedules, goals, and thread state.
+
+## 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.
+
+Use storage when your application needs any of these behaviors:
+
+- Agents remember past messages or user facts.
+- Workflows suspend and resume after a restart.
+- Traces, metrics, logs, scores, or feedback stay available for analysis.
+- Schedules and background tasks continue across deployments.
+- Multiple runtime processes read and write the same state.
+
+## How storage works
+
+Mastra storage is organized into **domains**. A domain owns one type of runtime data, and a storage adapter implements one or more domains.
+
+| Domain            | What it stores                                                              |
+| ----------------- | --------------------------------------------------------------------------- |
+| `memory`          | Threads, messages, resources, working memory, and other agent memory state. |
+| `workflows`       | Workflow snapshots used to suspend and resume runs.                         |
+| `observability`   | Traces, spans, metrics, logs, and feedback.                                 |
+| `scores`          | Eval score records.                                                         |
+| `datasets`        | Dataset records and dataset items used by evals and experiments.            |
+| `experiments`     | Experiment runs and per-item experiment results.                            |
+| `backgroundTasks` | Background task records and execution state.                                |
+| `schedules`       | Schedule definitions and trigger history.                                   |
+| `threadState`     | Durable task, goal, and thread state.                                       |
+
+Adapter support varies by domain. For the full domain list and built-in schemas, see the [storage overview reference](https://mastra.ai/reference/storage/overview).
+
+## Choose a backend by data shape
+
+Different domains write and query different kinds of data. Pick a backend based on the domain's access pattern:
+
+- `memory`: Reads and writes rows during every remembered agent call. Use a transactional database such as libSQL, PostgreSQL, or MongoDB.
+- `observability`: Writes high-volume telemetry and often queries aggregations. Use a dedicated observability store or an online analytical processing (OLAP) backend such as ClickHouse or DuckDB.
+- `workflows`: Stores durable snapshots that must be available when a run resumes. Use a reliable persistent database.
+- `scores`, `datasets`, and `experiments`: Store lower-frequency evaluation data that's often read later for analysis.
+- `schedules`: Stores schedule definitions and fire history. Use an adapter that implements the schedules domain.
+
+When domains have different operational needs, use [composite storage](#composite-storage) to route each domain to the right backend.
+
+## Get started locally
+
+For local development, use libSQL with a file-backed database. It doesn't require a separate database server and persists state between restarts.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'mastra-storage',
+    url: 'file:./mastra.db',
+  }),
+})
+```
+
+> **Sharing the database with Studio:** When running `mastra dev` alongside your application, use an absolute path so both processes access the same database:
+>
+> ```typescript
+> url: 'file:/absolute/path/to/your/project/mastra.db'
+> ```
+>
+> Relative paths like `file:./mastra.db` resolve based on each process's working directory, which may differ.
+
+Mastra initializes the required storage structures on first use.
+
+## Configure for production
+
+For production, use a persistent managed database. PostgreSQL is a good default for most teams because it works well for transactional runtime state and is widely available as a managed service.
+
+Production guidance:
+
+- Use a managed database with backups, monitoring, and connection pooling.
+- Keep local file databases such as `file:./mastra.db` out of multi-process production deployments.
+- Route high-volume domains, especially `observability`, to a dedicated backend with [composite storage](#composite-storage).
+- Configure [retention](https://mastra.ai/reference/storage/retention) policies on the storage adapter or composite store, then call `storage.prune()` from a scheduler or maintenance job.
+- Choose providers based on the domains your application uses. For example, schedules require an adapter that implements the `schedules` domain.
+
+## Configuration scope
+
+Storage can be configured at the Mastra instance level or at the agent level.
+
+### Instance-level storage
+
+Instance-level storage is shared by agents, workflows, observability, evals, schedules, and other runtime features registered on the same Mastra instance.
+
+**PostgreSQL**:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { PostgresStore } from '@mastra/pg'
+
+export const mastra = new Mastra({
+  storage: new PostgresStore({
+    id: 'mastra-storage',
+    connectionString: process.env.DATABASE_URL,
+  }),
+})
+```
+
+**MongoDB**:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MongoDBStore } from '@mastra/mongodb'
+
+export const mastra = new Mastra({
+  storage: new MongoDBStore({
+    id: 'mastra-storage',
+    uri: process.env.MONGODB_URI,
+    dbName: process.env.MONGODB_DB_NAME,
+  }),
+})
+```
+
+Use instance-level storage when most runtime domains can share the same database.
+
+### Agent-level storage
+
+Agent-level storage is configured on a `Memory` instance. It overrides instance-level storage for that agent's memory data only.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { PostgresStore } from '@mastra/pg'
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support agent',
+  instructions: 'Answer customer support questions.',
+  model: 'openai/gpt-5.5',
+  memory: new Memory({
+    storage: new PostgresStore({
+      id: 'support-agent-storage',
+      connectionString: process.env.SUPPORT_AGENT_DATABASE_URL,
+    }),
+  }),
+})
+```
+
+Use agent-level storage when an agent needs an isolated memory boundary or a different memory backend.
+
+## Composite storage
+
+[`MastraCompositeStore`](https://mastra.ai/reference/storage/composite) routes domains to different backends. Use it when one database isn't the right fit for every domain.
+
+The following example uses libSQL as the default store and routes workflow state to PostgreSQL:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraCompositeStore } from '@mastra/core/storage'
+import { LibSQLStore } from '@mastra/libsql'
+import { WorkflowsPG } from '@mastra/pg'
+
+export const mastra = new Mastra({
+  storage: new MastraCompositeStore({
+    id: 'composite-storage',
+    default: new LibSQLStore({
+      id: 'default-storage',
+      url: 'file:./mastra.db',
+    }),
+    domains: {
+      workflows: new WorkflowsPG({
+        connectionString: process.env.DATABASE_URL,
+      }),
+    },
+  }),
+})
+```
+
+You can also route `observability` to a dedicated analytics backend. See [observability storage](https://mastra.ai/docs/observability/storage) for an observability-specific example.
+
+## Supported providers
+
+Each provider page includes installation instructions, configuration parameters, and usage examples:
+
+- [libSQL](https://mastra.ai/reference/storage/libsql)
+- [PostgreSQL](https://mastra.ai/reference/storage/postgresql)
+- [MongoDB](https://mastra.ai/reference/storage/mongodb)
+- [Upstash](https://mastra.ai/reference/storage/upstash)
+- [Redis](https://mastra.ai/reference/storage/redis)
+- [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
+- [Cloudflare KV & Durable Objects](https://mastra.ai/reference/storage/cloudflare)
+- [Convex](https://mastra.ai/reference/storage/convex)
+- [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
+- [LanceDB](https://mastra.ai/reference/storage/lance)
+- [Microsoft SQL Server](https://mastra.ai/reference/storage/mssql)
+- [Google Cloud Spanner](https://mastra.ai/reference/storage/spanner)
+
+> **Tip:** libSQL is the fastest path for local development because it doesn't require running a separate database server.
+
+## Next steps
+
+- [Composite storage](https://mastra.ai/reference/storage/composite)
+- [Storage retention](https://mastra.ai/reference/storage/retention)
+- [Storage schemas](https://mastra.ai/reference/storage/overview)
+- [Memory](https://mastra.ai/docs/memory/overview)
+- [Observability storage](https://mastra.ai/docs/observability/storage)

package/dist/docs/references/docs-workflows-snapshots.md

@@ -145,7 +145,7 @@ export const mastra = new Mastra({
 - [Upstash Storage](https://mastra.ai/reference/storage/upstash)
 - [Cloudflare D1](https://mastra.ai/reference/storage/cloudflare-d1)
 - [DynamoDB](https://mastra.ai/reference/storage/dynamodb)
-- [More storage providers](https://mastra.ai/docs/memory/storage)
+- [More storage providers](https://mastra.ai/docs/storage/overview)
 
 ## Best practices