@mastra/core 1.7.0 → 1.8.0

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

@@ -0,0 +1,135 @@
+# libSQL Storage
+
+[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](https://mastra.ai/reference/vectors/libsql) which covers embeddings and vector search.
+
+## Installation
+
+Storage providers must be installed as separate packages:
+
+**npm**:
+
+```bash
+npm install @mastra/libsql@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/libsql@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/libsql@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/libsql@latest
+```
+
+## Usage
+
+```typescript
+import { LibSQLStore } from '@mastra/libsql'
+import { Mastra } from '@mastra/core'
+
+const mastra = new Mastra({
+  storage: new LibSQLStore({
+    id: 'libsql-storage',
+    url: 'file:./storage.db',
+  }),
+})
+```
+
+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',
+    }),
+  }),
+})
+```
+
+> **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
+
+**url:** (`string`): 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.
+
+**authToken?:** (`string`): Authentication token for remote libSQL databases.
+
+## Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically to create the [core schema](https://mastra.ai/reference/storage/overview):
+
+```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() called automatically
+})
+```
+
+If using storage directly without Mastra, call `init()` explicitly:
+
+```typescript
+import { LibSQLStore } from '@mastra/libsql'
+
+const storage = new LibSQLStore({
+  id: 'libsql-storage',
+  url: 'file:./storage.db',
+})
+
+await storage.init()
+
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory')
+const thread = await memoryStore?.getThreadById({ threadId: '...' })
+```
+
+## Observability
+
+libSQL supports observability and is ideal for local development. Use the `realtime` [tracing strategy](https://mastra.ai/docs/observability/tracing/exporters/default) for immediate visibility while debugging.
+
+For production environments with higher trace volumes, consider using [PostgreSQL](https://mastra.ai/reference/storage/postgresql) or [ClickHouse via composite storage](https://mastra.ai/reference/storage/composite).

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

@@ -0,0 +1,262 @@
+# MongoDB Storage
+
+The MongoDB storage implementation provides a scalable storage solution using MongoDB databases with support for both document storage and vector operations.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/mongodb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mongodb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mongodb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mongodb@latest
+```
+
+## Usage
+
+Ensure you have a MongoDB Atlas Local (via Docker) or MongoDB Atlas Cloud instance with Atlas Search enabled. MongoDB 7.0+ is recommended.
+
+```typescript
+import { MongoDBStore } from '@mastra/mongodb'
+
+const storage = new MongoDBStore({
+  id: 'mongodb-storage',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+})
+```
+
+## Parameters
+
+**id:** (`string`): Unique identifier for this storage instance.
+
+**uri:** (`string`): MongoDB connection string (e.g., mongodb+srv://user:password\@cluster.mongodb.net)
+
+**url?:** (`string`): Deprecated. Use uri instead. MongoDB connection string (supported for backward compatibility).
+
+**dbName:** (`string`): The name of the database you want the storage to use.
+
+**options?:** (`MongoClientOptions`): MongoDB client options for advanced configuration (SSL, connection pooling, etc.).
+
+> **Deprecation Notice:** The `url` parameter is deprecated but still supported for backward compatibility. Please use `uri` instead in all new code.
+
+## Constructor Examples
+
+You can instantiate `MongoDBStore` in the following ways:
+
+```ts
+import { MongoDBStore } from '@mastra/mongodb'
+
+// Basic connection without custom options
+const store1 = new MongoDBStore({
+  id: 'mongodb-storage-01',
+  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
+  dbName: 'mastra_storage',
+})
+
+// Using connection string with options
+const store2 = new MongoDBStore({
+  id: 'mongodb-storage-02',
+  uri: 'mongodb+srv://user:password@cluster.mongodb.net',
+  dbName: 'mastra_storage',
+  options: {
+    retryWrites: true,
+    maxPoolSize: 10,
+    serverSelectionTimeoutMS: 5000,
+    socketTimeoutMS: 45000,
+  },
+})
+```
+
+## Additional Notes
+
+### Collection Management
+
+The storage implementation handles collection creation and management automatically. It creates the following collections:
+
+- `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
+import { Mastra } from '@mastra/core'
+import { MongoDBStore } from '@mastra/mongodb'
+
+const storage = new MongoDBStore({
+  id: 'mongodb-storage',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+})
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+})
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the collections:
+
+```typescript
+import { MongoDBStore } from '@mastra/mongodb'
+
+const storage = new MongoDBStore({
+  id: 'mongodb-storage',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+})
+
+// Required when using storage directly
+await storage.init()
+
+// Access domain-specific stores via getStore()
+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.
+
+## Vector Search Capabilities
+
+MongoDB storage includes built-in vector search capabilities for AI applications:
+
+### Vector Index Creation
+
+```typescript
+import { MongoDBVector } from '@mastra/mongodb'
+
+const vectorStore = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+})
+
+// Create a vector index for embeddings
+await vectorStore.createIndex({
+  indexName: 'document_embeddings',
+  dimension: 1536,
+})
+```
+
+### Vector Operations
+
+```typescript
+// Store vectors with metadata
+await vectorStore.upsert({
+  indexName: "document_embeddings",
+  vectors: [
+    {
+      id: "doc-1",
+      values: [0.1, 0.2, 0.3, ...], // 1536-dimensional vector
+      metadata: {
+        title: "Document Title",
+        category: "technical",
+        source: "api-docs",
+      },
+    },
+  ],
+});
+
+// Similarity search
+const results = await vectorStore.query({
+  indexName: "document_embeddings",
+  vector: queryEmbedding,
+  topK: 5,
+  filter: {
+    category: "technical",
+  },
+});
+```
+
+## 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
+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({
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    options: {
+      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
+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/dist/docs/references/reference-storage-mssql.md

@@ -0,0 +1,157 @@
+# MSSQL Storage
+
+The MSSQL storage implementation provides a production-ready storage solution using Microsoft SQL Server databases.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/mssql@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/mssql@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/mssql@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/mssql@latest
+```
+
+## Usage
+
+```typescript
+import { MSSQLStore } from '@mastra/mssql'
+
+const storage = new MSSQLStore({
+  id: 'mssql-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+```
+
+## Parameters
+
+**connectionString:** (`string`): MSSQL connection string (e.g., Server=localhost,1433;Database=mydb;User Id=sa;Password=password;Encrypt=true;TrustServerCertificate=true)
+
+**schemaName?:** (`string`): The name of the schema you want the storage to use. Will use the default schema if not provided.
+
+## Constructor Examples
+
+You can instantiate `MSSQLStore` in the following ways:
+
+```ts
+import { MSSQLStore } from '@mastra/mssql'
+
+// Using a connection string only
+const store1 = new MSSQLStore({
+  id: 'mssql-storage-1',
+  connectionString:
+    'Server=localhost,1433;Database=mydb;User Id=sa;Password=password;Encrypt=true;TrustServerCertificate=true',
+})
+
+// Using a connection string with a custom schema name
+const store2 = new MSSQLStore({
+  id: 'mssql-storage-2',
+  connectionString:
+    'Server=localhost,1433;Database=mydb;User Id=sa;Password=password;Encrypt=true;TrustServerCertificate=true',
+  schemaName: 'custom_schema', // optional
+})
+
+// Using individual connection parameters
+const store4 = new MSSQLStore({
+  id: 'mssql-storage-3',
+  server: 'localhost',
+  port: 1433,
+  database: 'mydb',
+  user: 'user',
+  password: 'password',
+})
+
+// Individual parameters with schemaName
+const store5 = new MSSQLStore({
+  id: 'mssql-storage-4',
+  server: 'localhost',
+  port: 1433,
+  database: 'mydb',
+  user: 'user',
+  password: 'password',
+  schemaName: 'custom_schema', // optional
+})
+```
+
+## Additional Notes
+
+### Schema Management
+
+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
+import { Mastra } from '@mastra/core'
+import { MSSQLStore } from '@mastra/mssql'
+
+const storage = new MSSQLStore({
+  connectionString: process.env.DATABASE_URL,
+})
+
+const mastra = new Mastra({
+  storage, // init() is called automatically
+})
+```
+
+If you're using storage directly without Mastra, you must call `init()` explicitly to create the tables:
+
+```typescript
+import { MSSQLStore } from '@mastra/mssql'
+
+const storage = new MSSQLStore({
+  id: 'mssql-storage',
+  connectionString: process.env.DATABASE_URL,
+})
+
+// Required when using storage directly
+await storage.init()
+
+// Access domain-specific stores via getStore()
+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.
+
+### Direct Database and Pool Access
+
+`MSSQLStore` exposes the mssql connection pool as public fields:
+
+```typescript
+store.pool // mssql connection pool instance
+```
+
+This enables direct queries and custom transaction management. When using these fields:
+
+- You are responsible for proper connection and transaction handling.
+- Closing the store (`store.close()`) will destroy the associated connection pool.
+- Direct access bypasses any additional logic or validation provided by MSSQLStore methods.
+
+This approach is intended for advanced scenarios where low-level access is required.

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

@@ -0,0 +1,121 @@
+# Storage Overview
+
+Mastra requires the following tables to be present in the database.
+
+## Core Schema
+
+**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.
+
+iduuidv4PRIMARYKEYNOT NULLUnique identifier for the message (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)thread\_iduuidv4FK → threads.idNOT NULLParent thread referenceresourceIduuidv4CAN BE NULLID of the resource that owns this messagecontenttextNOT NULLJSON of the message content in V2 format. Example: `{ format: 2, parts: [...] }`roletextNOT NULLEnum of `user | assistant`createdAttimestampNOT NULLUsed for thread message ordering
+
+The message `content` column contains a JSON object conforming to the `MastraMessageContentV2` type, which is designed to align closely with the AI SDK `UIMessage` message shape.
+
+formatintegerNOT NULLMessage format version (currently 2)partsarray (JSON)NOT NULLArray of message parts (text, tool-invocation, file, reasoning, etc.). The structure of items in this array varies by `type`.experimental\_attachmentsarray (JSON)CAN BE NULLOptional array of file attachmentscontenttextCAN BE NULLOptional main text content of the messagetoolInvocationsarray (JSON)CAN BE NULLOptional array summarizing tool calls and resultsreasoningobject (JSON)CAN BE NULLOptional information about the reasoning process behind the assistant's responseannotationsobject (JSON)CAN BE NULLOptional additional metadata or annotations
+
+**Threads**:
+
+Groups related messages together and associates them with a resource. Contains metadata about the conversation.
+
+iduuidv4PRIMARYKEYNOT NULLUnique identifier for the thread (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)resourceIdtextNOT NULLPrimary identifier of the external resource this thread is associated with. Used to group and retrieve related threads.titletextNOT NULLTitle of the conversation threadmetadatatextCustom thread metadata as stringified JSON. Example:
+
+```json
+{
+  "category": "support",
+  "priority": 1
+}
+```
+
+createdAttimestampNOT NULLupdatedAttimestampNOT NULLUsed for thread ordering history
+
+**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.
+
+idtextPRIMARYKEYNOT NULLResource identifier (user or entity ID) - same as resourceId used in threads and agent callsworkingMemorytextCAN BE NULLPersistent working memory data as Markdown text. Contains user profile, preferences, and contextual information that persists across conversation threads.metadatajsonbCAN BE NULLAdditional resource metadata as JSON. Example:
+
+```json
+{
+  "preferences": {
+    "language": "en",
+    "timezone": "UTC"
+  },
+  "tags": [
+    "premium",
+    "beta-user"
+  ]
+}
+```
+
+createdAttimestampNOT NULLWhen the resource record was first createdupdatedAttimestampNOT NULLWhen the working memory was last updated
+
+**Workflows**:
+
+When `suspend` is called on a workflow, its state is saved in the following format. When `resume` is called, that state is rehydrated.
+
+workflow\_nametextNOT NULLName of the workflowrun\_iduuidv4NOT NULLUnique identifier for the workflow execution. Used to track state across suspend/resume cycles (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)snapshottextNOT NULLSerialized workflow state as JSON. Example:
+
+```json
+{
+  "value": {
+    "currentState": "running"
+  },
+  "context": {
+    "stepResults": {},
+    "attempts": {},
+    "triggerData": {}
+  },
+  "activePaths": [],
+  "runId": "550e8400-e29b-41d4-a716-446655440000",
+  "timestamp": 1648176000000
+}
+```
+
+createdAttimestampNOT NULLupdatedAttimestampNOT NULLLast modification time, used to track state changes during workflow execution
+
+**Evals**:
+
+Stores eval results from running metrics against agent outputs.
+
+inputtextNOT NULLInput provided to the agentoutputtextNOT NULLOutput generated by the agentresultjsonbNOT NULLEval result data that includes score and details. Example:
+
+```json
+{
+  "score": 0.95,
+  "details": {
+    "reason": "Response accurately reflects source material",
+    "citations": [
+      "page 1",
+      "page 3"
+    ]
+  }
+}
+```
+
+agent\_nametextNOT NULLmetric\_nametextNOT NULLe.g Faithfulness, Hallucination, etc.instructionstextNOT NULLSystem prompt or instructions for the agenttest\_infojsonbNOT NULLAdditional test metadata and configurationglobal\_run\_iduuidv4NOT NULLGroups related evaluation runs (e.g. all unit tests in a CI run)run\_iduuidv4NOT NULLUnique identifier for the run being evaluated (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)created\_attimestampNOT NULL
+
+**Traces**:
+
+Captures OpenTelemetry traces for monitoring and debugging.
+
+idtextNOT NULLPRIMARYKEYUnique trace identifierparentSpanIdtextID of the parent span. Null if span is top levelnametextNOT NULLHierarchical operation name (e.g. `workflow.myWorkflow.execute`, `http.request`, `database.query`)traceIdtextNOT NULLRoot trace identifier that groups related spansscopetextNOT NULLLibrary/package/service that created the span (e.g. `@mastra/core`, `express`, `pg`)kindintegerNOT NULL`INTERNAL` (0, within process), `CLIENT` (1, outgoing calls), `SERVER` (2, incoming calls), `PRODUCER` (3, async job creation), `CONSUMER` (4, async job processing)attributesjsonbUser defined key-value pairs that contain span metadatastatusjsonbJSON object with `code` (UNSET=0, ERROR=1, OK=2) and optional `message`. Example:
+
+```json
+{
+  "code": 1,
+  "message": "HTTP request failed with status 500"
+}
+```
+
+eventsjsonbTime-stamped events that occurred during the spanlinksjsonbLinks to other related spansothertextAdditional OpenTelemetry span fields as stringified JSON. Example:
+
+```json
+{
+  "droppedAttributesCount": 2,
+  "droppedEventsCount": 1,
+  "instrumentationLibrary": "@opentelemetry/instrumentation-http"
+}
+```
+
+startTimebigintNOT NULLNanoseconds since Unix epoch when span startedendTimebigintNOT NULLNanoseconds since Unix epoch when span endedcreatedAttimestampNOT NULL