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

# Embedding Models

> Configure embedding models for semantic search and memory retrieval

CORE uses embedding models to convert text into vector representations for semantic search, memory retrieval, and knowledge graph operations. Vectors are stored in pgvector with a fixed dimension: all embeddings must match the configured `EMBEDDING_MODEL_SIZE`.

## Configuration

```env theme={null}
EMBEDDINGS_PROVIDER=openai          # openai | google | ollama | azure | local
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_MODEL_SIZE=1536           # must match pgvector column dimension
```

## Providers

### OpenAI

Requires `OPENAI_API_KEY`. Works with direct API or proxies via `OPENAI_BASE_URL`.

| Model                    | Dimensions | Notes                                     |
| ------------------------ | ---------- | ----------------------------------------- |
| `text-embedding-3-small` | 1536       | Default. Good balance of cost and quality |
| `text-embedding-3-large` | 3072       | Higher quality, higher cost               |
| `text-embedding-ada-002` | 1536       | Legacy                                    |

```env theme={null}
EMBEDDINGS_PROVIDER=openai
EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_MODEL_SIZE=1536
OPENAI_API_KEY=sk-...
```

### Google Gemini

Requires `GOOGLE_GENERATIVE_AI_API_KEY`. Get a free key from [Google AI Studio](https://aistudio.google.com).

| Model                        | Default Dimensions | Configurable                    | Notes                    |
| ---------------------------- | ------------------ | ------------------------------- | ------------------------ |
| `text-embedding-004`         | 768                | No                              | Stable, production-ready |
| `gemini-embedding-001`       | 3072               | Yes (256, 512, 768, 1024, 3072) | Higher quality           |
| `gemini-embedding-2-preview` | 3072               | Yes (256, 512, 768, 1024, 3072) | Latest, best quality     |

For models with configurable dimensions, `EMBEDDING_MODEL_SIZE` controls the output dimensionality. This lets you match existing pgvector columns without changing the schema.

```env theme={null}
EMBEDDINGS_PROVIDER=google
EMBEDDING_MODEL=gemini-embedding-2-preview
EMBEDDING_MODEL_SIZE=1024
GOOGLE_GENERATIVE_AI_API_KEY=AIza...
```

### Local (in-process, no server)

CORE ships with an in-process embedding backend powered by [`@huggingface/transformers`](https://huggingface.co/docs/transformers.js) v4 + ONNX Runtime. No separate service, no API key, no network — model weights are downloaded once on first boot and cached to disk. Ideal for fully local self-hosts that don't want to run Ollama.

| Model                                                                | Dimensions | Notes                                               |
| -------------------------------------------------------------------- | ---------- | --------------------------------------------------- |
| `nomic-ai/nomic-embed-text-v1.5`                                     | 768        | Recommended. Comparable to `text-embedding-3-small` |
| Any other feature-extraction model published as ONNX on Hugging Face | varies     | Set `EMBEDDING_MODEL` to the repo id                |

```env theme={null}
EMBEDDINGS_PROVIDER=local
EMBEDDING_MODEL=nomic-ai/nomic-embed-text-v1.5
EMBEDDING_MODEL_SIZE=768

# Optional. Defaults to q8 — the sweet spot for CPU inference.
LOCAL_EMBEDDING_DTYPE=q8              # fp32 | fp16 | q8 | q4

# Optional. Where ONNX weights are cached. Defaults to ./data/models.
LOCAL_EMBEDDING_CACHE_DIR=/app/data/models
```

The pipeline is warmed at server startup so the first request doesn't pay the load cost. First-run download progress streams into the server logs (throttled to \~10% per file):

```
[embed:local] initializing pipeline (model=nomic-ai/nomic-embed-text-v1.5, dtype=q8, cache=/app/data/models)
[embed:local] fetching model_quantized.onnx (nomic-ai/nomic-embed-text-v1.5)
[embed:local] downloading model_quantized.onnx: 30% (52.1/172.8 MB)
[embed:local] downloading model_quantized.onnx: 40% (69.5/172.8 MB)
…
[embed:local] pipeline ready (nomic-ai/nomic-embed-text-v1.5)
Local embeddings warmed
```

**Docker persistence** — the hosted `docker-compose.yaml` mounts a named volume `local_models:/app/data/models` so weights survive rebuilds. Without it, every container recreate re-downloads \~150–200 MB.

**Trigger.dev caveat** — memory-ingestion jobs run inside Trigger.dev workers when `QUEUE_PROVIDER=trigger`, not the webapp process. Local embeddings only work end-to-end with `QUEUE_PROVIDER=bullmq`.

### Ollama (Self-Hosted)

Requires a running Ollama instance. No API key needed: fully local and private.

| Model                    | Dimensions | Notes                                    |
| ------------------------ | ---------- | ---------------------------------------- |
| `mxbai-embed-large`      | 1024       | Default for Ollama. Good general-purpose |
| `nomic-embed-text`       | 768        | Lightweight                              |
| `all-minilm`             | 384        | Smallest, fastest                        |
| `snowflake-arctic-embed` | 1024       | High quality for retrieval               |
| `bge-large`              | 1024       | Strong multilingual support              |

Pull the model first:

```bash theme={null}
ollama pull mxbai-embed-large
```

```env theme={null}
EMBEDDINGS_PROVIDER=ollama
EMBEDDING_MODEL=mxbai-embed-large
EMBEDDING_MODEL_SIZE=1024
OLLAMA_URL=http://ollama:11434
```

## Choosing a Model

| Use Case                 | Recommended Model            | Provider | Dimensions |
| ------------------------ | ---------------------------- | -------- | ---------- |
| Best quality (cloud)     | `gemini-embedding-2-preview` | Google   | 3072       |
| Low cost (cloud)         | `text-embedding-004`         | Google   | 768        |
| Balanced (cloud)         | `text-embedding-3-small`     | OpenAI   | 1536       |
| Fully local / air-gapped | `mxbai-embed-large`          | Ollama   | 1024       |
| Minimum resources        | `all-minilm`                 | Ollama   | 384        |

## Dimension Mismatch Handling

pgvector columns are created with a fixed dimension. If the embedding model returns vectors that don't match `EMBEDDING_MODEL_SIZE`:

* **Too short**: padded with zeros. Works but degrades retrieval quality. A warning is logged.
* **Too long**: fails with an error. Update `EMBEDDING_MODEL_SIZE` and re-embed.

## Switching Embedding Models

Changing models requires re-embedding all existing vectors since different models produce incompatible vector spaces.

1. Update `EMBEDDINGS_PROVIDER`, `EMBEDDING_MODEL`, and `EMBEDDING_MODEL_SIZE`
2. If the dimension changed, update your pgvector column dimension
3. Re-embed all existing content

<Note>
  Google models with configurable dimensions (`gemini-embedding-001`, `gemini-embedding-2-preview`) can output at your existing dimension size, avoiding step 2. Re-embedding is still needed since vector spaces differ between models.
</Note>