@mastra/mcp-docs-server 1.2.7-alpha.1 → 1.2.7-alpha.12

package/.docs/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/.docs/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/.docs/docs/observability/integrations/exporters/mastra-platform.md

@@ -126,9 +126,7 @@ If you prefer, rely entirely on environment variables:
 new MastraPlatformExporter()
 ```
 
-With `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `MastraPlatformExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`, it sends data to that collector instead.
-
-> **Note:** Visit [MastraPlatformExporter reference](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for the full list of configuration options.
+With `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` set, `MastraPlatformExporter` sends data to the Mastra platform project you configured. If you also set `MASTRA_PLATFORM_OBSERVABILITY_ENDPOINT`, it sends data to that collector instead. Visit [MastraPlatformExporter reference](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for the full list of configuration options.
 
 ## Recommended configuration
 

package/.docs/docs/observability/integrations/exporters/mastra-storage.md

@@ -243,4 +243,4 @@ new MastraStorageExporter({
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview)
 - [MastraPlatformExporter](https://mastra.ai/docs/observability/integrations/exporters/mastra-platform)
 - [Composite Storage](https://mastra.ai/reference/storage/composite): Combine multiple storage providers
-- [Storage Configuration](https://mastra.ai/docs/memory/storage)
+- [Storage Configuration](https://mastra.ai/docs/storage/overview)

package/.docs/docs/observability/logging.md

@@ -22,7 +22,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** Visit [PinoLogger](https://mastra.ai/reference/logging/pino-logger) for all available configuration options.
+Visit [PinoLogger](https://mastra.ai/reference/logging/pino-logger) for all available configuration options.
 
 ## Logging to observability storage
 

package/.docs/docs/observability/tracing/overview.md

@@ -325,7 +325,7 @@ const result = await agent.generate([{ role: 'user', content: 'Sensitive operati
 })
 ```
 
-> **Tip:** For more granular control over sensitive data, consider using the [Sensitive Data Filter](https://mastra.ai/docs/observability/integrations/processors/sensitive-data-filter) processor, which can redact specific fields (like passwords, tokens, and keys) while preserving the rest of the input/output.
+For more granular control over sensitive data, consider using the [Sensitive Data Filter](https://mastra.ai/docs/observability/integrations/processors/sensitive-data-filter) processor, which can redact specific fields (like passwords, tokens, and keys) while preserving the rest of the input/output.
 
 #### Child spans and metadata extraction
 

package/.docs/docs/rag/vector-databases.md

@@ -14,7 +14,7 @@ import { MongoDBVector } from '@mastra/mongodb'
 const store = new MongoDBVector({
   id: 'mongodb-vector',
   uri: process.env.MONGODB_URI,
-  dbName: process.env.MONGODB_DATABASE,
+  dbName: process.env.MONGODB_DB_NAME,
 })
 await store.createIndex({
   indexName: 'myCollection',
@@ -27,10 +27,14 @@ await store.upsert({
 })
 ```
 
-### Using MongoDB Atlas Vector search
+### Using MongoDB Atlas Vector Search
 
 For detailed setup instructions and best practices, see the [official MongoDB Atlas Vector Search documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/?utm_campaign=devrel\&utm_source=third-party-content\&utm_medium=cta\&utm_content=mastra-docs).
 
+### Using VoyageAI with MongoDB
+
+MongoDB works seamlessly with VoyageAI's embedding models, which are optimized for retrieval tasks. For complete examples and specialized models, see the [VoyageAI embeddings documentation](https://mastra.ai/models/embeddings) and [MongoDB vector reference](https://mastra.ai/reference/vectors/mongodb).
+
 **PgVector**:
 
 ```ts
@@ -359,6 +363,7 @@ The dimension size must match the output dimension of your chosen embedding mode
 
 - `OpenAI text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
 - `Cohere embed-multilingual-v3`: 1024 dimensions
+- `VoyageAI voyage-3.5`: 1024 dimensions (or custom: 256, 512, 1024, 2048)
 - `Google gemini-embedding-001`: 768 dimensions (or custom)
 
 > **Warning:** Index dimensions can't be changed after creation. To use a different model, delete and recreate the index with the new dimension size.

package/.docs/docs/server/auth/auth0.md

@@ -105,7 +105,7 @@ const auth0Provider = new MastraAuthAuth0({
 })
 ```
 
-> **Info:** Visit [MastraAuthAuth0](https://mastra.ai/reference/auth/auth0) for all available configuration options.
+Visit [MastraAuthAuth0](https://mastra.ai/reference/auth/auth0) for all available configuration options.
 
 ## Client-side setup
 

package/.docs/docs/server/auth/better-auth.md

@@ -87,7 +87,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** Visit [MastraAuthBetterAuth](https://mastra.ai/reference/auth/better-auth) for all available configuration options.
+Visit [MastraAuthBetterAuth](https://mastra.ai/reference/auth/better-auth) for all available configuration options.
 
 ## Custom authorization
 
@@ -180,7 +180,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 

package/.docs/docs/server/auth/clerk.md

@@ -88,7 +88,7 @@ export const useClerkAuth = () => {
 }
 ```
 
-> **Info:** Refer to the [Clerk documentation](https://clerk.com/docs) for more information.
+Refer to the [Clerk documentation](https://clerk.com/docs) for more information.
 
 ## Configuring `MastraClient`
 

package/.docs/docs/server/auth/firebase.md

@@ -118,7 +118,7 @@ const firebaseAuth = new MastraAuthFirebase({
 })
 ```
 
-> **Info:** Visit [MastraAuthFirebase](https://mastra.ai/reference/auth/firebase) for all available configuration options.
+Visit [MastraAuthFirebase](https://mastra.ai/reference/auth/firebase) for all available configuration options.
 
 ## Client-side setup
 

package/.docs/docs/server/auth/google.md

@@ -168,7 +168,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** Visit [MastraAuthGoogle](https://mastra.ai/reference/auth/google) for all available configuration options.
+Visit [MastraAuthGoogle](https://mastra.ai/reference/auth/google) for all available configuration options.
 
 ## Role mapping
 
@@ -242,7 +242,7 @@ export const createMastraClient = (idToken: string) => {
 }
 ```
 
-> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 
@@ -273,7 +273,7 @@ curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
 - **Workspace users are rejected**: Verify `GOOGLE_ALLOWED_DOMAINS` matches the Google ID token `hd` claim.
 - **Consumer Gmail accounts are rejected**: This is expected when `allowedDomains` is configured because Gmail accounts don't have a Workspace `hd` claim.
 - **RBAC returns default permissions**: No roles were resolved for the user. Verify the user email or custom `getUserKey`, Google group membership, and `roleMapping`. If the Directory API lookup fails, the provider throws an error instead of returning `_default`.
-- **Cookies are not sent cross-origin**: Set `credentials: "include"` in `MastraClient` and configure `server.cors` with your frontend origin and `credentials: true`.
+- **Cookies aren't sent cross-origin**: Set `credentials: "include"` in `MastraClient` and configure `server.cors` with your frontend origin and `credentials: true`.
 - **Session lost on restart**: Set `GOOGLE_COOKIE_PASSWORD` to a stable value of at least 32 characters. Without it, an auto-generated key is used in development and changes on each restart.
 
 ## Related

package/.docs/docs/server/auth/jwt.md

@@ -61,7 +61,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** Visit [MastraJwtAuth](https://mastra.ai/reference/auth/jwt) for all available configuration options.
+Visit [MastraJwtAuth](https://mastra.ai/reference/auth/jwt) for all available configuration options.
 
 Inside [Studio](https://mastra.ai/docs/studio/overview), go to **Settings** and under **Headers** select the **"Add Header"** button. Enter `Authorization` as the header name and `Bearer <your-jwt>` as the value.
 
@@ -80,7 +80,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 

package/.docs/docs/server/auth/okta.md

@@ -120,7 +120,7 @@ export const mastra = new Mastra({
 
 > **Note:** To link users between providers, store the Okta user ID in the other provider's user metadata. Mastra uses this ID to fetch groups from Okta.
 
-> **Info:** Visit [MastraAuthOkta](https://mastra.ai/reference/auth/okta) for all available configuration options.
+Visit [MastraAuthOkta](https://mastra.ai/reference/auth/okta) for all available configuration options.
 
 ## Role mapping
 
@@ -194,7 +194,7 @@ export const createMastraClient = (accessToken: string) => {
 }
 ```
 
-> **Info:** Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
+Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 
 ### Making authenticated requests
 

package/.docs/docs/server/auth/workos.md

@@ -149,7 +149,7 @@ const workosAuth = new AdminOnlyWorkosAuth({
 })
 ```
 
-> **Info:** Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
+Visit [MastraAuthWorkos](https://mastra.ai/reference/auth/workos) for all available configuration options.
 
 ## Client-side setup
 

package/.docs/docs/server/mastra-client.md

@@ -134,7 +134,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for more configuration options.
+Visit [MastraClient](https://mastra.ai/reference/client-js/mastra-client) for more configuration options.
 
 ## Credentials and session cookies
 

package/.docs/docs/server/mastra-server.md

@@ -32,7 +32,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** Visit the [configuration reference](https://mastra.ai/reference/configuration) for a full list of available server options.
+Visit the [configuration reference](https://mastra.ai/reference/configuration) for a full list of available server options.
 
 ## Deploy your server
 

package/.docs/docs/server/pubsub.md

@@ -116,7 +116,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Note:** Visit the [PubSub reference](https://mastra.ai/reference/pubsub/base) for the full delivery contract and the configuration options for each backend.
+Visit the [PubSub reference](https://mastra.ai/reference/pubsub/base) for the full delivery contract and the configuration options for each backend.
 
 ## Related
 

package/.docs/docs/server/request-context.md

@@ -82,7 +82,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** Visit [Middleware](https://mastra.ai/docs/server/middleware) for how to use server middleware.
+Visit [Middleware](https://mastra.ai/docs/server/middleware) for how to use server middleware.
 
 ## Studio
 
@@ -188,7 +188,7 @@ export const registryAgent = new Agent({
 })
 ```
 
-> **Info:** Visit [Agent](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
+Visit [Agent](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
 
 ## Accessing values from workflow steps
 
@@ -210,7 +210,7 @@ const stepOne = createStep({
 })
 ```
 
-> **Info:** Visit [createStep()](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
+Visit [createStep()](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
 
 ## Accessing values with tools
 
@@ -232,7 +232,7 @@ export const weatherTool = createTool({
 })
 ```
 
-> **Info:** Visit [createTool()](https://mastra.ai/reference/tools/create-tool) for a full list of configuration options.
+Visit [createTool()](https://mastra.ai/reference/tools/create-tool) for a full list of configuration options.
 
 ## Reserved keys
 

package/.docs/docs/server/server-adapters.md

@@ -303,7 +303,7 @@ app.listen(4111, () => {
 })
 ```
 
-> **Info:** See the [Express Adapter](https://mastra.ai/reference/server/express-adapter) documentation for full configuration options.
+See the [Express Adapter](https://mastra.ai/reference/server/express-adapter) documentation for full configuration options.
 
 **Hono**:
 
@@ -324,7 +324,7 @@ serve({ fetch: app.fetch, port: 4111 }, () => {
 })
 ```
 
-> **Info:** See the [Hono Adapter](https://mastra.ai/reference/server/hono-adapter) documentation for full configuration options.
+See the [Hono Adapter](https://mastra.ai/reference/server/hono-adapter) documentation for full configuration options.
 
 **Fastify**:
 
@@ -352,7 +352,7 @@ app.listen({ port }, () => {
 })
 ```
 
-> **Info:** See the [Fastify Adapter](https://mastra.ai/reference/server/fastify-adapter) documentation for full configuration options.
+See the [Fastify Adapter](https://mastra.ai/reference/server/fastify-adapter) documentation for full configuration options.
 
 **Koa**:
 
@@ -387,7 +387,7 @@ app.listen(port, () => {
 })
 ```
 
-> **Info:** See the [Koa Adapter](https://mastra.ai/reference/server/koa-adapter) documentation for full configuration options.
+See the [Koa Adapter](https://mastra.ai/reference/server/koa-adapter) documentation for full configuration options.
 
 **NestJS**:
 
@@ -418,7 +418,7 @@ async function bootstrap() {
 bootstrap()
 ```
 
-> **Info:** See the [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter) documentation for full configuration options.
+See the [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter) documentation for full configuration options.
 
 ## Initialization flow
 
@@ -460,7 +460,7 @@ You can add your own routes to the app alongside Mastra's routes.
 - When you want Mastra-managed auth and route metadata such as `requiresAuth`, prefer `registerApiRoute()`.
 - When you mount routes directly on the framework app, use the adapter's exported `createAuthMiddleware()` helper if those routes need Mastra auth.
 
-> **Info:** Visit "Adding custom routes" for [Express](https://mastra.ai/reference/server/express-adapter) and [Hono](https://mastra.ai/reference/server/hono-adapter) for more information.
+Visit "Adding custom routes" for [Express](https://mastra.ai/reference/server/express-adapter) and [Hono](https://mastra.ai/reference/server/hono-adapter) for more information.
 
 ## Route prefixes
 
@@ -513,7 +513,7 @@ const server = new MastraServer({
 })
 ```
 
-> **Info:** See [MastraServer](https://mastra.ai/reference/server/mastra-server) for full configuration options.
+See [MastraServer](https://mastra.ai/reference/server/mastra-server) for full configuration options.
 
 ## Per-route auth overrides
 
@@ -540,7 +540,7 @@ const server = new MastraServer({
 })
 ```
 
-> **Info:** See [MastraServer](https://mastra.ai/reference/server/mastra-server) for full configuration options.
+See [MastraServer](https://mastra.ai/reference/server/mastra-server) for full configuration options.
 
 ## Accessing the app
 

package/.docs/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/.docs/docs/studio/auth.md

@@ -35,9 +35,7 @@ export const mastra = new Mastra({
 })
 ```
 
-Once configured, Studio shows a login screen and requires authentication for all API requests.
-
-> **Note:** Visit the [Auth docs](https://mastra.ai/docs/server/auth) for a full list of supported providers.
+Once configured, Studio shows a login screen and requires authentication for all API requests. Visit the [Auth docs](https://mastra.ai/docs/server/auth) for a full list of supported providers.
 
 ## How it works