MongoDB vector store

The MongoDBVector class provides vector search using MongoDB Atlas Vector Search. It enables efficient similarity search and metadata filtering within your MongoDB collections.

Installation

npm install @mastra/mongodb@latest

Usage example

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:

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

<PropertiesTable content={[ { name: 'id', type: 'string', description: 'Unique identifier for this vector store instance', }, { name: 'uri', type: 'string', description: 'MongoDB connection string', }, { name: 'dbName', type: 'string', description: 'Name of the MongoDB database to use', }, { name: 'options', type: 'MongoClientOptions', isOptional: true, description: 'Optional MongoDB client options', }, { name: 'embeddingFieldPath', type: 'string', isOptional: true, defaultValue: 'embedding', description: "Path to the field that stores vector embeddings. Supports nested paths using dot notation (e.g., 'text.contentEmbedding').", }, ]} />

Methods

createIndex()

Creates a new vector index (collection) in MongoDB.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection to create', }, { name: 'dimension', type: 'number', description: 'Vector dimension (must match your embedding model)', }, { name: 'metric', type: "'cosine' | 'euclidean' | 'dotproduct'", isOptional: true, defaultValue: 'cosine', description: 'Distance metric for similarity search', }, ]} />

upsert()

Adds or updates vectors and their metadata in the collection.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection to insert into', }, { name: 'vectors', type: 'number[][]', description: 'Array of embedding vectors', }, { name: 'metadata', type: 'Record<string, any>[]', isOptional: true, description: 'Metadata for each vector', }, { name: 'ids', type: 'string[]', isOptional: true, description: 'Optional vector IDs (auto-generated if not provided)', }, ]} />

query()

Searches for similar vectors with optional metadata filtering.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection to search in', }, { name: 'queryVector', type: 'number[]', description: 'Query vector to find similar vectors for', }, { name: 'topK', type: 'number', isOptional: true, defaultValue: '10', description: 'Number of results to return', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filters (applies to the metadata field)', }, { name: 'documentFilter', type: 'Record<string, any>', isOptional: true, description: 'Filters on original document fields (not just metadata)', }, { name: 'includeVector', type: 'boolean', isOptional: true, defaultValue: 'false', description: 'Whether to include vector data in results', }, { name: 'minScore', type: 'number', isOptional: true, defaultValue: '0', description: 'Minimum similarity score threshold', }, ]} />

describeIndex()

Returns information about the index (collection).

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection to describe', }, ]} />

Returns:

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

Deletes a collection and all its data.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection to delete', }, ]} />

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.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection containing the vector', }, { name: 'id', type: 'string', isOptional: true, description: 'ID of the vector entry to update (mutually exclusive with filter)', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filter to identify vector(s) to update (mutually exclusive with id)', }, { name: 'update', type: 'object', description: 'Update data containing vector and/or metadata', }, { name: 'update.vector', type: 'number[]', isOptional: true, description: 'New vector data to update', }, { name: 'update.metadata', type: 'Record<string, any>', isOptional: true, description: 'New metadata to update', }, ]} />

deleteVector()

Deletes a specific vector entry from an index by its ID.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection containing the vector', }, { name: 'id', type: 'string', description: 'ID of the vector entry to delete', }, ]} />

deleteVectors()

Delete multiple vectors by IDs or by metadata filter. Either ids or filter must be provided, but not both.

<PropertiesTable content={[ { name: 'indexName', type: 'string', description: 'Name of the collection containing the vectors to delete', }, { name: 'ids', type: 'string[]', isOptional: true, description: 'Array of vector IDs to delete (mutually exclusive with filter)', }, { name: 'filter', type: 'Record<string, any>', isOptional: true, description: 'Metadata filter to identify vectors to delete (mutually exclusive with ids)', }, ]} />

disconnect()

Closes the MongoDB client connection. Should be called when done using the store.

Response types

Query results are returned in this format:

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:

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:

npm install @mastra/fastembed@latest

Add the following to your agent:

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.4',
  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