@mastra/mcp-docs-server 1.0.0-beta.8 → 1.0.0

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

@@ -1,6 +1,10 @@
 ---
 title: "Reference: PostgreSQL Storage | Storage"
 description: Documentation for the PostgreSQL storage implementation in Mastra.
+packages:
+  - "@mastra/core"
+  - "@mastra/memory"
+  - "@mastra/pg"
 ---
 
 # PostgreSQL Storage
@@ -9,13 +13,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({
@@ -28,6 +32,13 @@ const storage = new PostgresStore({
 
 <PropertiesTable
   content={[
+    {
+      name: "id",
+      type: "string",
+      description:
+        "Unique identifier for this storage instance.",
+      isOptional: false,
+    },
     {
       name: "connectionString",
       type: "string",
@@ -105,11 +116,12 @@ 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";
 
 const storage = new PostgresStore({
+  id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 });
 
@@ -120,18 +132,20 @@ 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({
+  id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 });
 
 // Required when using storage directly
 await storage.init();
 
-// Now you can use the storage
-await storage.getThread({ threadId: "..." });
+// Access domain-specific stores via getStore()
+const memoryStore = await storage.getStore('memory');
+const thread = await memoryStore?.getThreadById({ threadId: "..." });
 ```
 
 :::warning
@@ -155,50 +169,199 @@ This enables direct queries and custom transaction management. When using these
 
 This approach is intended for advanced scenarios where low-level access is required.
 
+### Using with Next.js
+
+When using `PostgresStore` in Next.js applications, [Hot Module Replacement (HMR)](https://nextjs.org/docs/architecture/fast-refresh) during development can cause multiple storage instances to be created, resulting in this warning:
+
+```
+WARNING: Creating a duplicate database object for the same connection.
+```
+
+To prevent this, store the `PostgresStore` instance on the global object so it persists across HMR reloads:
+
+```typescript title="src/mastra/storage.ts"
+import { PostgresStore } from "@mastra/pg";
+import { Memory } from "@mastra/memory";
+
+// Extend the global type to include our instances
+declare global {
+  var pgStore: PostgresStore | undefined;
+  var memory: Memory | undefined;
+}
+
+// Get or create the PostgresStore instance
+function getPgStore(): PostgresStore {
+  if (!global.pgStore) {
+    if (!process.env.DATABASE_URL) {
+      throw new Error("DATABASE_URL is not defined in environment variables");
+    }
+    global.pgStore = new PostgresStore({
+      id: "pg-storage",
+      connectionString: process.env.DATABASE_URL,
+      ssl:
+        process.env.DATABASE_SSL === "true"
+          ? { rejectUnauthorized: false }
+          : false,
+    });
+  }
+  return global.pgStore;
+}
+
+// Get or create the Memory instance
+function getMemory(): Memory {
+  if (!global.memory) {
+    global.memory = new Memory({
+      storage: getPgStore(),
+    });
+  }
+  return global.memory;
+}
+
+export const storage = getPgStore();
+export const memory = getMemory();
+```
+
+Then use the exported instances in your Mastra configuration:
+
+```typescript title="src/mastra/index.ts"
+import { Mastra } from "@mastra/core/mastra";
+import { storage } from "./storage";
+
+export const mastra = new Mastra({
+  storage,
+  // ...other config
+});
+```
+
+This pattern ensures only one `PostgresStore` instance is created regardless of how many times the module is reloaded during development. The same pattern can be applied to other storage providers like `LibSQLStore`.
+
+:::tip
+This singleton pattern is only necessary during local development with HMR. In production builds, modules are only loaded once.
+:::
+
+## 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.
+PostgreSQL storage provides index management to optimize query performance.
 
-### Automatic Performance Indexes
+### Default Indexes
 
-PostgreSQL storage automatically creates composite indexes during initialization for common query patterns:
+PostgreSQL storage creates composite indexes during initialization for common query patterns:
 
 - `mastra_threads_resourceid_createdat_idx`: (resourceId, createdAt DESC)
 - `mastra_messages_thread_id_createdat_idx`: (thread_id, createdAt DESC)
-- `mastra_traces_name_starttime_idx`: (name, startTime DESC)
-- `mastra_evals_agent_name_created_at_idx`: (agent_name, created_at DESC)
+- `mastra_ai_spans_traceid_startedat_idx`: (traceId, startedAt DESC)
+- `mastra_ai_spans_parentspanid_startedat_idx`: (parentSpanId, startedAt DESC)
+- `mastra_ai_spans_name_startedat_idx`: (name, startedAt DESC)
+- `mastra_ai_spans_scope_startedat_idx`: (scope, startedAt DESC)
+- `mastra_scores_trace_id_span_id_created_at_idx`: (traceId, spanId, createdAt DESC)
 
-These indexes significantly improve performance for filtered queries with sorting.
+These indexes improve performance for filtered queries with sorting, including `dateRange` filters on message queries.
 
-### Creating Custom Indexes
+### Configuring Indexes
 
-Create additional indexes to optimize specific query patterns:
+You can control index creation via constructor options:
 
-```typescript copy
-// Basic index for common queries
-await storage.createIndex({
-  name: "idx_threads_resource",
-  table: "mastra_threads",
-  columns: ["resourceId"],
-});
+```typescript
+import { PostgresStore } from "@mastra/pg";
 
-// Composite index with sort order for filtering + sorting
-await storage.createIndex({
-  name: "idx_messages_composite",
-  table: "mastra_messages",
-  columns: ["thread_id", "createdAt DESC"],
+// Skip default indexes (manage indexes separately)
+const store = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+  skipDefaultIndexes: true,
 });
 
-// GIN index for JSONB columns (fast JSON queries)
-await storage.createIndex({
-  name: "idx_traces_attributes",
-  table: "mastra_traces",
-  columns: ["attributes"],
-  method: "gin",
+// Add custom indexes during initialization
+const storeWithCustomIndexes = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+  indexes: [
+    {
+      name: "idx_threads_metadata_type",
+      table: "mastra_threads",
+      columns: ["metadata->>'type'"],
+    },
+    {
+      name: "idx_messages_status",
+      table: "mastra_messages",
+      columns: ["metadata->>'status'"],
+    },
+  ],
 });
 ```
 
-For more advanced use cases, you can also use:
+For advanced index types, you can specify additional options:
 
 - `unique: true` for unique constraints
 - `where: 'condition'` for partial indexes
@@ -274,66 +437,48 @@ For more advanced use cases, you can also use:
   ]}
 />
 
-### Managing Indexes
-
-List and monitor existing indexes:
-
-```typescript copy
-// List all indexes
-const allIndexes = await storage.listIndexes();
-console.log(allIndexes);
-// [
-//   {
-//     name: 'mastra_threads_pkey',
-//     table: 'mastra_threads',
-//     columns: ['id'],
-//     unique: true,
-//     size: '16 KB',
-//     definition: 'CREATE UNIQUE INDEX...'
-//   },
-//   ...
-// ]
-
-// List indexes for specific table
-const threadIndexes = await storage.listIndexes("mastra_threads");
-
-// Get detailed statistics for an index
-const stats = await storage.describeIndex("idx_threads_resource");
-console.log(stats);
-// {
-//   name: 'idx_threads_resource',
-//   table: 'mastra_threads',
-//   columns: ['resourceId', 'createdAt'],
-//   unique: false,
-//   size: '128 KB',
-//   definition: 'CREATE INDEX idx_threads_resource...',
-//   method: 'btree',
-//   scans: 1542,           // Number of index scans
-//   tuples_read: 45230,    // Tuples read via index
-//   tuples_fetched: 12050  // Tuples fetched via index
-// }
-
-// Drop an index
-await storage.dropIndex("idx_threads_status");
-```
-
 ### Schema-Specific Indexes
 
-When using custom schemas, indexes are created with schema prefixes:
+When using custom schemas, index names are prefixed with the schema name:
 
-```typescript copy
+```typescript
 const storage = new PostgresStore({
   id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
   schemaName: "custom_schema",
+  indexes: [
+    {
+      name: "idx_threads_status",
+      table: "mastra_threads",
+      columns: ["status"],
+    },
+  ],
 });
 
 // Creates index as: custom_schema_idx_threads_status
-await storage.createIndex({
-  name: "idx_threads_status",
-  table: "mastra_threads",
-  columns: ["status"],
-});
+```
+
+### Managing Indexes via SQL
+
+For advanced index management (listing, dropping, analyzing), use direct SQL queries via the `db` accessor:
+
+```typescript
+// List indexes for a table
+const indexes = await storage.db.any(`
+  SELECT indexname, indexdef
+  FROM pg_indexes
+  WHERE tablename = 'mastra_messages'
+`);
+
+// Drop an index
+await storage.db.none('DROP INDEX IF EXISTS idx_my_custom_index');
+
+// Analyze index usage
+const stats = await storage.db.one(`
+  SELECT idx_scan, idx_tup_read
+  FROM pg_stat_user_indexes
+  WHERE indexrelname = 'mastra_messages_thread_id_createdat_idx'
+`);
 ```
 
 ### Index Types and Use Cases

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

@@ -1,6 +1,10 @@
 ---
 title: "Reference: Upstash Storage | Storage"
 description: Documentation for the Upstash storage implementation in Mastra.
+packages:
+  - "@mastra/core"
+  - "@mastra/memory"
+  - "@mastra/upstash"
 ---
 
 # Upstash Storage
@@ -15,13 +19,13 @@ The Upstash storage implementation provides a serverless-friendly storage soluti
 
 ## Installation
 
-```bash copy
+```bash
 npm install @mastra/upstash@beta
 ```
 
 ## Usage
 
-```typescript copy showLineNumbers
+```typescript
 import { UpstashStore } from "@mastra/upstash";
 
 const storage = new UpstashStore({
@@ -91,3 +95,75 @@ For optimal performance:
 - Use appropriate key prefixes to organize data
 - Monitor Redis memory usage
 - Consider data expiration policies if needed
+
+## Usage Example
+
+### Adding memory to an agent
+
+To add Upstash memory to an agent use the `Memory` class and create a new `storage` key using `UpstashStore` and a new `vector` key using `UpstashVector`. The configuration can point to either a remote service or a local setup.
+
+```typescript title="src/mastra/agents/example-upstash-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { UpstashStore } from "@mastra/upstash";
+
+export const upstashAgent = new Agent({
+  id: "upstash-agent",
+  name: "Upstash 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 UpstashStore({
+      id: 'upstash-agent-storage',
+      url: process.env.UPSTASH_REDIS_REST_URL!,
+      token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+    }),
+    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-upstash-agent.ts"
+import "dotenv/config";
+
+import { mastra } from "./mastra";
+
+const threadId = "123";
+const resourceId = "user-456";
+
+const agent = mastra.getAgent("upstashAgent");
+
+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/streaming/ChunkType.mdx

@@ -1,6 +1,8 @@
 ---
 title: "Reference: ChunkType | Streaming"
 description: "Documentation for the ChunkType type used in Mastra streaming responses, defining all possible chunk types and their payloads."
+packages:
+  - "@mastra/core"
 ---
 
 import PropertiesTable from "@site/src/components/PropertiesTable";
@@ -1013,6 +1015,11 @@ Stream has completed successfully.
               type: "object",
               description: "Message history",
             },
+            {
+              name: "response",
+              type: "object",
+              description: "Response metadata and messages from the model provider",
+            },
           ],
         },
       ],
@@ -1097,7 +1104,7 @@ Emitted when using output generation with defined schemas. Contains partial or c
     },
     {
       name: "object",
-      type: "PartialSchemaOutput<OUTPUT>",
+      type: "Partial<OUTPUT>",
       description:
         "Partial or complete structured data matching the defined schema. The type is determined by the OUTPUT schema parameter.",
     },
@@ -1255,7 +1262,7 @@ Contains monitoring and observability data from agent execution. Can include wor
 
 ### tripwire
 
-Emitted when the stream is forcibly terminated due to content being blocked by output processors. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed.
+Emitted when the stream is forcibly terminated due to content being blocked by a processor. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed. The payload includes information about why the content was blocked and whether a retry was requested.
 
 <PropertiesTable
   content={[
@@ -1274,11 +1281,32 @@ Emitted when the stream is forcibly terminated due to content being blocked by o
           type: "TripwirePayload",
           parameters: [
             {
-              name: "tripwireReason",
+              name: "reason",
               type: "string",
               description:
                 "Explanation of why the content was blocked (e.g., 'Output processor blocked content')",
             },
+            {
+              name: "retry",
+              type: "boolean",
+              isOptional: true,
+              description:
+                "Whether the processor requested a retry of the step",
+            },
+            {
+              name: "metadata",
+              type: "unknown",
+              isOptional: true,
+              description:
+                "Additional metadata from the processor (e.g., scores, categories)",
+            },
+            {
+              name: "processorId",
+              type: "string",
+              isOptional: true,
+              description:
+                "ID of the processor that triggered the tripwire",
+            },
           ],
         },
       ],