mirror of
https://github.com/supermemoryai/supermemory.git
synced 2026-10-27 06:15:15 +00:00
acbb05f837
Fixes self-hosting docs to match the `supermemory-server` binary. - **Ingest example.** `?dreaming=instant` was in the URL in the quickstart; it's now in the body. - **Startup.** The banner example is accurate. The plaintext `env` file is legacy: it's moved into the encrypted `env.enc` and then deleted. - **Providers:** - The provider order is OpenAI → Anthropic → Gemini → Vertex → Groq → Workers AI. - PDF extraction needs `GEMINI_API_KEY` (Vertex doesn't help). - URL ingestion uses Firecrawl and needs `FIRECRAWL_API_KEY`. - **Smaller fixes:** - The SDK option is `baseUrl`. - Documented the environment switches the binary honors. - Embedding defaults are corrected. - Removed the claim that the hosted platform uses the same embedding stack. Checked against the current API and the published SDKs (TS 5.0.1, Python 5.0.0). Legacy v3/v4 docs are unchanged apart from factual fixes. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
167 lines
8.5 KiB
Text
167 lines
8.5 KiB
Text
---
|
||
title: "Embeddings (self-hosted)"
|
||
sidebarTitle: "Embeddings"
|
||
description: "Local and remote embedding providers for Supermemory local: defaults, env vars, multilingual options and dimension lock."
|
||
icon: "/icons/hugeicons/route-02.svg"
|
||
---
|
||
|
||
Self-hosted Supermemory supports local ONNX models, OpenAI, Gemini, or any OpenAI-compatible embeddings endpoint (including Ollama). LLM keys power extraction and summarization; embeddings are configured separately.
|
||
|
||
## Defaults
|
||
|
||
| | |
|
||
|---|---|
|
||
| Provider | `local` |
|
||
| Model | `Xenova/bge-base-en-v1.5` |
|
||
| Dimensions | `768` |
|
||
| API key | None — runs on your machine |
|
||
|
||
Press Enter at the optional first-boot picker to keep this default. Nothing is sent off-box to embed.
|
||
|
||
<Warning>
|
||
The default local model is **English-only**. Non-English content can ingest successfully while dense semantic recall stays weak. See [Multilingual](#multilingual).
|
||
</Warning>
|
||
|
||
## 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).
|
||
|
||
<Tip>
|
||
**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.
|
||
</Tip>
|
||
|
||
## Configuration (env)
|
||
|
||
For Docker, CI, or any non-interactive deploy, set env vars — there is **no interactive prompt without a TTY**.
|
||
|
||
| Variable | Purpose | Default |
|
||
|---|---|---|
|
||
| `SUPERMEMORY_EMBEDDING_PROVIDER` | Embedding backend: `local`, `openai`, `gemini`, or `openai-compatible` (Ollama, vLLM, or any custom base URL) | `local` |
|
||
| `SUPERMEMORY_EMBEDDING_MODEL` | Model id for the chosen provider (e.g. `Xenova/bge-m3`, `text-embedding-3-small`) | `Xenova/bge-base-en-v1.5` (local), `text-embedding-3-small` (OpenAI and compatible), `gemini-embedding-001` (Gemini) |
|
||
| `SUPERMEMORY_EMBEDDING_DIMENSIONS` | Vector size; must match the model's output size (native, or a reduced size for `text-embedding-3-*` and Gemini) and any stored data. Required for models not in the [table below](#local-models-with-known-dimensions) or the defaults | Inferred for known models (`768` for the local default) |
|
||
| `SUPERMEMORY_EMBEDDING_BASE_URL` | Base URL for OpenAI-compatible embedding APIs (Ollama, vLLM, etc.) | unset (`openai-compatible` falls back to `OPENAI_BASE_URL`) |
|
||
| `SUPERMEMORY_EMBEDDING_API_KEY` | API key for embedding endpoint (falls back to `OPENAI_API_KEY` / `GEMINI_API_KEY`; `openai-compatible` needs this or `OPENAI_API_KEY`; use any non-empty string if the endpoint has no auth) | unset |
|
||
| `OPENAI_API_KEY` | Used when provider is `openai` (or compatible) if not otherwise supplied | unset |
|
||
| `GEMINI_API_KEY` | Used when provider is `gemini` | unset |
|
||
|
||
Local worker tuning (throughput only — does not change model or dimensions):
|
||
|
||
| Variable | Purpose | Default |
|
||
|---|---|---|
|
||
| `SUPERMEMORY_LOCAL_EMBEDDING_POOL_SIZE` | Number of embedding workers | `1` |
|
||
| `SUPERMEMORY_LOCAL_EMBEDDING_WASM_THREADS` | Compute threads per worker | `1` |
|
||
| `SUPERMEMORY_LOCAL_EMBEDDING_BATCH_SIZE` | Texts per worker dispatch | `8` |
|
||
| `SUPERMEMORY_LOCAL_EMBEDDING_IDLE_TIMEOUT_MS` | Idle time before workers shut down | `120000` |
|
||
| `SUPERMEMORY_SKIP_EMBEDDING_PREWARM` | Skip startup prewarm, load on first use | unset |
|
||
|
||
Ingestion memory headroom is controlled by `SUPERMEMORY_EMBEDDING_RAM_LIMIT` — see [Memory limits & ingestion queue](/self-hosting/configuration#memory-limits-&-ingestion-queue).
|
||
|
||
<Tip>
|
||
**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.
|
||
</Tip>
|
||
|
||
## 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:
|
||
|
||
```bash
|
||
# Example: local multilingual (set dimensions to match the model)
|
||
SUPERMEMORY_EMBEDDING_PROVIDER=local
|
||
SUPERMEMORY_EMBEDDING_MODEL=Xenova/bge-m3
|
||
SUPERMEMORY_EMBEDDING_DIMENSIONS=1024
|
||
```
|
||
|
||
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)
|
||
|
||
```bash
|
||
# Explicit local default — no embedding API key
|
||
SUPERMEMORY_EMBEDDING_PROVIDER=local
|
||
SUPERMEMORY_EMBEDDING_MODEL=Xenova/bge-base-en-v1.5
|
||
SUPERMEMORY_EMBEDDING_DIMENSIONS=768
|
||
```
|
||
|
||
#### Local models with known dimensions
|
||
|
||
Local models do not support dimension reduction, so `SUPERMEMORY_EMBEDDING_DIMENSIONS` must match the model's native size:
|
||
|
||
| Model ID | Dimensions | Notes |
|
||
|---|---|---|
|
||
| `Xenova/bge-base-en-v1.5` | `768` | Default local model (English) |
|
||
| `Xenova/bge-m3` | `1024` | Multilingual (uses `cls` pooling) |
|
||
| `Xenova/bge-small-en-v1.5` | `384` | English (lightweight) |
|
||
| `Xenova/bge-large-en-v1.5` | `1024` | English (high capacity) |
|
||
| `Xenova/multilingual-e5-small` | `384` | Multilingual (lightweight) |
|
||
| `Xenova/multilingual-e5-base` | `768` | Multilingual |
|
||
| `Xenova/multilingual-e5-large` | `1024` | Multilingual (high capacity) |
|
||
| `Xenova/all-MiniLM-L6-v2` | `384` | English general purpose |
|
||
| `Xenova/paraphrase-multilingual-MiniLM-L12-v2` | `384` | Multilingual sentence similarity |
|
||
|
||
### OpenAI
|
||
|
||
```bash
|
||
OPENAI_API_KEY=sk-...
|
||
SUPERMEMORY_EMBEDDING_PROVIDER=openai
|
||
SUPERMEMORY_EMBEDDING_MODEL=text-embedding-3-small
|
||
SUPERMEMORY_EMBEDDING_DIMENSIONS=1536
|
||
```
|
||
|
||
### Gemini
|
||
|
||
```bash
|
||
GEMINI_API_KEY=...
|
||
SUPERMEMORY_EMBEDDING_PROVIDER=gemini
|
||
SUPERMEMORY_EMBEDDING_MODEL=gemini-embedding-001
|
||
SUPERMEMORY_EMBEDDING_DIMENSIONS=768
|
||
```
|
||
|
||
### Ollama (OpenAI-compatible)
|
||
|
||
```bash
|
||
SUPERMEMORY_EMBEDDING_PROVIDER=openai-compatible
|
||
SUPERMEMORY_EMBEDDING_BASE_URL=http://localhost:11434/v1
|
||
SUPERMEMORY_EMBEDDING_API_KEY=ollama
|
||
SUPERMEMORY_EMBEDDING_MODEL=nomic-embed-text
|
||
SUPERMEMORY_EMBEDDING_DIMENSIONS=768
|
||
```
|
||
|
||
Use the dimension published for your chosen model. A mismatch with vectors already in the store fails boot.
|
||
|
||
## Changing models later
|
||
|
||
<Warning>
|
||
**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**.
|
||
</Warning>
|
||
|
||
<Note>
|
||
**Embedding env vars are ignored in v0.0.6 and v0.0.7-rc.2**
|
||
|
||
Those 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.
|
||
</Note>
|
||
|
||
<Note>
|
||
**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.
|
||
</Note>
|
||
|
||
## Related
|
||
|
||
- [Configuration](/self-hosting/configuration) — LLM providers, storage, ingestion limits
|
||
- [Quickstart](/self-hosting/quickstart) — install and first memory
|