@mastra/memory 1.0.0-beta.8 → 1.0.0

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

@@ -0,0 +1,1139 @@
+# Storage API Reference
+
+> API reference for storage - 5 entries
+
+
+---
+
+## Reference: DynamoDB Storage
+
+> Documentation for the DynamoDB storage implementation in Mastra, using a single-table design with ElectroDB.
+
+The DynamoDB storage implementation provides a scalable and performant NoSQL database solution for Mastra, leveraging a single-table design pattern with [ElectroDB](https://electrodb.dev/).
+
+## Features
+
+- Efficient single-table design for all Mastra storage needs
+- Based on ElectroDB for type-safe DynamoDB access
+- Support for AWS credentials, regions, and endpoints
+- Compatible with AWS DynamoDB Local for development
+- Stores Thread, Message, Trace, Eval, and Workflow data
+- Optimized for serverless environments
+- Configurable TTL (Time To Live) for automatic data expiration per entity type
+
+## Installation
+
+```bash
+npm install @mastra/dynamodb@beta
+# or
+pnpm add @mastra/dynamodb@beta
+# or
+yarn add @mastra/dynamodb@beta
+```
+
+## Prerequisites
+
+Before using this package, you **must** create a DynamoDB table with a specific structure, including primary keys and Global Secondary Indexes (GSIs). This adapter expects the DynamoDB table and its GSIs to be provisioned externally.
+
+Detailed instructions for setting up the table using AWS CloudFormation or AWS CDK are available in [TABLE_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md). Please ensure your table is configured according to those instructions before proceeding.
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { Memory } from "@mastra/memory";
+import { DynamoDBStore } from "@mastra/dynamodb";
+
+// Initialize the DynamoDB storage
+const storage = new DynamoDBStore({
+  id: "dynamodb", // Unique identifier for this storage instance
+  config: {
+    tableName: "mastra-single-table", // Name of your DynamoDB table
+    region: "us-east-1", // Optional: AWS region, defaults to 'us-east-1'
+    // endpoint: "http://localhost:8000", // Optional: For local DynamoDB
+    // credentials: { accessKeyId: "YOUR_ACCESS_KEY", secretAccessKey: "YOUR_SECRET_KEY" } // Optional
+  },
+});
+
+// Example: Initialize Memory with DynamoDB storage
+const memory = new Memory({
+  storage,
+  options: {
+    lastMessages: 10,
+  },
+});
+```
+
+### Local Development with DynamoDB Local
+
+For local development, you can use [DynamoDB Local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html).
+
+1.  **Run DynamoDB Local (e.g., using Docker):**
+
+    ```bash
+    docker run -p 8000:8000 amazon/dynamodb-local
+    ```
+
+2.  **Configure `DynamoDBStore` to use the local endpoint:**
+
+    ```typescript
+    import { DynamoDBStore } from "@mastra/dynamodb";
+
+    const storage = new DynamoDBStore({
+      id: "dynamodb-local",
+      config: {
+        tableName: "mastra-single-table", // Ensure this table is created in your local DynamoDB
+        region: "localhost", // Can be any string for local, 'localhost' is common
+        endpoint: "http://localhost:8000",
+        // For DynamoDB Local, credentials are not typically required unless configured.
+        // If you've configured local credentials:
+        // credentials: { accessKeyId: "fakeMyKeyId", secretAccessKey: "fakeSecretAccessKey" }
+      },
+    });
+    ```
+
+    You will still need to create the table and GSIs in your local DynamoDB instance, for example, using the AWS CLI pointed to your local endpoint.
+
+## Parameters
+
+## TTL (Time To Live) Configuration
+
+DynamoDB TTL allows you to automatically delete items after a specified time period. This is useful for:
+
+- **Cost optimization**: Automatically remove old data to reduce storage costs
+- **Data lifecycle management**: Implement retention policies for compliance
+- **Performance**: Prevent tables from growing indefinitely
+- **Privacy compliance**: Automatically purge personal data after specified periods
+
+### Enabling TTL
+
+To use TTL, you must:
+
+1. **Configure TTL in DynamoDBStore** (shown below)
+2. **Enable TTL on your DynamoDB table** via AWS Console or CLI, specifying the attribute name (default: `ttl`)
+
+```typescript
+import { DynamoDBStore } from "@mastra/dynamodb";
+
+const storage = new DynamoDBStore({
+  name: "dynamodb",
+  config: {
+    tableName: "mastra-single-table",
+    region: "us-east-1",
+    ttl: {
+      // Messages expire after 30 days
+      message: {
+        enabled: true,
+        defaultTtlSeconds: 30 * 24 * 60 * 60, // 30 days
+      },
+      // Threads expire after 90 days
+      thread: {
+        enabled: true,
+        defaultTtlSeconds: 90 * 24 * 60 * 60, // 90 days
+      },
+      // Traces expire after 7 days with custom attribute name
+      trace: {
+        enabled: true,
+        attributeName: "expiresAt", // Custom TTL attribute
+        defaultTtlSeconds: 7 * 24 * 60 * 60, // 7 days
+      },
+      // Workflow snapshots don't expire
+      workflow_snapshot: {
+        enabled: false,
+      },
+    },
+  },
+});
+```
+
+### Supported Entity Types
+
+TTL can be configured for these entity types:
+
+| Entity | Description |
+|--------|-------------|
+| `thread` | Conversation threads |
+| `message` | Messages within threads |
+| `trace` | Observability traces |
+| `eval` | Evaluation results |
+| `workflow_snapshot` | Workflow state snapshots |
+| `resource` | User/resource data |
+| `score` | Scoring results |
+
+### TTL Entity Configuration
+
+Each entity type accepts the following configuration:
+
+### Enabling TTL on Your DynamoDB Table
+
+After configuring TTL in your code, you must enable TTL on the DynamoDB table itself:
+
+**Using AWS CLI:**
+
+```bash
+aws dynamodb update-time-to-live \
+  --table-name mastra-single-table \
+  --time-to-live-specification "Enabled=true, AttributeName=ttl"
+```
+
+**Using AWS Console:**
+
+1. Go to the DynamoDB console
+2. Select your table
+3. Go to "Additional settings" tab
+4. Under "Time to Live (TTL)", click "Manage TTL"
+5. Enable TTL and specify the attribute name (default: `ttl`)
+
+> **Note**: DynamoDB deletes expired items within 48 hours after expiration. Items remain queryable until actually deleted.
+
+## AWS IAM Permissions
+
+The IAM role or user executing the code needs appropriate permissions to interact with the specified DynamoDB table and its indexes. Below is a sample policy. Replace `${YOUR_TABLE_NAME}` with your actual table name and `${YOUR_AWS_REGION}` and `${YOUR_AWS_ACCOUNT_ID}` with appropriate values.
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "dynamodb:DescribeTable",
+        "dynamodb:GetItem",
+        "dynamodb:PutItem",
+        "dynamodb:UpdateItem",
+        "dynamodb:DeleteItem",
+        "dynamodb:Query",
+        "dynamodb:Scan",
+        "dynamodb:BatchGetItem",
+        "dynamodb:BatchWriteItem"
+      ],
+      "Resource": [
+        "arn:aws:dynamodb:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:table/${YOUR_TABLE_NAME}",
+        "arn:aws:dynamodb:${YOUR_AWS_REGION}:${YOUR_AWS_ACCOUNT_ID}:table/${YOUR_TABLE_NAME}/index/*"
+      ]
+    }
+  ]
+}
+```
+
+## Key Considerations
+
+Before diving into the architectural details, keep these key points in mind when working with the DynamoDB storage adapter:
+
+- **External Table Provisioning:** This adapter _requires_ you to create and configure the DynamoDB table and its Global Secondary Indexes (GSIs) yourself, prior to using the adapter. Follow the guide in [TABLE_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md).
+- **Single-Table Design:** All Mastra data (threads, messages, etc.) is stored in one DynamoDB table. This is a deliberate design choice optimized for DynamoDB, differing from relational database approaches.
+- **Understanding GSIs:** Familiarity with how the GSIs are structured (as per `TABLE_SETUP.md`) is important for understanding data retrieval and potential query patterns.
+- **ElectroDB:** The adapter uses ElectroDB to manage interactions with DynamoDB, providing a layer of abstraction and type safety over raw DynamoDB operations.
+
+## Architectural Approach
+
+This storage adapter utilizes a **single-table design pattern** leveraging [ElectroDB](https://electrodb.dev/), a common and recommended approach for DynamoDB. This differs architecturally from relational database adapters (like `@mastra/pg` or `@mastra/libsql`) that typically use multiple tables, each dedicated to a specific entity (threads, messages, etc.).
+
+Key aspects of this approach:
+
+- **DynamoDB Native:** The single-table design is optimized for DynamoDB's key-value and query capabilities, often leading to better performance and scalability compared to mimicking relational models.
+- **External Table Management:** Unlike some adapters that might offer helper functions to create tables via code, this adapter **expects the DynamoDB table and its associated Global Secondary Indexes (GSIs) to be provisioned externally** before use. Please refer to [TABLE_SETUP.md](https://github.com/mastra-ai/mastra/blob/main/stores/dynamodb/TABLE_SETUP.md) for detailed instructions using tools like AWS CloudFormation or CDK. The adapter focuses solely on interacting with the pre-existing table structure.
+- **Consistency via Interface:** While the underlying storage model differs, this adapter adheres to the same `MastraStorage` interface as other adapters, ensuring it can be used interchangeably within the Mastra `Memory` component.
+
+### Mastra Data in the Single Table
+
+Within the single DynamoDB table, different Mastra data entities (such as Threads, Messages, Traces, Evals, and Workflows) are managed and distinguished using ElectroDB. ElectroDB defines specific models for each entity type, which include unique key structures and attributes. This allows the adapter to store and retrieve diverse data types efficiently within the same table.
+
+For example, a `Thread` item might have a primary key like `THREAD#<threadId>`, while a `Message` item belonging to that thread might use `THREAD#<threadId>` as a partition key and `MESSAGE#<messageId>` as a sort key. The Global Secondary Indexes (GSIs), detailed in `TABLE_SETUP.md`, are strategically designed to support common access patterns across these different entities, such as fetching all messages for a thread or querying traces associated with a particular workflow.
+
+### Advantages of Single-Table Design
+
+This implementation uses a single-table design pattern with ElectroDB, which offers several advantages within the context of DynamoDB:
+
+1.  **Lower cost (potentially):** Fewer tables can simplify Read/Write Capacity Unit (RCU/WCU) provisioning and management, especially with on-demand capacity.
+2.  **Better performance:** Related data can be co-located or accessed efficiently through GSIs, enabling fast lookups for common access patterns.
+3.  **Simplified administration:** Fewer distinct tables to monitor, back up, and manage.
+4.  **Reduced complexity in access patterns:** ElectroDB helps manage the complexity of item types and access patterns on a single table.
+5.  **Transaction support:** DynamoDB transactions can be used across different "entity" types stored within the same table if needed.
+
+---
+
+## Reference: libSQL Storage
+
+> Documentation for the libSQL storage implementation in Mastra.
+
+[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/v1/vectors/libsql) which covers embeddings and vector search.
+
+## Installation
+
+Storage providers must be installed as separate packages:
+
+```bash
+npm install @mastra/libsql@beta
+```
+
+## 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",
+    }),
+  }),
+});
+```
+
+> **Note:**
+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:",
+})
+```
+> **Note:**
+In-memory storage resets when the process changes. Only suitable for development.
+
+## Options
+
+## Initialization
+
+When you pass storage to the Mastra class, `init()` is called automatically to create the [core schema](https://mastra.ai/reference/v1/storage/overview#core-schema):
+
+```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: "..." });
+```
+
+---
+
+## Reference: MongoDB Storage
+
+> Documentation for the MongoDB storage implementation in Mastra.
+
+The MongoDB storage implementation provides a scalable storage solution using MongoDB databases with support for both document storage and vector operations.
+
+## Installation
+
+```bash
+npm install @mastra/mongodb@beta
+```
+
+## 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
+
+> **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: "..." });
+```
+
+> **Note:**
+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 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({
+      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 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);
+}
+```
+
+---
+
+## Reference: PostgreSQL Storage
+
+> Documentation for the PostgreSQL storage implementation in Mastra.
+
+The PostgreSQL storage implementation provides a production-ready storage solution using PostgreSQL databases.
+
+## Installation
+
+```bash
+npm install @mastra/pg@beta
+```
+
+## Usage
+
+```typescript
+import { PostgresStore } from "@mastra/pg";
+
+const storage = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+});
+```
+
+## Parameters
+
+## Constructor Examples
+
+You can instantiate `PostgresStore` in the following ways:
+
+```ts
+import { PostgresStore } from "@mastra/pg";
+
+// Using a connection string only
+const store1 = new PostgresStore({
+  id: 'pg-storage-1',
+  connectionString: "postgresql://user:password@localhost:5432/mydb",
+});
+
+// Using a connection string with a custom schema name
+const store2 = new PostgresStore({
+  id: 'pg-storage-2',
+  connectionString: "postgresql://user:password@localhost:5432/mydb",
+  schemaName: "custom_schema", // optional
+});
+
+// Using individual connection parameters
+const store4 = new PostgresStore({
+  id: 'pg-storage-3',
+  host: "localhost",
+  port: 5432,
+  database: "mydb",
+  user: "user",
+  password: "password",
+});
+
+// Individual parameters with schemaName
+const store5 = new PostgresStore({
+  id: 'pg-storage-4',
+  host: "localhost",
+  port: 5432,
+  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 { PostgresStore } from "@mastra/pg";
+
+const storage = new PostgresStore({
+  id: 'pg-storage',
+  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 { PostgresStore } from "@mastra/pg";
+
+const storage = new PostgresStore({
+  id: 'pg-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: "..." });
+```
+
+> **Note:**
+If `init()` is not called, tables won't be created and storage operations will fail silently or throw errors.
+
+### Direct Database and Pool Access
+
+`PostgresStore` exposes both the underlying database object and the pg-promise instance as public fields:
+
+```typescript
+store.db; // pg-promise database instance
+store.pgp; // pg-promise main 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 PostgresStore methods.
+
+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
+
+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 index management to optimize query performance.
+
+### Default Indexes
+
+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_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 improve performance for filtered queries with sorting, including `dateRange` filters on message queries.
+
+### Configuring Indexes
+
+You can control index creation via constructor options:
+
+```typescript
+import { PostgresStore } from "@mastra/pg";
+
+// Skip default indexes (manage indexes separately)
+const store = new PostgresStore({
+  id: 'pg-storage',
+  connectionString: process.env.DATABASE_URL,
+  skipDefaultIndexes: true,
+});
+
+// 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 advanced index types, you can specify additional options:
+
+- `unique: true` for unique constraints
+- `where: 'condition'` for partial indexes
+- `method: 'brin'` for time-series data
+- `storage: { fillfactor: 90 }` for update-heavy tables
+- `concurrent: true` for non-blocking creation (default)
+
+### Index Options
+
+### Schema-Specific Indexes
+
+When using custom schemas, index names are prefixed with the schema name:
+
+```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
+```
+
+### 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
+
+PostgreSQL offers different index types optimized for specific scenarios:
+
+| Index Type          | Best For                                | Storage    | Speed                      |
+| ------------------- | --------------------------------------- | ---------- | -------------------------- |
+| **btree** (default) | Range queries, sorting, general purpose | Moderate   | Fast                       |
+| **hash**            | Equality comparisons only               | Small      | Very fast for `=`          |
+| **gin**             | JSONB, arrays, full-text search         | Large      | Fast for contains          |
+| **gist**            | Geometric data, full-text search        | Moderate   | Fast for nearest-neighbor  |
+| **spgist**          | Non-balanced data, text patterns        | Small      | Fast for specific patterns |
+| **brin**            | Large tables with natural ordering      | Very small | Fast for ranges            |
+
+---
+
+## Reference: Upstash Storage
+
+> Documentation for the Upstash storage implementation in Mastra.
+
+The Upstash storage implementation provides a serverless-friendly storage solution using Upstash's Redis-compatible key-value store.
+
+> **Note:**
+
+**Important:** When using Mastra with Upstash, the pay-as-you-go model can result in unexpectedly high costs due to the high volume of Redis commands generated during agent conversations. We strongly recommend using a **fixed pricing plan** for predictable costs. See [Upstash pricing](https://upstash.com/pricing/redis) for details and [GitHub issue #5850](https://github.com/mastra-ai/mastra/issues/5850) for context.
+
+## Installation
+
+```bash
+npm install @mastra/upstash@beta
+```
+
+## Usage
+
+```typescript
+import { UpstashStore } from "@mastra/upstash";
+
+const storage = new UpstashStore({
+  id: 'upstash-storage',
+  url: process.env.UPSTASH_URL,
+  token: process.env.UPSTASH_TOKEN,
+});
+```
+
+## Parameters
+
+## Additional Notes
+
+### Key Structure
+
+The Upstash storage implementation uses a key-value structure:
+
+- Thread keys: `{prefix}thread:{threadId}`
+- Message keys: `{prefix}message:{messageId}`
+- Metadata keys: `{prefix}metadata:{entityId}`
+
+### Serverless Benefits
+
+Upstash storage is particularly well-suited for serverless deployments:
+
+- No connection management needed
+- Pay-per-request pricing
+- Global replication options
+- Edge-compatible
+
+### Data Persistence
+
+Upstash provides:
+
+- Automatic data persistence
+- Point-in-time recovery
+- Cross-region replication options
+
+### Performance Considerations
+
+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);
+}
+```