@mastra/mcp-docs-server 1.0.0-beta.11 → 1.0.0-beta.14

package/.docs/raw/reference/storage/libsql.mdx

@@ -1,37 +1,81 @@
 ---
-title: "Reference: LibSQL Storage | Storage"
-description: Documentation for the LibSQL storage implementation in Mastra.
+title: "Reference: libSQL Storage | Storage"
+description: Documentation for the libSQL storage implementation in Mastra.
 ---
 
-# LibSQL Storage
+# libSQL Storage
 
-The LibSQL storage implementation provides a SQLite-compatible storage solution that can run both in-memory and as a persistent database.
+[libSQL](https://docs.turso.tech/libsql) is an open-source, SQLite-compatible database that supports both local and remote deployments. It can be used to store message history, workflow snapshots, traces, and eval scores.
+
+For vectors like semantic recall or traditional RAG, use [libSQL Vector](/reference/v1/vectors/libsql) which covers embeddings and vector search.
 
 ## Installation
 
-```bash copy
+Storage providers must be installed as separate packages:
+
+```bash
 npm install @mastra/libsql@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { LibSQLStore } from "@mastra/libsql";
+import { Mastra } from "@mastra/core";
 
-// File database (development)
-const storage = new LibSQLStore({
-  id: 'libsql-storage',
-  url: "file:./storage.db",
+const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'libsql-storage',
+    url: "file:./storage.db",
+  }),
 });
+```
 
-// Persistent database (production)
-const storage = new LibSQLStore({
-  id: 'libsql-storage',
-  url: process.env.DATABASE_URL,
+Agent-level file storage:
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { LibSQLStore } from "@mastra/libsql";
+
+export const agent = new Agent({
+  id: "example-agent",
+  memory: new Memory({
+    storage: new LibSQLStore({
+      id: 'libsql-storage',
+      url: "file:./agent.db",
+    }),
+  }),
 });
 ```
 
-## Parameters
+:::warning
+File storage doesn't work with serverless platforms that have ephemeral file systems. For serverless deployments, use [Turso](https://turso.tech) or a different database engine.
+:::
+
+Production with remote database:
+
+```typescript 
+storage: new LibSQLStore({
+  id: 'libsql-storage',
+  url: "libsql://your-db-name.aws-ap-northeast-1.turso.io",
+  authToken: process.env.TURSO_AUTH_TOKEN,
+})
+```
+
+For local development and testing, you can store data in memory:
+
+```typescript 
+storage: new LibSQLStore({
+  id: 'libsql-storage',
+  url: ":memory:",
+})
+```
+:::warning
+In-memory storage resets when the process changes. Only suitable for development.
+:::
+
+## Options
 
 <PropertiesTable
   content={[
@@ -39,75 +83,46 @@ const storage = new LibSQLStore({
       name: "url",
       type: "string",
       description:
-        "Database URL. Use ':memory:' for in-memory database, 'file:filename.db' for a file database, or any LibSQL-compatible connection string for persistent storage.",
+        "Database URL. Use `:memory:` for in-memory database, `file:filename.db` for a file database, or a libSQL connection string (e.g., `libsql://your-database.turso.io`) for remote storage.",
       isOptional: false,
     },
     {
       name: "authToken",
       type: "string",
-      description: "Authentication token for remote LibSQL databases.",
+      description: "Authentication token for remote libSQL databases.",
       isOptional: true,
     },
   ]}
 />
 
-## Additional Notes
-
-### In-Memory vs Persistent Storage
-
-The file configuration (`file:storage.db`) is useful for:
-
-- Development and testing
-- Temporary storage
-- Quick prototyping
-
-For production use cases, use a persistent database URL: `libsql://your-database.turso.io`
+## Initialization
 
-### Schema Management
+When you pass storage to the Mastra class, `init()` is called automatically to create the [core schema](/reference/v1/storage/overview#core-schema):
 
-The storage implementation handles schema creation and updates automatically. It creates the following tables:
-
-- `mastra_workflow_snapshot`: Stores workflow state and execution data
-- `mastra_evals`: Stores evaluation results and metadata
-- `mastra_threads`: Stores conversation threads
-- `mastra_messages`: Stores individual messages
-- `mastra_traces`: Stores telemetry and tracing data
-- `mastra_scorers`: Stores scoring and evaluation data
-- `mastra_resources`: Stores resource working memory data
-
-### Initialization
-
-When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
-
-```typescript copy
+```typescript 
 import { Mastra } from "@mastra/core";
 import { LibSQLStore } from "@mastra/libsql";
 
 const storage = new LibSQLStore({
+  id: 'libsql-storage',
   url: "file:./storage.db",
 });
 
 const mastra = new Mastra({
-  storage, // init() is called automatically
+  storage, // init() called automatically
 });
 ```
 
-If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+If using storage directly without Mastra, call `init()` explicitly:
 
-```typescript copy
+```typescript 
 import { LibSQLStore } from "@mastra/libsql";
 
 const storage = new LibSQLStore({
+  id: 'libsql-storage',
   url: "file:./storage.db",
 });
 
-// Required when using storage directly
 await storage.init();
-
-// Now you can use the storage
 await storage.getThread({ threadId: "..." });
 ```
-
-:::warning
-If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
-:::

package/.docs/raw/reference/storage/mongodb.mdx

@@ -9,7 +9,7 @@ The MongoDB storage implementation provides a scalable storage solution using Mo
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/mongodb@beta
 ```
 
@@ -17,7 +17,7 @@ npm install @mastra/mongodb@beta
 
 Ensure you have a MongoDB Atlas Local (via Docker) or MongoDB Atlas Cloud instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
 
-```typescript copy showLineNumbers
+```typescript
 import { MongoDBStore } from "@mastra/mongodb";
 
 const storage = new MongoDBStore({
@@ -47,7 +47,7 @@ const storage = new MongoDBStore({
       name: "options",
       type: "MongoClientOptions",
       description:
-        "MongoDB client options for advanced configuration (SSL, connection pooling, etc.). See advanced configuration [here](https://www.mongodb.com/docs/drivers/node/current/connect/connection-options/).",
+        "MongoDB client options for advanced configuration (SSL, connection pooling, etc.).",
       isOptional: true,
     },
   ]}
@@ -97,7 +97,7 @@ The storage implementation handles collection creation and management automatica
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
 
-```typescript copy
+```typescript
 import { Mastra } from "@mastra/core";
 import { MongoDBStore } from "@mastra/mongodb";
 
@@ -113,7 +113,7 @@ const mastra = new Mastra({
 
 If you're using storage directly without Mastra, you must call `init()` explicitly to create the collections:
 
-```typescript copy
+```typescript
 import { MongoDBStore } from "@mastra/mongodb";
 
 const storage = new MongoDBStore({
@@ -138,7 +138,7 @@ MongoDB storage includes built-in vector search capabilities for AI applications
 
 ### Vector Index Creation
 
-```typescript copy
+```typescript
 import { MongoDBVector } from "@mastra/mongodb";
 
 const vectorStore = new MongoDBVector({
@@ -155,7 +155,7 @@ await vectorStore.createIndex({
 
 ### Vector Operations
 
-```typescript copy
+```typescript
 // Store vectors with metadata
 await vectorStore.upsert({
   indexName: "document_embeddings",
@@ -182,3 +182,76 @@ const results = await vectorStore.query({
   },
 });
 ```
+
+## Usage Example
+
+### Adding memory to an agent
+
+To add MongoDB memory to an agent use the `Memory` class and create a new `storage` key using `MongoDBStore`. The configuration supports both local and remote MongoDB instances.
+
+```typescript title="src/mastra/agents/example-mongodb-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { MongoDBStore } from "@mastra/mongodb";
+
+export const mongodbAgent = new Agent({
+  id: "mongodb-agent",
+  name: "mongodb-agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new MongoDBStore({
+      url: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    options: {
+      threads: {
+        generateTitle: true,
+      },
+    },
+  }),
+});
+```
+
+### Using the agent
+
+Use `memoryOptions` to scope recall for this request. Set `lastMessages: 5` to limit recency-based recall, and use `semanticRecall` to fetch the `topK: 3` most relevant messages, including `messageRange: 2` neighboring messages for context around each match.
+
+```typescript title="src/test-mongodb-agent.ts"
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("mongodbAgent");
+
+const message = await agent.stream("My name is Mastra", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+});
+
+await message.textStream.pipeTo(new WritableStream());
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+  memoryOptions: {
+    lastMessages: 5,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2,
+    },
+  },
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```

package/.docs/raw/reference/storage/mssql.mdx

@@ -9,13 +9,13 @@ The MSSQL storage implementation provides a production-ready storage solution us
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/mssql@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { MSSQLStore } from "@mastra/mssql";
 
 const storage = new MSSQLStore({
@@ -105,7 +105,7 @@ The storage implementation handles schema creation and updates automatically. It
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
 
-```typescript copy
+```typescript
 import { Mastra } from "@mastra/core";
 import { MSSQLStore } from "@mastra/mssql";
 
@@ -120,7 +120,7 @@ const mastra = new Mastra({
 
 If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
 
-```typescript copy
+```typescript
 import { MSSQLStore } from "@mastra/mssql";
 
 const storage = new MSSQLStore({

package/.docs/raw/{server-db/storage.mdx → reference/storage/overview.mdx}

@@ -1,58 +1,22 @@
 ---
-title: "MastraStorage | Server & DB"
-description: Overview of Mastra's storage system and data persistence capabilities.
+title: "Reference: Storage Overview | Storage"
+description: Core data schema and table structure for Mastra's storage system.
 ---
 
-import PropertiesTable from "@site/src/components/PropertiesTable";
 import { SchemaTable } from "@site/src/components/SchemaTable";
-import { StorageOverviewImage } from "@site/src/components/StorageOverviewImage";
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-# MastraStorage
+# Storage Overview
 
-`MastraStorage` provides a unified interface for managing:
+Mastra requires the following tables to be present in the database.
 
-- **Suspended Workflows**: the serialized state of suspended workflows (so they can be resumed later)
-- **Memory**: threads and messages per `resourceId` in your application
-- **Traces**: OpenTelemetry traces from all components of Mastra
-- **Eval Datasets**: scores and scoring reasons from eval runs
-
-<br />
-
-<br />
-
-<StorageOverviewImage />
-
-Mastra provides different storage providers, but you can treat them as interchangeable. Eg, you could use libsql in development but postgres in production, and your code will work the same both ways.
-
-## Configuration
-
-Mastra can be configured with a default storage option:
-
-```typescript copy
-import { Mastra } from "@mastra/core";
-import { LibSQLStore } from "@mastra/libsql";
-
-const mastra = new Mastra({
-  storage: new LibSQLStore({
-    id: 'mastra-storage',
-    url: "file:./mastra.db",
-  }),
-});
-```
-
-If you do not specify any `storage` configuration, Mastra will not persist data across application restarts or deployments. For any
-deployment beyond local testing you should provide your own storage
-configuration either on `Mastra` or directly within `new Memory()`.
-
-## Data Schema
+## Core Schema
 
 <Tabs>
   <TabItem value="messages" label="Messages">
 Stores conversation messages and their metadata. Each message belongs to a thread and contains the actual content along with metadata about the sender role and message type.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -152,10 +116,9 @@ The message `content` column contains a JSON object conforming to the `MastraMes
 
 </TabItem>
 
-  <TabItem value="threads" label="Threads">
+<TabItem value="threads" label="Threads">
 Groups related messages together and associates them with a resource. Contains metadata about the conversation.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -202,10 +165,9 @@ Groups related messages together and associates them with a resource. Contains m
 />
 
 </TabItem>
-  <TabItem value="resources" label="Resources">
+<TabItem value="resources" label="Resources">
 Stores user-specific data for resource-scoped working memory. Each resource represents a user or entity, allowing working memory to persist across all conversation threads for that user.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -248,10 +210,9 @@ Stores user-specific data for resource-scoped working memory. Each resource repr
 />
 
 </TabItem>
-  <TabItem value="workflows" label="Workflows">
+<TabItem value="workflows" label="Workflows">
 When `suspend` is called on a workflow, its state is saved in the following format. When `resume` is called, that state is rehydrated.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -296,11 +257,10 @@ When `suspend` is called on a workflow, its state is saved in the following form
     }
   ]}
 />
-  </TabItem>
-  <TabItem value="evals" label="Evals">
+</TabItem>
+<TabItem value="evals" label="Evals">
 Stores eval results from running metrics against agent outputs.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -370,11 +330,10 @@ Stores eval results from running metrics against agent outputs.
     }
   ]}
 />
-  </TabItem>
-  <TabItem value="traces" label="Traces">
+</TabItem>
+<TabItem value="traces" label="Traces">
 Captures OpenTelemetry traces for monitoring and debugging.
 
-<br />
 <SchemaTable
   columns={[
     {
@@ -468,62 +427,5 @@ Captures OpenTelemetry traces for monitoring and debugging.
     }
   ]}
 />
-  </TabItem>
+</TabItem>
 </Tabs>
-
-### Querying Messages
-
-Messages are stored in the `MastraDBMessage` format, which provides a consistent structure across the entire Mastra system:
-
-```typescript copy
-// Get messages for a thread with pagination
-const result = await mastra
-  .getStorage()
-  .listMessages({
-    threadId: "your-thread-id",
-    page: 0,
-    perPage: 50
-  });
-
-console.log(result.messages); // MastraDBMessage[]
-console.log(result.total); // Total count
-console.log(result.hasMore); // Whether more pages exist
-
-// Get messages from multiple threads at once
-const multiThreadResult = await mastra
-  .getStorage()
-  .listMessages({
-    threadId: ["thread-1", "thread-2", "thread-3"],
-    page: 0,
-    perPage: 100
-  });
-
-// Get messages by their IDs
-const messages = await mastra
-  .getStorage()
-  .listMessagesById({ messageIds: messageIdArr });
-```
-
-The `threadId` parameter accepts either a single thread ID string or an array of thread IDs to query messages from multiple threads in a single request.
-
-All message queries return `MastraDBMessage[]` format. If you need to convert messages to AI SDK formats for UI rendering, use the conversion utilities from `@mastra/ai-sdk/ui`:
-
-```typescript copy
-import { toAISdkV5Messages } from '@mastra/ai-sdk/ui';
-
-const result = await mastra
-  .getStorage()
-  .listMessages({ threadId: "your-thread-id" });
-
-// Convert to AI SDK v5 UIMessage format for UI rendering
-const uiMessages = toAISdkV5Messages(result.messages);
-```
-
-## Storage Providers
-
-Mastra supports the following providers:
-
-- For local development, check out [LibSQL Storage](/reference/v1/storage/libsql)
-- For production, check out [PostgreSQL Storage](/reference/v1/storage/postgresql)
-- For serverless deployments, check out [Upstash Storage](/reference/v1/storage/upstash)
-- For document-based storage, check out [MongoDB Storage](/reference/v1/storage/mongodb)

package/.docs/raw/reference/storage/postgresql.mdx

@@ -9,13 +9,13 @@ The PostgreSQL storage implementation provides a production-ready storage soluti
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/pg@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { PostgresStore } from "@mastra/pg";
 
 const storage = new PostgresStore({
@@ -105,7 +105,7 @@ The storage implementation handles schema creation and updates automatically. It
 
 When you pass storage to the Mastra class, `init()` is called automatically before any storage operation:
 
-```typescript copy
+```typescript
 import { Mastra } from "@mastra/core";
 import { PostgresStore } from "@mastra/pg";
 
@@ -120,7 +120,7 @@ const mastra = new Mastra({
 
 If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
 
-```typescript copy
+```typescript
 import { PostgresStore } from "@mastra/pg";
 
 const storage = new PostgresStore({
@@ -155,6 +155,77 @@ This enables direct queries and custom transaction management. When using these
 
 This approach is intended for advanced scenarios where low-level access is required.
 
+## Usage Example
+
+### Adding memory to an agent
+
+To add PostgreSQL memory to an agent use the `Memory` class and create a new `storage` key using `PostgresStore`. The `connectionString` can either be a remote location, or a local database connection.
+
+```typescript title="src/mastra/agents/example-pg-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { PostgresStore } from "@mastra/pg";
+
+export const pgAgent = new Agent({
+  id: "pg-agent",
+  name: "PG Agent",
+  instructions:
+    "You are an AI agent with the ability to automatically recall memories from previous interactions.",
+  model: "openai/gpt-5.1",
+  memory: new Memory({
+    storage: new PostgresStore({
+      id: 'pg-agent-storage',
+      connectionString: process.env.DATABASE_URL!,
+    }),
+    options: {
+      generateTitle: true, // Explicitly enable automatic title generation
+    },
+  }),
+});
+```
+
+### Using the agent
+
+Use `memoryOptions` to scope recall for this request. Set `lastMessages: 5` to limit recency-based recall, and use `semanticRecall` to fetch the `topK: 3` most relevant messages, including `messageRange: 2` neighboring messages for context around each match.
+
+```typescript title="src/test-pg-agent.ts" 
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("pg-agent");
+
+const message = await agent.stream("My name is Mastra", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+});
+
+await message.textStream.pipeTo(new WritableStream());
+
+const stream = await agent.stream("What's my name?", {
+  memory: {
+    thread: threadId,
+    resource: resourceId,
+  },
+  memoryOptions: {
+    lastMessages: 5,
+    semanticRecall: {
+      topK: 3,
+      messageRange: 2,
+    },
+  },
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
 ## Index Management
 
 PostgreSQL storage provides comprehensive index management capabilities to optimize query performance.
@@ -174,7 +245,7 @@ These indexes significantly improve performance for filtered queries with sortin
 
 Create additional indexes to optimize specific query patterns:
 
-```typescript copy
+```typescript
 // Basic index for common queries
 await storage.createIndex({
   name: "idx_threads_resource",
@@ -278,7 +349,7 @@ For more advanced use cases, you can also use:
 
 List and monitor existing indexes:
 
-```typescript copy
+```typescript
 // List all indexes
 const allIndexes = await storage.listIndexes();
 console.log(allIndexes);
@@ -321,7 +392,7 @@ await storage.dropIndex("idx_threads_status");
 
 When using custom schemas, indexes are created with schema prefixes:
 
-```typescript copy
+```typescript
 const storage = new PostgresStore({
   id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,