diff --git a/apps/docs/self-hosting/configuration.mdx b/apps/docs/self-hosting/configuration.mdx index 2dd6c19a..ce057fac 100644 --- a/apps/docs/self-hosting/configuration.mdx +++ b/apps/docs/self-hosting/configuration.mdx @@ -7,7 +7,7 @@ icon: "/icons/hugeicons/settings-01.svg" The self-hosted server aims for **zero configuration** — the only required input is one LLM provider key, which the first-boot wizard collects interactively (or set via env var for non-interactive deployments). Embeddings default to local English; you can pick another provider in the optional wizard step or via env. Everything else below is opt-in. -The installer writes API keys to `~/.supermemory/env`, which is loaded on every launch. You can also set variables in your shell or a process manager. +The installer writes API keys to `~/.supermemory/env`, and the first-boot wizard saves them encrypted to `env.enc` in the data directory. Saved keys are loaded on every launch. When the data directory is `~/.supermemory`, the server copies the installer's parsed plaintext `env` values into `env.enc` on the next launch before attempting to remove `env`. A failed migration or removal can leave the plaintext file in place. You can also set variables in your shell or a process manager. ## Core @@ -30,18 +30,20 @@ In production, Supermemory uses its own proprietary models tuned for long-horizo | `OPENAI_API_KEY` | OpenAI — or any OpenAI-compatible endpoint, see below | | `ANTHROPIC_API_KEY` | Anthropic | | `GEMINI_API_KEY` | Google AI Studio (Gemini) | +| `GOOGLE_VERTEX_PROJECT_ID` + `GOOGLE_VERTEX_LOCATION` | GCP Vertex AI | | `GROQ_API_KEY` | Groq | | `WORKERS_AI_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` | Cloudflare Workers AI | -| `GOOGLE_VERTEX_PROJECT_ID` + `GOOGLE_VERTEX_LOCATION` | GCP Vertex AI | No key set? The server walks you through it. On first boot, an interactive setup wizard asks which provider you want, securely prompts for the key, and saves it encrypted — including a custom base URL and model name if you pick an OpenAI-compatible endpoint. -With multiple providers configured, the first one in the order above is used. +For fast/text LLM tasks, the first configured provider in the order above is used. Image and video tasks use Vertex AI first, then Gemini. -Image, video, and high-fidelity PDF understanding require a Gemini or Vertex AI key. Text ingestion, memory extraction, and search work with any provider. +Image and video understanding require a Gemini or Vertex AI key. PDF extraction requires `GEMINI_API_KEY`; Vertex AI doesn't cover it. Text ingestion, memory extraction, and search work with any provider. + +Webpage ingestion fetches pages through Firecrawl and needs `FIRECRAWL_API_KEY`. Without it, webpage documents fail. URLs pointing to PDFs or media use their corresponding extractors instead. ### Fully offline with local models @@ -138,7 +140,7 @@ These exist in the codebase but are exclusive to the [hosted platform](https://c - **Optimized memory extraction** — the platform's extraction pipeline is tuned for higher quality at lower cost than bring-your-own-key - **Managed scale** — globally distributed infrastructure, no capacity planning -Any other environment variables you may find referenced in the codebase are platform-only: the self-hosted binary ignores them even when set. +Besides the variables on this page, the binary honors a few operational switches: `SUPERMEMORY_VERBOSE=1` (detailed logs), `SUPERMEMORY_HIDE_API_KEY_IN_LOGS=1` (omit the key from the startup banner), `SUPERMEMORY_NO_OPEN=1` (don't open a browser on boot), and `SUPERMEMORY_NO_UPDATE_CHECK=1` (skip the update notification). The Docker image sets the last three. ## Example: production-ish `.env` diff --git a/apps/docs/self-hosting/docker.mdx b/apps/docs/self-hosting/docker.mdx index 1693c9fd..bf5bcb37 100644 --- a/apps/docs/self-hosting/docker.mdx +++ b/apps/docs/self-hosting/docker.mdx @@ -57,7 +57,7 @@ curl --fail -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ http://127.0.0.1:6767/v3/projects ``` -Treat this key as a secret. API requests require it even on localhost. Use the same key with your SDK and set `baseURL` to `http://localhost:6767`. +Treat this key as a secret. API requests require it even on localhost. Use the same key with your SDK and set `baseUrl` (Python: `base_url`) to `http://localhost:6767`. ## Preserve data and configuration diff --git a/apps/docs/self-hosting/embeddings.mdx b/apps/docs/self-hosting/embeddings.mdx index 5fd4fce1..24b400b2 100644 --- a/apps/docs/self-hosting/embeddings.mdx +++ b/apps/docs/self-hosting/embeddings.mdx @@ -5,7 +5,7 @@ description: "Local and remote embedding providers for Supermemory local: defaul icon: "/icons/hugeicons/route-02.svg" --- -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. +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 @@ -43,9 +43,9 @@ For Docker, CI, or any non-interactive deploy, set env vars — there is **no in | 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) | -| `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 | `768` (local default) | -| `SUPERMEMORY_EMBEDDING_BASE_URL` | Base URL for OpenAI-compatible embedding APIs (Ollama, vLLM, etc.) | unset | +| `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 | @@ -122,7 +122,7 @@ SUPERMEMORY_EMBEDDING_DIMENSIONS=1536 ```bash GEMINI_API_KEY=... SUPERMEMORY_EMBEDDING_PROVIDER=gemini -SUPERMEMORY_EMBEDDING_MODEL=text-embedding-004 +SUPERMEMORY_EMBEDDING_MODEL=gemini-embedding-001 SUPERMEMORY_EMBEDDING_DIMENSIONS=768 ``` diff --git a/apps/docs/self-hosting/local-vs-enterprise.mdx b/apps/docs/self-hosting/local-vs-enterprise.mdx index a3e259c8..d04d793f 100644 --- a/apps/docs/self-hosting/local-vs-enterprise.mdx +++ b/apps/docs/self-hosting/local-vs-enterprise.mdx @@ -5,7 +5,7 @@ description: "Supermemory local is for builders. Supermemory Enterprise is for o icon: "/icons/hugeicons/building-03.svg" --- -Supermemory local — the self-hosted binary — is free within its lite license limit and built for individual developers: local-first workflows, prototyping, and privacy-sensitive side projects. Its server source is not in the public repository. Text-memory processing can run offline after the first embedding-model download; URL ingestion uses a hosted reader service. +Supermemory local — the self-hosted binary — is free within its lite license limit and built for individual developers: local-first workflows, prototyping, and privacy-sensitive side projects. Its server source is not in the public repository. Text-memory processing can run offline after the first embedding-model download when the LLM is also local; webpage ingestion goes through Firecrawl and needs `FIRECRAWL_API_KEY`. **Supermemory Enterprise** is the full platform, run for your organization: the same memory engine with proprietary models, organizational controls, and infrastructure that scales with you — without you operating any of it. @@ -44,7 +44,7 @@ Local is bounded by one machine — which is the point. Enterprise runs on globa ## Moving between them -The two speak the same API. Code written against your local server moves to Enterprise by changing the `baseUrl` — and vice versa. Prototype locally, ship on Enterprise. +The two speak the same API. Point your code at the destination's `baseUrl` and use a credential issued there. Changing the connection does not transfer your local data. Prototype locally, ship on Enterprise. diff --git a/apps/docs/self-hosting/overview.mdx b/apps/docs/self-hosting/overview.mdx index 07d54c0c..85d93223 100644 --- a/apps/docs/self-hosting/overview.mdx +++ b/apps/docs/self-hosting/overview.mdx @@ -24,7 +24,7 @@ No Docker. No database to provision. No config files. It boots in seconds with e Run the binary with nothing set and you get a complete memory system: - **The Supermemory graph engine, embedded** — created automatically on first boot. No database to stand up, no connection strings. -- **Built-in local embeddings** — default `Xenova/bge-base-en-v1.5` (768d) on your machine, no API key. Same provider stack as cloud if you opt into OpenAI, Gemini, or Ollama — see [Embeddings](/self-hosting/embeddings). +- **Built-in local embeddings** — default `Xenova/bge-base-en-v1.5` (768d) on your machine, no API key. Opt into OpenAI, Gemini, or Ollama instead — see [Embeddings](/self-hosting/embeddings). - **An API key, generated for you** — printed on first boot, ready to paste into any SDK. - **The full Memory API** — `/ns/{namespace}/document`, `/ns/{namespace}/search`, `/ns/{namespace}/profile`, namespaces, the works. @@ -41,7 +41,7 @@ OPENAI_MODEL=gpt-oss:20b \ supermemory-server ``` -Local graph engine, local embeddings, local LLM. Text-memory processing can stay on your machine after the embedding model's first download. Supermemory collects telemetry; you can disable it with `SUPERMEMORY_DISABLE_TELEMETRY=1`. URL ingestion uses a hosted reader service; use local text or file inputs for offline operation. +Local graph engine, local embeddings, local LLM. Text-memory processing can stay on your machine after the embedding model's first download. Supermemory collects telemetry; you can disable it with `SUPERMEMORY_DISABLE_TELEMETRY=1`. Webpage ingestion sends the URL to Firecrawl and needs `FIRECRAWL_API_KEY`; use local text inputs for offline operation. Also set `SUPERMEMORY_NO_UPDATE_CHECK=1` if the server must not check for releases. ## Drop-in with your existing code @@ -68,14 +68,14 @@ Self-hosted is free within its lite license limit and useful for local developme |---|---|---| | Full Memory API | ✅ | ✅ | | Hybrid semantic search | ✅ | ✅ | -| Embeddings | Local default (or OpenAI / Gemini / Ollama) | Same provider stack, managed | -| File ingestion (PDFs, images) | ✅ | ✅ | +| Embeddings | Local default (or OpenAI / Gemini / Ollama) | Managed | +| File ingestion (PDFs, images) | ✅ (PDFs need `GEMINI_API_KEY`; images use Gemini or Vertex AI) | ✅ | | [Connectors](/connectors/overview) (Google Drive, Notion, Gmail, OneDrive) | — | ✅ | | [Supermemory MCP](/supermemory-mcp/mcp) | — | ✅ | | Memory extraction | Your model, your key | Proprietary long-horizon models — higher quality, cheaper at scale | | Infrastructure | Your machine | Globally distributed, scales with you | -If you outgrow a single machine — or want connectors, MCP, and the best-tuned extraction pipeline — [the platform](https://console.supermemory.ai) is one `serverURL` change away. Running this for a team or organization? See [Local vs. Enterprise](/self-hosting/local-vs-enterprise). +If you outgrow a single machine — or want connectors, MCP, and the best-tuned extraction pipeline — switch to [the platform](https://console.supermemory.ai) with its `baseUrl` and a hosted API key. Changing the connection does not transfer your local data. Running this for a team or organization? See [Local vs. Enterprise](/self-hosting/local-vs-enterprise). ## Next steps diff --git a/apps/docs/self-hosting/providers.mdx b/apps/docs/self-hosting/providers.mdx index 741d1c7e..9a3e1b56 100644 --- a/apps/docs/self-hosting/providers.mdx +++ b/apps/docs/self-hosting/providers.mdx @@ -45,7 +45,7 @@ Runs on `claude-haiku-4-5` — this one isn't currently configurable via env var GEMINI_API_KEY=... ``` -Runs on `gemini-3.1-flash-lite-preview` — also not currently overridable. This is the only key that also unlocks image, video, and high-fidelity PDF understanding (see the [full provider table](/self-hosting/configuration#llm-providers)). +Runs on `gemini-3.1-flash-lite-preview` — also not currently overridable. This is the only key on this page that also unlocks image, video, and PDF understanding (see the [full provider table](/self-hosting/configuration#llm-providers)). diff --git a/apps/docs/self-hosting/quickstart.mdx b/apps/docs/self-hosting/quickstart.mdx index c1a13300..8ab34ddf 100644 --- a/apps/docs/self-hosting/quickstart.mdx +++ b/apps/docs/self-hosting/quickstart.mdx @@ -58,12 +58,18 @@ supermemory-server First boot sets everything up — the embedded Supermemory graph engine, local embeddings, and your credentials: ``` - ┌──────────────────────────────────────────────────┐ - │ url http://localhost:6767 │ - │ database ./.supermemory │ - │ api key sm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx │ - │ org id xxxxxxxxxxxxxxxxxxxxxx │ - └──────────────────────────────────────────────────┘ +╭───────────────────────────────────────────────────────────────╮ +│ → supermemory ready │ +│ │ +│ url http://localhost:6767 │ +│ database encrypted local storage (~/.supermemory) │ +│ embeddings local · Xenova/bge-base-en-v1.5 · 768d │ +│ workflow rivet │ +│ api key sm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx │ +│ org id xxxxxxxxxxxxxxxxxxxxxx │ +│ boot 4.2s │ +╰───────────────────────────────────────────────────────────────╯ + every request needs this key: Authorization: Bearer ``` Save that API key — it's your bearer token for every request. @@ -118,11 +124,12 @@ client.add( ```bash -curl "http://localhost:6767/ns/user_dhravya/document?dreaming=instant" \ +curl http://localhost:6767/ns/user_dhravya/document \ -H "Authorization: Bearer sm_..." \ -H "Content-Type: application/json" \ -d '{ - "content": "I am Dhravya. I love building dev tools and I am allergic to peanuts." + "content": "I am Dhravya. I love building dev tools and I am allergic to peanuts.", + "dreaming": "instant" }' ``` @@ -163,8 +170,9 @@ By default, all state lives in a single directory you can back up or move: | Path | Contents | |---|---| -| `~/.supermemory/` (or `$SUPERMEMORY_DATA_DIR`; `./.supermemory/` before v0.0.9) | The Supermemory graph engine's data, auth secret, embedding model cache | -| `~/.supermemory/env` | API keys saved by the installer, loaded on every launch | +| `~/.supermemory/` (or `$SUPERMEMORY_DATA_DIR`; `./.supermemory/` before v0.0.9) | The Supermemory graph engine's data, API key, auth secret, embedding model cache | +| `~/.supermemory/env.enc` | Provider keys and embedding choices saved by the first-boot wizard, encrypted and loaded on every launch | +| `~/.supermemory/env` | Plaintext API keys written by the installer. On launch, the server copies parsed values into `env.enc` before attempting to remove this file; it can remain if migration or removal fails | ## Next steps