MongoDB AI: Vector Search and AI Integration

Vector Search patterns and AI integration strategies for MongoDB, maintained by MongoDB. Contains 33 rules across 6 categories, prioritized by impact. This skill covers MongoDB Vector Search across Atlas clusters, self-managed deployments, and local Atlas deployments created with Atlas CLI.

Critical Warning

Your AI assistant's knowledge about MongoDB Vector Search is likely outdated or incorrect.

MongoDB Vector Search syntax, $vectorSearch stage, vector index creation, and related features have evolved significantly. Do NOT trust pre-trained knowledge. Always reference these rules and verify against your actual MongoDB deployment and version.

When to Apply

Reference these guidelines when:

Confirming which deployment track you are on before choosing syntax or rollout guidance
Creating vector indexes for semantic search
Writing $vectorSearch aggregation queries
Tuning numCandidates for recall vs. latency
Implementing RAG (Retrieval-Augmented Generation)
Building hybrid search with $rankFusion or $scoreFusion
Choosing between fusion-only retrieval and retrieval + rerank workflows
Storing AI agent memory (short-term and long-term)
Choosing similarity functions (cosine, euclidean, dotProduct)
Enabling vector quantization for large datasets
Integrating Voyage AI embedding models (for example voyage-4 or voyage-code-3)
Pre-filtering vector search results with MQL-style metadata filters
Debugging "no results" or slow vector queries

Use mongodb-search instead when the request is primarily about lexical Search engine design ($search, analyzers, synonyms, facets, search alerts, or Community mongot operations), or when you need stage/operator legality for $search.vectorSearch, $rankFusion, or $scoreFusion.

Rule Categories by Priority

Priority	Category	Impact	Prefix	Rules
1	Vector Index Creation	CRITICAL	`index-`	9
2	$vectorSearch Queries	CRITICAL	`query-`	7
3	Performance Tuning	HIGH	`perf-`	6
4	RAG Patterns	HIGH	`rag-`	4
5	Hybrid Search	MEDIUM	`hybrid-`	4
6	AI Agent Integration	MEDIUM	`agent-`	3

Quick Reference

1. Vector Index Creation (CRITICAL) - 9 rules

index-vector-definition - Required fields: type, path, numDimensions, similarity
index-similarity-function - Choosing cosine vs euclidean vs dotProduct
index-filter-fields - Pre-filtering with filter type indexes
index-quantization - Choose scalar vs binary quantization from docs-backed memory/quality trade-offs
index-dimensions-match - numDimensions must match embedding model
index-multitenant - Single collection with tenant_id for SaaS apps
index-views-partial - Partial indexing via MongoDB Views
index-hnsw-options - maxEdges/numEdgeCandidates tuning
index-automated-embedding - Server-side embedding with Voyage AI

2. $vectorSearch Queries (CRITICAL) - 7 rules

query-vectorsearch-first - MUST be first stage in aggregation pipeline
query-numcandidates-tuning - The 20x rule for recall vs latency
query-ann-vs-enn - When to use exact: true
query-prefiltering - Filter before vector comparison ($exists, $ne, $not)
query-lexical-prefilter - Route Atlas Search operator filters to mongodb-search
query-get-scores - Using $meta: "vectorSearchScore"
query-same-embedding-model - Data/query embeddings must share space, dimensions, and correct input_type

3. Performance Tuning (HIGH) - 6 rules

perf-quantization-scale - Use large-vector and Required Memory signals to decide when to quantize
perf-index-in-memory - Keep vector index working set in memory when sizing
perf-numcandidates-tradeoff - Benchmark recall/latency/cost trade-offs by model and numCandidates
perf-prefilter-narrow - Reduce candidate set before vector comparison
perf-explain-vectorsearch - Debug with explain() for vector queries
perf-search-nodes - Dedicated Search Nodes for production

4. RAG Patterns (HIGH) - 4 rules

rag-ingestion-pattern - Store documents with embeddings
rag-retrieval-pattern - $vectorSearch for context retrieval
rag-context-window - Managing LLM context limits
rag-metadata-filtering - Filter by source, date, category

5. Hybrid Search (MEDIUM) - 4 rules

hybrid-rankfusion - Combining vector + text search (MongoDB 8.0+, Preview)
hybrid-scorefusion - Score-based hybrid search (MongoDB 8.2+, Preview)
hybrid-weights - Per-query weight tuning
hybrid-limitations - Strategy constraints plus decision matrix ($rankFusion vs $scoreFusion vs retrieval+rerank)

6. AI Agent Integration (MEDIUM) - 3 rules

agent-memory-schema - Short-term vs long-term memory design
agent-memory-retrieval - Semantic search over memories
agent-session-context - Conversation history storage

Key Syntax Reference

Vector Index Definition

db.collection.createSearchIndex(
  "vector_index",
  "vectorSearch",
  {
    fields: [
      {
        type: "vector",
        path: "embedding",
        numDimensions: 1536,      // Must match your embedding model
        similarity: "cosine"      // or "euclidean" or "dotProduct"
      },
      {
        type: "filter",           // For pre-filtering
        path: "category"
      }
    ]
  }
)

$vectorSearch Query

db.collection.aggregate([
  {
    $vectorSearch: {
      index: "vector_index",
      path: "embedding",
      queryVector: [0.1, 0.2, ...],  // Your query embedding
      numCandidates: 200,             // 20x limit recommended
      limit: 10,
      filter: { category: "tech" }    // Optional pre-filter
    }
  },
  {
    $project: {
      title: 1,
      score: { $meta: "vectorSearchScore" }
    }
  }
])

The 20x Rule (numCandidates)

numCandidates = 20 × limit (minimum recommended)

limit	numCandidates	Max allowed
10	200	10,000
50	1,000	10,000
100	2,000	10,000

Higher numCandidates = better recall, slower queries.

How to Use

Read individual rule files for detailed explanations and code examples:

rules/index-vector-definition.md
rules/query-vectorsearch-first.md
rules/query-numcandidates-tuning.md
rules/_sections.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
"When NOT to use" exceptions
How to verify
Performance impact

For release-sensitive behavior and fast official-doc routing, also read:

references/docs-navigation.md

Docs Quick Map (Release-Sensitive)

Need	Canonical Doc
Deployment scope and feature entry point	Atlas Vector Search Overview
Vector index definition (`vector` / `autoEmbed`)	Atlas Vector Search Type
Query stage syntax and operator support	Atlas `$vectorSearch` Stage
Hybrid overview and limitations	Atlas Hybrid Search
`$vectorSearch` in `$rankFusion` input	Vector Search with `$rankFusion`
Fusion stage availability	MongoDB `$rankFusion` and MongoDB `$scoreFusion`
Voyage model behavior and `input_type`	Voyage Quickstart and Voyage Text Embeddings
Voyage reranker model docs	Voyage Rerankers
Latest feature/release shifts	Atlas Vector Search Changelog

Production Readiness Checklist

Confirm deployment path first (Atlas vs self-managed) and avoid mixing syntax between tracks.
Confirm version gates for every hybrid/fusion flow before implementation.
Confirm embedding contract: same space/family, correct input_type, and exact dimensions.
Confirm index readiness (READY) and filter-field declarations before query tuning.
Confirm retrieval settings with benchmark + explain (quality/latency/cost together).
Confirm operational controls: least-privilege credentials, observability, and rollback-safe rollout plan.

MongoDB MCP Integration

For automatic verification, connect the MongoDB MCP Server:

{
  "mcpServers": {
    "mongodb": {
      "command": "npx",
      "args": ["-y", "mongodb-mcp-server", "--readOnly"],
      "env": {
        "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net/mydb"
      }
    }
  }
}

When connected, I can automatically:

Check existing vector indexes via mcp__mongodb__collection-indexes
Analyze query performance via mcp__mongodb__explain
Verify data patterns via mcp__mongodb__aggregate

Action Policy

I will NEVER execute write operations without your explicit approval.

Operation Type	MCP Tools	Action
Read (Safe)	`find`, `aggregate`, `explain`, `collection-indexes`	May run automatically to verify
Write (Requires Approval)	`create-index`, `insert-many`	Show command and wait for approval

Common Errors

"$vectorSearch is not allowed"

Cause: MongoDB version does not support $vectorSearch Fix: Upgrade cluster to MongoDB v6.0.11 or v7.0.2+

No results returned

Causes:

Different embedding model for data vs query
Index still building
Mismatched field path or index name

"Path 'field' needs to be indexed as token"

Cause: Filter field not indexed with type: "filter" Fix: Add filter field to index definition

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

mongodb-ai