voyageai

name	voyageai
description	Voyage AI embedding and reranking CLI integrated with MongoDB Atlas Vector Search. Use for: generating text embeddings, reranking search results, storing embeddings in Atlas, performing vector similarity search, creating vector search indexes, listing available models, comparing text similarity, bulk ingestion, interactive demos, and learning about AI concepts. Triggers: embed text, generate embeddings, vector search, rerank documents, voyage ai, semantic search, similarity search, store embeddings, atlas vector search, embedding models, cosine similarity, bulk ingest, explain embeddings.
metadata	{"openclaw":{"emoji":"🧭","author":{"name":"Michael Lynn","url":"https://mlynn.org","github":"mrlynn"},"version":"1.4.0","license":"MIT","tags":["embeddings","vector-search","reranking","mongodb","atlas","semantic-search","rag","voyage-ai"],"requires":{"bins":["vai"],"env":["VOYAGE_API_KEY"]},"install":[{"id":"npm","kind":"npm","package":"voyageai-cli","global":true}]}}

🧭 Voyage AI Skill

Uses the vai CLI (voyageai-cli) for Voyage AI embeddings, reranking, and MongoDB Atlas Vector Search. Pure Node.js — no Python required.

Setup

npm install -g voyageai-cli

Environment Variables

Variable	Required For	Description
VOYAGE_API_KEY	embed, rerank, store, search, similarity, ingest, ping	Model API key from MongoDB Atlas
MONGODB_URI	store, search, index, ingest, ping (optional)	Atlas connection string

Get your API key: MongoDB Atlas → AI Models → Create model API key

Command Reference (14 commands)

embed — Generate embeddings

vai embed "What is MongoDB?"
vai embed "search query" --model voyage-4-large --input-type query --dimensions 512
vai embed --file document.txt --input-type document
cat texts.txt | vai embed
vai embed "hello" --output-format array

rerank — Rerank documents

vai rerank --query "database performance" --documents "MongoDB is fast" "SQL is relational"
vai rerank --query "best database" --documents-file candidates.json --top-k 3

store — Embed and store in Atlas

vai store --db mydb --collection docs --field embedding \
  --text "MongoDB Atlas is a cloud database" \
  --metadata '{"source": "docs"}'

# Batch from JSONL
vai store --db mydb --collection docs --field embedding --file documents.jsonl

search — Vector search

vai search --query "cloud database" --db mydb --collection docs \
  --index vector_index --field embedding

# With pre-filter
vai search --query "performance" --db mydb --collection docs \
  --index vector_index --field embedding --filter '{"category": "guides"}' --limit 5

index — Manage vector search indexes

vai index create --db mydb --collection docs --field embedding \
  --dimensions 1024 --similarity cosine --index-name my_index
vai index list --db mydb --collection docs
vai index delete --db mydb --collection docs --index-name my_index

models — List available models

vai models
vai models --type embedding
vai models --type reranking
vai models --json

ping — Test connectivity

vai ping
vai ping --json

config — Manage persistent configuration

vai config set api-key "pa-your-key"
echo "pa-your-key" | vai config set api-key --stdin
vai config get
vai config delete api-key
vai config path
vai config reset

demo — Interactive guided walkthrough

vai demo
vai demo --no-pause
vai demo --skip-pipeline
vai demo --keep

explain — Learn about AI concepts

vai explain                      # List all topics
vai explain embeddings
vai explain reranking
vai explain vector-search
vai explain rag
vai explain cosine-similarity
vai explain two-stage-retrieval
vai explain input-type
vai explain models
vai explain api-keys
vai explain api-access
vai explain batch-processing

similarity — Compare text similarity

vai similarity "MongoDB is a document database" "MongoDB Atlas is a cloud database"
vai similarity "database performance" --against "MongoDB is fast" "PostgreSQL is relational"
vai similarity --file1 doc1.txt --file2 doc2.txt
vai similarity "text A" "text B" --json

ingest — Bulk import with progress

vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding
vai ingest --file data.csv --db myapp --collection docs --field embedding --text-column content
vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding \
  --model voyage-4 --batch-size 100 --input-type document
vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding --dry-run

completions — Shell completion scripts

vai completions bash    # Output bash completion script
vai completions zsh     # Output zsh completion script

# Install bash completions
vai completions bash >> ~/.bashrc && source ~/.bashrc

# Install zsh completions
vai completions zsh > ~/.zsh/completions/_vai

help — Display help

vai help
vai help embed
vai embed --help

Common Workflows

Embed → Store → Search Pipeline

# 1. Store documents
vai store --db myapp --collection articles --field embedding \
  --text "MongoDB Atlas provides a fully managed cloud database" \
  --metadata '{"title": "Atlas Overview"}'

# 2. Create index
vai index create --db myapp --collection articles --field embedding \
  --dimensions 1024 --similarity cosine --index-name article_search

# 3. Search
vai search --query "how does cloud database work" \
  --db myapp --collection articles --index article_search --field embedding

Two-Stage Retrieval (Embed + Rerank)

# 1. Get candidates via vector search
vai search --query "database scaling" --db myapp --collection articles \
  --index article_search --field embedding --limit 20 --json > candidates.json

# 2. Rerank for precision
vai rerank --query "database scaling" --documents-file candidates.json --top-k 5

Bulk Ingest Pipeline

# 1. Validate data (dry run)
vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding --dry-run

# 2. Ingest with progress
vai ingest --file corpus.jsonl --db myapp --collection docs --field embedding

# 3. Create index
vai index create --db myapp --collection docs --field embedding \
  --dimensions 1024 --similarity cosine

Global Flags

Flag	Description
--json	Machine-readable JSON output
--quiet	Suppress non-essential output

References

• Model Catalog — All models with pricing and specs
• Vector Search Patterns — Atlas Vector Search integration guide