Skip to main content
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

​
Providers

​
OpenAI

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

​
Google Gemini

Requires GOOGLE_GENERATIVE_AI_API_KEY. Get a free key from Google AI Studio. For models with configurable dimensions, EMBEDDING_MODEL_SIZE controls the output dimensionality. This lets you match existing pgvector columns without changing the schema.

​
Local (in-process, no server)

CORE ships with an in-process embedding backend powered by @huggingface/transformers 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.
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):
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. Pull the model first:

​
Choosing a Model

​
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
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.