Skip to main content
Self-hosted Supermemory uses the same embedding provider stack as the hosted platform: local ONNX models, OpenAI, Gemini, or any OpenAI-compatible embeddings endpoint (including Ollama). LLM keys power extraction and summarization; embeddings are configured separately.

​
Defaults

Press Enter at the optional first-boot picker to keep this default. Nothing is sent off-box to embed.
The default local model is English-only. Non-English content can ingest successfully while dense semantic recall stays weak. See Multilingual.

​
First-time setup (interactive)

On first boot with a TTY, Supermemory asks for an LLM API key (required), then optionally which embedding model to use.
  1. Choose or paste an LLM provider key (OpenAI, Anthropic, Gemini, Groq, or OpenAI-compatible).
  2. Optionally pick an embedding provider/model. Press Enter to keep the local English model.
  3. Choices are saved encrypted under your data directory ($SUPERMEMORY_DATA_DIR, ~/.supermemory by default from v0.0.9, ./.supermemory before).
Boot order is intentional: LLM keys load first so remote embedding options can reuse them (for example OpenAI or Gemini embeddings with the same key).
First boot (terminal): Supermemory asks for an LLM API key (required), then optionally which embedding model to use. Press Enter to keep the local English model. Choices are saved encrypted under your data directory.

​
Configuration (env)

For Docker, CI, or any non-interactive deploy, set env vars — there is no interactive prompt without a TTY. Local worker tuning (throughput only — does not change model or dimensions): Ingestion memory headroom is controlled by SUPERMEMORY_EMBEDDING_RAM_LIMIT — see Memory limits & ingestion queue.
Docker / production: Set at least one LLM key and, if you don’t want local embeddings, set SUPERMEMORY_EMBEDDING_PROVIDER / SUPERMEMORY_EMBEDDING_MODEL / SUPERMEMORY_EMBEDDING_DIMENSIONS (and base URL or API key as needed). There is no interactive prompt without a TTY.

​
Multilingual

The default Xenova/bge-base-en-v1.5 model is trained for English. For German, Dutch, and other non-English corpora, dense recall can fail even when hybrid keyword search still finds rare tokens. For multilingual or non-English deployments, switch before large backfills:
Or use a remote multilingual embedding API (OpenAI, Gemini, or Ollama with a multilingual embed model). Set provider, model, and dimensions together. Changing them later requires a fresh data directory or full re-ingestion — see below.

​
Remote providers

​
Local (default)

​
Local models with known dimensions

Local models do not support dimension reduction, so SUPERMEMORY_EMBEDDING_DIMENSIONS must match the model’s native size:

​
OpenAI

​
Gemini

​
Ollama (OpenAI-compatible)

Use the dimension published for your chosen model. A mismatch with vectors already in the store fails boot.

​
Changing models later

Not supported in place. Embeddings from different models (or different dimensions) are not comparable. Start from a fresh data directory or re-ingest all content so vectors stay in one space. If configured dimensions disagree with stored data, the server refuses to boot.
Embedding env vars are ignored in v0.0.6 and v0.0.7-rc.2Those two releases ignore SUPERMEMORY_EMBEDDING_* and always use local Xenova/bge-base-en-v1.5. The env vars work in v0.0.7 and later.A data directory created on v0.0.6 has no embedding-plan.json. From v0.0.7, if such a directory already has embeddings, the server locks it to local · Xenova/bge-base-en-v1.5 · 768d. To use another provider or model, point SUPERMEMORY_DATA_DIR at a fresh directory (or delete the old one) before starting with the new env vars.
Model Mixing Bug in v0.0.5 (Exact match returns nothing)In version v0.0.5, there was a bug where the server could mix different embedding models between write and read paths (e.g., document ingestion using OpenAI but memory queries using local default embeddings). In multilingual contexts like Japanese (which lacks space tokenization for fallback lexical FTS matching), this caused exact-text memory searches through /v4/search and /v4/profile to silently return {"results":[],"total":0}.Resolution: This was fully resolved in v0.0.7 by locking the embedding plan uniformly across all document and query embedding paths (enforced via a locked plan in the database store). If you are running v0.0.5 and experiencing this issue, you should upgrade to v0.0.7 or later.