@mastra/core 1.0.0-beta.21 → 1.0.0-beta.22

package/dist/docs/storage/01-reference.md

@@ -431,27 +431,27 @@ Captures OpenTelemetry traces for monitoring and debugging.
 
 ---
 
-## Reference: Storage Composition
+## Reference: Composite Storage
 
 > Documentation for combining multiple storage backends in Mastra.
 
-MastraStorage can compose storage domains from different adapters. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
+`MastraStorage` can compose storage domains from different providers. Use it when you need different databases for different purposes. For example, use LibSQL for memory and PostgreSQL for workflows.
 
 ## Installation
 
-MastraStorage is included in `@mastra/core`:
+`MastraStorage` is included in `@mastra/core`:
 
 ```bash
 npm install @mastra/core@beta
 ```
 
-You'll also need to install the storage adapters you want to compose:
+You'll also need to install the storage providers you want to compose:
 
 ```bash
 npm install @mastra/pg@beta @mastra/libsql@beta
 ```
 
-## Storage Domains
+## Storage domains
 
 Mastra organizes storage into five specialized domains, each handling a specific type of data. Each domain can be backed by a different storage adapter, and domain classes are exported from each storage package.
 
@@ -469,13 +469,13 @@ Mastra organizes storage into five specialized domains, each handling a specific
 
 Import domain classes directly from each store package and compose them:
 
-```typescript
+```typescript title="src/mastra/index.ts"
 import { MastraStorage } from "@mastra/core/storage";
 import { WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
 import { Mastra } from "@mastra/core";
 
-const mastra = new Mastra({
+export const mastra = new Mastra({
   storage: new MastraStorage({
     id: "composite",
     domains: {
@@ -491,7 +491,7 @@ const mastra = new Mastra({
 
 Use `default` to specify a fallback storage, then override specific domains:
 
-```typescript
+```typescript title="src/mastra/index.ts"
 import { MastraStorage } from "@mastra/core/storage";
 import { PostgresStore } from "@mastra/pg";
 import { MemoryLibSQL } from "@mastra/libsql";
@@ -502,7 +502,7 @@ const pgStore = new PostgresStore({
   connectionString: process.env.DATABASE_URL,
 });
 
-const mastra = new Mastra({
+export const mastra = new Mastra({
   storage: new MastraStorage({
     id: "composite",
     default: pgStore,
@@ -517,9 +517,9 @@ const mastra = new Mastra({
 
 ## Initialization
 
-MastraStorage initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
+`MastraStorage` initializes each configured domain independently. When passed to the Mastra class, `init()` is called automatically:
 
-```typescript
+```typescript title="src/mastra/index.ts"
 import { MastraStorage } from "@mastra/core/storage";
 import { MemoryPG, WorkflowsPG, ScoresPG } from "@mastra/pg";
 import { Mastra } from "@mastra/core";
@@ -533,7 +533,7 @@ const storage = new MastraStorage({
   },
 });
 
-const mastra = new Mastra({
+export const mastra = new Mastra({
   storage, // init() called automatically
 });
 ```
@@ -558,7 +558,7 @@ const memoryStore = await storage.getStore("memory");
 const thread = await memoryStore?.getThreadById({ threadId: "..." });
 ```
 
-## Use Cases
+## Use cases
 
 ### Separate databases for different workloads
 
@@ -955,13 +955,17 @@ Ensure you have a MongoDB Atlas Local (via Docker) or MongoDB Atlas Cloud instan
 import { MongoDBStore } from "@mastra/mongodb";
 
 const storage = new MongoDBStore({
-  url: process.env.MONGODB_URL,
+  id: 'mongodb-storage',
+  uri: process.env.MONGODB_URI,
   dbName: process.env.MONGODB_DATABASE,
 });
 ```
 
 ## Parameters
 
+> **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:
@@ -971,13 +975,15 @@ import { MongoDBStore } from "@mastra/mongodb";
 
 // Basic connection without custom options
 const store1 = new MongoDBStore({
-  url: "mongodb+srv://user:password@cluster.mongodb.net",
+  id: 'mongodb-storage-01',
+  uri: "mongodb+srv://user:password@cluster.mongodb.net",
   dbName: "mastra_storage",
 });
 
 // Using connection string with options
 const store2 = new MongoDBStore({
-  url: "mongodb+srv://user:password@cluster.mongodb.net",
+  id: 'mongodb-storage-02',
+  uri: "mongodb+srv://user:password@cluster.mongodb.net",
   dbName: "mastra_storage",
   options: {
     retryWrites: true,
@@ -1011,7 +1017,8 @@ import { Mastra } from "@mastra/core";
 import { MongoDBStore } from "@mastra/mongodb";
 
 const storage = new MongoDBStore({
-  url: process.env.MONGODB_URL,
+  id: 'mongodb-storage',
+  uri: process.env.MONGODB_URI,
   dbName: process.env.MONGODB_DATABASE,
 });
 
@@ -1027,7 +1034,7 @@ import { MongoDBStore } from "@mastra/mongodb";
 
 const storage = new MongoDBStore({
   id: 'mongodb-storage',
-  url: process.env.MONGODB_URL,
+  uri: process.env.MONGODB_URI,
   dbName: process.env.MONGODB_DATABASE,
 });
 
@@ -1052,7 +1059,8 @@ MongoDB storage includes built-in vector search capabilities for AI applications
 import { MongoDBVector } from "@mastra/mongodb";
 
 const vectorStore = new MongoDBVector({
-  url: process.env.MONGODB_URL,
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
   dbName: process.env.MONGODB_DATABASE,
 });
 
@@ -1112,13 +1120,11 @@ export const mongodbAgent = new Agent({
   model: "openai/gpt-5.1",
   memory: new Memory({
     storage: new MongoDBStore({
-      url: process.env.MONGODB_URI!,
+      uri: process.env.MONGODB_URI!,
       dbName: process.env.MONGODB_DB_NAME!,
     }),
     options: {
-      threads: {
-        generateTitle: true,
-      },
+      generateTitle: true,
     },
   }),
 });
@@ -1395,6 +1401,7 @@ import { Mastra } from "@mastra/core";
 import { PostgresStore } from "@mastra/pg";
 
 const storage = new PostgresStore({
+  id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 });
 
@@ -1441,6 +1448,75 @@ 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`.
+
+> **Note:**
+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

package/dist/docs/streaming/04-reference.md

@@ -298,6 +298,11 @@ for await (const chunk of stream.fullStream) {
       break;
     case "finish":
       console.log(`Done! Reason: $`);
+      // Access response messages with any metadata added by output processors
+      const uiMessages = chunk.payload.response?.uiMessages;
+      if (uiMessages) {
+        console.log("Response messages:", uiMessages);
+      }
       break;
   }
 }
@@ -546,7 +551,7 @@ await agent.streamLegacy("message for agent", {
 
 > **Note:**
 
-The new `.stream()` method offers enhanced capabilities including AI SDK v5 compatibility, better structured output handling, and improved callback system. See the [migration guide](https://mastra.ai/guides/v1/migrations/vnext-to-standard-apis) for detailed migration instructions.
+The new `.stream()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved callback system. See the [migration guide](https://mastra.ai/guides/v1/migrations/vnext-to-standard-apis) for detailed migration instructions.
 
 ### Quick Migration Example