> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memvid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embedding Models

> Configure embedding models for semantic search in Memvid

Memvid supports multiple embedding models for semantic (vector) search. You can use the built-in BGE-small model for local, offline operation, or connect to external providers like OpenAI, Cohere, or Voyage for higher-quality embeddings.

***

## Overview

Embeddings convert text into dense numerical vectors that capture semantic meaning. Similar concepts produce similar vectors, enabling semantic search (finding documents by meaning rather than exact keywords).

| Provider     | Model                   | Dimensions | Best For                |
| ------------ | ----------------------- | ---------- | ----------------------- |
| **Built-in** | BGE-small-en-v1.5       | 384        | Offline, privacy-first  |
| **Ollama**   | mxbai-embed-large       | 1024       | Local, high quality     |
| **Ollama**   | nomic-embed-text        | 768        | Local, fast             |
| **OpenAI**   | text-embedding-3-small  | 1536       | General purpose         |
| **OpenAI**   | text-embedding-3-large  | 3072       | Highest quality         |
| **Cohere**   | embed-english-v3.0      | 1024       | English documents       |
| **Cohere**   | embed-multilingual-v3.0 | 1024       | Multi-language          |
| **Voyage**   | voyage-3                | 1024       | Code and technical docs |

***

## Built-in Model (Default)

By default, Memvid uses BGE-small-en-v1.5, a lightweight embedding model that runs locally without any API keys.

### Characteristics

* **Dimensions**: 384
* **Size**: \~75 MB (downloaded on first use)
* **Inference**: CPU-based, no GPU required
* **Privacy**: All processing happens locally
* **Offline**: Works without internet after initial download

### Usage

```bash theme={null}
# CLI: Enable embeddings with built-in model
memvid put knowledge.mv2 --input document.pdf --embedding
```

```python theme={null}
# Python SDK
from memvid_sdk import create

mem = create("knowledge.mv2", enable_vec=True, enable_lex=True)
mem.put(
    "Document",
    "docs",
    {},
    text="Your content here",
    enable_embedding=True,
    embedding_model="bge-small",
)
```

```typescript theme={null}
// Node.js SDK
import { create } from '@memvid/sdk';

const mem = await create('knowledge.mv2');
await mem.put({ text: 'Your content here', title: 'Document', enableEmbedding: true });
```

***

## Ollama Embeddings (Local)

Ollama provides high-quality embeddings that run entirely locally on your machine. No API keys, no data leaving your infrastructure, and no usage costs.

### Setup

1. Install Ollama: [ollama.com/download](https://ollama.com/download)
2. Pull an embedding model:

```bash theme={null}
# Recommended: High quality (1024 dimensions)
ollama pull mxbai-embed-large

# Alternative: Faster, smaller (768 dimensions)
ollama pull nomic-embed-text
```

### Python SDK

```python theme={null}
from memvid_sdk import create
from memvid_sdk.embeddings import OllamaEmbeddings

# Initialize embedder (uses localhost:11434 by default)
embedder = OllamaEmbeddings(model='mxbai-embed-large')
print(f"Model: {embedder.model_name} ({embedder.dimension} dimensions)")

# Create memory with vector index
mem = create('knowledge.mv2', enable_vec=True, enable_lex=True)

# Store with embeddings
documents = [
    {"title": "Doc 1", "label": "kb", "text": "Machine learning fundamentals..."},
    {"title": "Doc 2", "label": "kb", "text": "Deep neural networks..."},
]
frame_ids = mem.put_many(documents, embedder=embedder)

# Search with query embedding
query = "How do neural networks work?"
results = mem.find(query, k=5, mode="sem", embedder=embedder)
```

### Node.js SDK

```typescript theme={null}
import { create, OllamaEmbeddings } from '@memvid/sdk';

// Initialize embedder
const embedder = new OllamaEmbeddings({ model: 'mxbai-embed-large' });
console.log(`Model: ${embedder.modelName} (${embedder.dimension} dimensions)`);

// Create memory
const mem = await create('knowledge.mv2', 'basic', { enableLex: true, enableVec: true });

// Ingest with embeddings
for (const doc of documents) {
  const embedding = await embedder.embedQuery(doc.text);
  await mem.put({
    title: doc.title,
    text: doc.text,
    label: doc.label,
    embedding,
    embeddingIdentity: { provider: 'ollama', model: 'mxbai-embed-large', dimension: 1024 },
  });
}
await mem.seal();

// Search
const queryEmbedding = await embedder.embedQuery('How do neural networks work?');
const results = await mem.find('neural networks', { k: 5, mode: 'auto', queryEmbedding });
```

### Supported Models

| Model                        | Dimensions | Speed   | Quality | Use Case                   |
| ---------------------------- | ---------- | ------- | ------- | -------------------------- |
| `mxbai-embed-large`          | 1024       | Medium  | Best    | Production, high accuracy  |
| `nomic-embed-text`           | 768        | Fast    | Good    | General purpose            |
| `bge-m3`                     | 1024       | Medium  | Best    | Multilingual               |
| `bge-large`                  | 1024       | Medium  | Great   | English documents          |
| `snowflake-arctic-embed`     | 1024       | Medium  | Great   | Retrieval-focused          |
| `snowflake-arctic-embed:m`   | 768        | Fast    | Good    | Balanced                   |
| `snowflake-arctic-embed:s`   | 384        | Fastest | OK      | Low latency                |
| `all-minilm`                 | 384        | Fastest | OK      | Lightweight                |
| `e5-large`                   | 1024       | Medium  | Great   | General purpose            |
| `jina-embeddings-v2-base-en` | 768        | Fast    | Good    | Long documents (8K tokens) |

### Custom Server

```python theme={null}
# Connect to remote Ollama server
embedder = OllamaEmbeddings(
    model='mxbai-embed-large',
    base_url='http://gpu-server:11434'
)
```

```typescript theme={null}
// Node.js
const embedder = new OllamaEmbeddings({
  model: 'mxbai-embed-large',
  baseUrl: 'http://gpu-server:11434',
});
```

### Environment Variables

| Variable      | Description                                           |
| ------------- | ----------------------------------------------------- |
| `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |

***

## OpenAI Embeddings

OpenAI's embedding models offer excellent quality for general-purpose semantic search.

### Setup

```bash theme={null}
export OPENAI_API_KEY=sk-your-key-here
```

### CLI Usage

```bash theme={null}
# Use OpenAI for embeddings
memvid put knowledge.mv2 --input document.pdf --embedding -m openai-small

# Specify exact model
memvid put knowledge.mv2 --input docs/ --embedding -m openai-large
```

### Python SDK

```python theme={null}
from memvid_sdk import create
from memvid_sdk.embeddings import OpenAIEmbeddings

# Initialize embedder
embedder = OpenAIEmbeddings(model='text-embedding-3-small')
print(f"Model: {embedder.model_name} ({embedder.dimension} dimensions)")

# Create memory with vector index
mem = create('knowledge.mv2', enable_vec=True, enable_lex=True)

# Store + embed in batch (vector index required for semantic search)
documents = [
    {"title": "Doc 1", "label": "kb", "text": "Machine learning fundamentals..."},
    {"title": "Doc 2", "label": "kb", "text": "Deep neural networks..."},
]
frame_ids = mem.put_many(documents, embedder=embedder)

# Search with query embedding
query = "How do neural networks work?"
results = mem.find(query, k=5, mode="sem", embedder=embedder)
```

***

## NVIDIA Embeddings

NVIDIA Integrate provides a fast hosted embedding API with OpenAI-compatible shapes.

### Setup

```bash theme={null}
export NVIDIA_API_KEY=nvapi-your-key-here
```

### Python SDK

```python theme={null}
from memvid_sdk import create
from memvid_sdk.embeddings import NvidiaEmbeddings

mem = create("knowledge.mv2", enable_vec=True, enable_lex=True)
embedder = NvidiaEmbeddings(model="nvidia/nv-embed-v1")  # uses NVIDIA_API_KEY

mem.put_many(
    [{"title": "Doc", "label": "kb", "text": "Vector search with NVIDIA embeddings."}],
    embedder=embedder,
)
res = mem.find("nvidia embeddings", mode="sem", embedder=embedder)
```

### Node.js SDK

```typescript theme={null}
import { create, NvidiaEmbeddings } from '@memvid/sdk';

const mem = await create('knowledge.mv2');
const embedder = new NvidiaEmbeddings({ model: 'nvidia/nv-embed-v1' }); // uses NVIDIA_API_KEY
await mem.putMany([{ title: 'Doc', text: 'Vector search with NVIDIA embeddings.' }], { embedder });
const res = await mem.find('nvidia embeddings', { mode: 'sem', embedder });
```

### Node.js SDK

```typescript theme={null}
import { create, OpenAIEmbeddings } from '@memvid/sdk';

// Initialize embedder (uses OPENAI_API_KEY env var)
const embedder = new OpenAIEmbeddings({ model: 'text-embedding-3-small' });
console.log(`Model: ${embedder.modelName} (${embedder.dimension} dimensions)`);

// Create memory
const mem = await create('knowledge.mv2');

// Store + embed in batch (vector index required for semantic search)
await mem.putMany(
  [
    { title: 'Doc 1', text: 'Machine learning fundamentals...' },
    { title: 'Doc 2', text: 'Deep neural networks...' },
  ],
  { embedder }
);
await mem.seal();

// Query using the same embedder (keeps dimensions consistent)
const results = await mem.find('How do neural networks work?', { mode: 'sem', k: 5, embedder });
```

### Model Comparison

| Model                    | Dimensions | Cost             | Quality |
| ------------------------ | ---------- | ---------------- | ------- |
| `text-embedding-3-small` | 1536       | \$0.02/1M tokens | Good    |
| `text-embedding-3-large` | 3072       | \$0.13/1M tokens | Best    |
| `text-embedding-ada-002` | 1536       | \$0.10/1M tokens | Legacy  |

***

## Cohere Embeddings

Cohere offers specialized models for English and multilingual content.

### Setup

```bash theme={null}
export COHERE_API_KEY=your-key-here
```

### Python SDK

```python theme={null}
from memvid_sdk.embeddings import CohereEmbeddings, get_embedder

# Direct initialization
embedder = CohereEmbeddings(model='embed-english-v3.0')

# Or use factory
embedder = get_embedder('cohere', model='embed-multilingual-v3.0')

# Generate embeddings
embeddings = embedder.embed_documents(['Text 1', 'Text 2'])
query_vec = embedder.embed_query('search query')
```

### Node.js SDK

```typescript theme={null}
import { CohereEmbeddings, getEmbedder } from '@memvid/sdk';

// Direct initialization
const embedder = new CohereEmbeddings({ model: 'embed-english-v3.0' });

// Or use factory
const embedder2 = getEmbedder('cohere', { model: 'embed-multilingual-v3.0' });

const embeddings = await embedder.embedDocuments(['Text 1', 'Text 2']);
```

### Model Options

| Model                           | Dimensions | Best For                |
| ------------------------------- | ---------- | ----------------------- |
| `embed-english-v3.0`            | 1024       | English documents       |
| `embed-multilingual-v3.0`       | 1024       | 100+ languages          |
| `embed-english-light-v3.0`      | 384        | Faster, lower cost      |
| `embed-multilingual-light-v3.0` | 384        | Multi-language, lighter |

***

## Voyage Embeddings

Voyage AI specializes in embeddings for code and technical documentation.

### Setup

```bash theme={null}
export VOYAGE_API_KEY=your-key-here
```

### Python SDK

```python theme={null}
from memvid_sdk.embeddings import VoyageEmbeddings

embedder = VoyageEmbeddings(model='voyage-3')
embeddings = embedder.embed_documents(['def hello(): pass', 'function hello() {}'])
```

### Node.js SDK

```typescript theme={null}
import { VoyageEmbeddings } from '@memvid/sdk';

const embedder = new VoyageEmbeddings({ model: 'voyage-code-3' });
const embeddings = await embedder.embedDocuments(['def hello(): pass']);
```

### Model Options

| Model           | Dimensions | Best For        |
| --------------- | ---------- | --------------- |
| `voyage-3`      | 1024       | General purpose |
| `voyage-3-lite` | 512        | Faster, smaller |
| `voyage-code-3` | 1024       | Source code     |

***

## HuggingFace Embeddings (Python)

Use any HuggingFace sentence-transformer model locally.

### Setup

```bash theme={null}
pip install sentence-transformers
```

### Usage

```python theme={null}
from memvid_sdk.embeddings import get_embedder

# Use any sentence-transformers model
embedder = get_embedder('huggingface', model='all-MiniLM-L6-v2')
print(f"Model: {embedder.model_name} ({embedder.dimension} dimensions)")

embeddings = embedder.embed_documents(['Text 1', 'Text 2'])
```

### Popular Models

| Model                       | Dimensions | Size   |
| --------------------------- | ---------- | ------ |
| `all-MiniLM-L6-v2`          | 384        | 80 MB  |
| `all-mpnet-base-v2`         | 768        | 420 MB |
| `multi-qa-MiniLM-L6-cos-v1` | 384        | 80 MB  |

***

## Using External Embeddings with Memvid

The key workflow for external embeddings:

1. **Pick an embedder** (OpenAI/Cohere/Voyage/NVIDIA/etc.)
2. **Ingest with `put_many(..., embedder=...)`** (stores embedding identity metadata)
3. **Query with `find/ask(..., embedder=...)`** (keeps dimensions consistent)

### Batch Ingestion Example

```python theme={null}
from memvid_sdk import create
from memvid_sdk.embeddings import OpenAIEmbeddings

# Setup
embedder = OpenAIEmbeddings()
mem = create('knowledge.mv2', enable_vec=True, enable_lex=True)

documents = [
    {"title": "Doc 1", "label": "research", "text": "Content 1..."},
    {"title": "Doc 2", "label": "research", "text": "Content 2..."},
]
frame_ids = mem.put_many(documents, embedder=embedder)

query = "What is the main finding?"
results = mem.find(query, k=10, mode="sem", embedder=embedder)
```

***

## Vector Compression

For large collections, enable vector compression to reduce storage by \~16x:

```bash theme={null}
# CLI
memvid put knowledge.mv2 --input docs/ --embedding --vector-compression
```

```python theme={null}
# Python
from memvid_sdk import create

mem = create("knowledge.mv2", enable_vec=True, enable_lex=True)
mem.put("Doc", "kb", {}, text="...", enable_embedding=True, vector_compression=True)
```

This uses Product Quantization (PQ) to compress vectors while maintaining search quality.

***

## Environment Variables

| Variable            | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `OLLAMA_HOST`       | Ollama server URL (default: `http://localhost:11434`) |
| `OPENAI_API_KEY`    | OpenAI API key                                        |
| `COHERE_API_KEY`    | Cohere API key                                        |
| `VOYAGE_API_KEY`    | Voyage AI API key                                     |
| `NVIDIA_API_KEY`    | NVIDIA Integrate API key                              |
| `NVIDIA_BASE_URL`   | Optional NVIDIA Integrate base URL override           |
| `GOOGLE_API_KEY`    | Google/Gemini API key                                 |
| `MISTRAL_API_KEY`   | Mistral API key                                       |
| `MEMVID_MODELS_DIR` | Local model cache directory                           |
| `MEMVID_OFFLINE=1`  | Skip model downloads                                  |

***

## Choosing an Embedding Model

### Decision Matrix

| Requirement          | Recommended                                     |
| -------------------- | ----------------------------------------------- |
| Privacy/offline      | Ollama mxbai-embed-large                        |
| Best quality (local) | Ollama mxbai-embed-large                        |
| Best quality (API)   | OpenAI text-embedding-3-large                   |
| Cost-effective       | Ollama (free) or OpenAI text-embedding-3-small  |
| Multi-language       | Ollama bge-m3 or Cohere embed-multilingual-v3.0 |
| Code/technical       | Voyage voyage-code-3                            |
| Fastest local        | Ollama all-minilm                               |
| No setup             | Built-in BGE-small                              |

### Performance Considerations

* **Dimension count** affects storage and search speed
* **API latency** for external providers (batch when possible)
* **Rate limits** vary by provider plan
* **Consistency** - use same model for ingestion and search

***

## Reranking

Memvid can rerank retrieved candidates using a cross-encoder model (auto-downloaded on first use). In the CLI this is applied during `ask` and can be disabled:

```bash theme={null}
memvid ask knowledge.mv2 --question "What is machine learning?" --mode hybrid --no-rerank
```

For `find`, reranking is handled internally; there is no `--rerank` flag.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Indices and Tracks" icon="layer-group" href="/concepts/indexes-and-tracks">
    Learn about lexical, vector, and time indices
  </Card>

  <Card title="Search & Ask" icon="magnifying-glass" href="/cli/search-and-ask">
    Master semantic search queries
  </Card>
</CardGroup>