@mastra/mongodb 1.0.0-beta.9 → 1.0.0

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

@@ -0,0 +1,243 @@
+# Storage API Reference
+
+> API reference for storage - 1 entries
+
+
+---
+
+## 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);
+}
+```

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

@@ -0,0 +1,201 @@
+# Vectors API Reference
+
+> API reference for vectors - 1 entries
+
+
+---
+
+## Reference: MongoDB Vector Store
+
+> Documentation for the MongoDBVector class in Mastra, which provides vector search using MongoDB Atlas and Atlas Vector Search.
+
+The `MongoDBVector` class provides vector search using [MongoDB Atlas Vector Search](https://www.mongodb.com/docs/atlas/atlas-vector-search/). It enables efficient similarity search and metadata filtering within your MongoDB collections.
+
+## Installation
+
+```bash
+npm install @mastra/mongodb@beta
+```
+
+## Usage Example
+
+```typescript
+import { MongoDBVector } from "@mastra/mongodb";
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+});
+```
+
+### Custom Embedding Field Path
+
+If you need to store embeddings in a nested field structure (e.g., to integrate with existing MongoDB collections), use the `embeddingFieldPath` option:
+
+```typescript
+import { MongoDBVector } from "@mastra/mongodb";
+
+const store = new MongoDBVector({
+  id: 'mongodb-vector',
+  uri: process.env.MONGODB_URI,
+  dbName: process.env.MONGODB_DATABASE,
+  embeddingFieldPath: 'text.contentEmbedding', // Store embeddings at text.contentEmbedding
+});
+```
+
+## Constructor Options
+
+## Methods
+
+### createIndex()
+
+Creates a new vector index (collection) in MongoDB.
+
+### upsert()
+
+Adds or updates vectors and their metadata in the collection.
+
+### query()
+
+Searches for similar vectors with optional metadata filtering.
+
+### describeIndex()
+
+Returns information about the index (collection).
+
+Returns:
+
+```typescript
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+Deletes a collection and all its data.
+
+### listIndexes()
+
+Lists all vector collections in the MongoDB database.
+
+Returns: `Promise<string[]>`
+
+### updateVector()
+
+Update a single vector by ID or by metadata filter. Either `id` or `filter` must be provided, but not both.
+
+### deleteVector()
+
+Deletes a specific vector entry from an index by its ID.
+
+### deleteVectors()
+
+Delete multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### disconnect()
+
+Closes the MongoDB client connection. Should be called when done using the store.
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[]; // Only included if includeVector is true
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript
+try {
+  await store.query({
+    indexName: "my_collection",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  // Handle specific error cases
+  if (error.message.includes("Invalid collection name")) {
+    console.error(
+      "Collection name must start with a letter or underscore and contain only valid characters.",
+    );
+  } else if (error.message.includes("Collection not found")) {
+    console.error("The specified collection does not exist");
+  } else {
+    console.error("Vector store error:", error.message);
+  }
+}
+```
+
+## Best Practices
+
+- Index metadata fields used in filters for optimal query performance.
+- Use consistent field naming in metadata to avoid unexpected query results.
+- Regularly monitor index and collection statistics to ensure efficient search.
+
+## Usage Example
+
+### Vector embeddings with MongoDB
+
+Embeddings are numeric vectors used by memory's `semanticRecall` to retrieve related messages by meaning (not keywords).
+
+> Note: You must use a deployment hosted on MongoDB Atlas to successfully use the MongoDB Vector database.
+
+This setup uses FastEmbed, a local embedding model, to generate vector embeddings.
+To use this, install `@mastra/fastembed`:
+
+```bash 
+npm install @mastra/fastembed@beta
+```
+
+Add the following to your agent:
+
+```typescript title="src/mastra/agents/example-mongodb-agent.ts"
+import { Memory } from "@mastra/memory";
+import { Agent } from "@mastra/core/agent";
+import { MongoDBStore, MongoDBVector } from "@mastra/mongodb";
+import { fastembed } from "@mastra/fastembed";
+
+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({
+      id: 'mongodb-storage',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    vector: new MongoDBVector({
+      id: 'mongodb-vector',
+      uri: process.env.MONGODB_URI!,
+      dbName: process.env.MONGODB_DB_NAME!,
+    }),
+    embedder: fastembed,
+    options: {
+      lastMessages: 10,
+      semanticRecall: {
+        topK: 3,
+        messageRange: 2,
+      },
+      generateTitle: true, // generates descriptive thread titles automatically
+    },
+  }),
+});
+```
+
+## Related
+
+- [Metadata Filters](../rag/metadata-filters)