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