diff --git a/README.md b/README.md index fefa4560a..4a17c5934 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@

Docs · Quickstart · + Self-host · Dashboard · Discord

@@ -77,6 +78,21 @@ No vector DB config. No embedding pipelines. No chunking strategies. **[→ Jump to developer quickstart](#build-with-supermemory-api)** + + + + + +

🖥️ I want to run it myself

+ +State-of-the-art memory, on your machine. **One binary. Zero config.** Bring any model — or run fully offline with Ollama. + +```bash +curl -fsSL https://supermemory.ai/install | bash +``` + +**[→ Jump to Supermemory local](#supermemory-local--run-it-yourself)** + @@ -301,6 +317,38 @@ Full API reference → [supermemory.ai/docs](https://supermemory.ai/docs) --- +## Supermemory local — run it yourself + +State-of-the-art memory, on your machine. One binary. Zero config. + +```bash +curl -fsSL https://supermemory.ai/install | bash +# or +npx supermemory local +``` + +```bash +supermemory-server +``` + +First boot sets up the embedded Supermemory graph engine, local embeddings, and your credentials, then prints an API key. The full Memory API — documents, memories, user profiles, hybrid search — runs against `http://localhost:6767`. + +```typescript +const client = new Supermemory({ + apiKey: "sm_...", + baseURL: "http://localhost:6767", // that's the only change +}); +``` + +- **Bring any model** — OpenAI, Anthropic, Gemini, Groq, or any OpenAI-compatible endpoint. An interactive wizard walks you through it on first boot. +- **Fully offline if you want** — point it at Ollama (`gpt-oss:20b` works great) and nothing leaves your machine. +- **Your data, one directory** — everything lives in `./.supermemory`, easy to back up or move. +- **Same API as the platform** — prototype locally, ship on the hosted platform by changing `baseURL`. + +Read the [self-hosting docs](https://supermemory.ai/docs/self-hosting/overview) — quickstart, configuration, and [local vs. Enterprise](https://supermemory.ai/docs/self-hosting/local-vs-enterprise). + +--- + ## Benchmarks Supermemory is state of the art across all major AI memory benchmarks: @@ -354,6 +402,7 @@ Your app / AI tool - 📖 [Documentation](https://supermemory.ai/docs) - 🚀 [Quickstart](https://supermemory.ai/docs/quickstart) +- 🖥️ [Self-hosting (Supermemory local)](https://supermemory.ai/docs/self-hosting/overview) - 🧪 [MemoryBench](https://supermemory.ai/docs/memorybench/overview) - 🔌 [Integrations](https://supermemory.ai/docs/integrations) - 💬 [Discord](https://supermemory.link/discord) diff --git a/apps/docs/deployment/self-hosting.mdx b/apps/docs/deployment/self-hosting.mdx deleted file mode 100644 index 7f7db4d31..000000000 --- a/apps/docs/deployment/self-hosting.mdx +++ /dev/null @@ -1,243 +0,0 @@ ---- -title: 'Self Hosting' -description: 'Deploy your own instance of the supermemory API on Cloudflare Workers' ---- - - -This guide is intended for **enterprise customers only** who have specifically opted for self-hosting as part of their enterprise plan. If you're on a standard plan, please use our hosted API at [console.supermemory.ai](https://console.supermemory.ai). - - -## Prerequisites - -Before you start, you'll need to gather several API keys and set up accounts with various services. This comprehensive guide will walk you through obtaining each required component. - -### Enterprise Deployment Package - -Your enterprise deployment package is provided by the supermemory team and contains: -- Your unique Host ID (`NEXT_PUBLIC_HOST_ID`) -- The compiled JavaScript bundle -- The deployment script - -Contact your supermemory enterprise representative to receive your deployment package. - -### Cloudflare - - -#### Create Account - -1. Go to [cloudflare.com](https://dash.cloudflare.com/sign-up) and create an account -3. Your **Account ID** is the long randon string in the URL bar - -#### Create API Token - -1. Navigate to [Cloudflare API Tokens](https://dash.cloudflare.com/?to=/:account/api-tokens) -2. Click **"Create Token"** -3. Use the **"Custom token"** template -4. Configure the token with these permissions: - - **Account:AI Gateway:Edit** - - **Account:Hyperdrive:Edit** - - **Account:Workers KV Storage:Edit** - - **Account:Workers R2 Storage:Edit** -7. Click **"Continue to summary"** → **"Create Token"** -8. **Important**: Copy and securely store the token immediately (it won't be shown again) - -#### Enable Workers - -1. In your Cloudflare dashboard, go to **Workers & Pages** -2. If prompted, accept the Workers terms of service -3. Choose a subdomain for your workers (e.g., `yourcompany.workers.dev`) - -Your `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN` are now ready. - -### Database - -You'll need to provide a PostgreSQL connection string via the `DATABASE_URL` environment variable. - -The database must: -- Support the **pgvector extension** for vector operations -- Be accessible from Cloudflare Workers -- Support SSL connections -- Allow connections from Cloudflare's IP ranges - -Your connection string should follow this format: -``` -postgresql://username:password@hostname:port/database -``` - -### LLM Providers - -#### OpenAI - -1. Go to [platform.openai.com](https://platform.openai.com) -2. Sign in or create an account -3. Navigate to **API Keys** in the left sidebar -4. Click **"Create new secret key"** -5. Name your key (e.g., "supermemory Self-Hosted") -6. Copy the key and store it securely -7. Add billing information if you haven't already - -#### Anthropic - -1. Go to [console.anthropic.com](https://console.anthropic.com) -2. Create an account and complete verification -3. Navigate to **API Keys** -4. Click **"Create Key"** -5. Name your key and copy it securely - -#### Gemini - -1. Go to [Google AI Studio](https://aistudio.google.com) -2. Sign in with your Google account -3. Click **"Get API key"** → **"Create API key"** -4. Choose an existing Google Cloud project or create a new one -5. Copy your API key - -#### Groq - -1. Go to [console.groq.com](https://console.groq.com) -2. Sign up for an account -3. Navigate to **API Keys** -4. Click **"Create API Key"** -5. Name your key and copy it - - - -{/* TODO: Add OAuth documentation */} -{/* ### Authentication Providers -#### GitHub OAuth (Optional) - -1. Go to [GitHub Developer Settings](https://github.com/settings/developers) -2. Click **"New OAuth App"** -3. Fill in the application details: - - **Application name**: Your app name - - **Homepage URL**: Your API domain (e.g., `https://api.yourdomain.com`) - - **Authorization callback URL**: `https://api.yourdomain.com/api/auth/callback/github` -4. Click **"Register application"** -5. Note the **Client ID** and generate a **Client Secret** -6. Use these for `AUTH_GITHUB_ID` and `AUTH_GITHUB_SECRET` - -#### Google OAuth (Optional) - -1. Go to [Google Cloud Console](https://console.cloud.google.com) -2. Create a new project or select an existing one -3. Enable the **Google+ API** -4. Go to **Credentials** → **Create Credentials** → **OAuth client ID** -5. Choose **Web application** -6. Add your domain to **Authorized JavaScript origins** -7. Add `https://api.yourdomain.com/api/auth/callback/google` to **Authorized redirect URIs** -8. Copy the **Client ID** and **Client secret** -9. Use these for `AUTH_GOOGLE_ID` and `AUTH_GOOGLE_SECRET` */} - -### Email Service Setup - -#### Resend - -1. Go to [resend.com](https://resend.com) and create an account -2. Navigate to **API Keys** -3. Click **"Create API Key"** -4. Name your key (e.g., "supermemory Production") -5. Copy the key for `RESEND_API_KEY` -6. Verify your sending domain in the **Domains** section - -### Connectors (Optional) - -#### Google Drive - -1. Go to [Google Cloud Console](https://console.cloud.google.com) -2. Create or select a project -3. Enable the **Google Drive API** -4. Go to **Credentials** → **Create Credentials** → **OAuth client ID** -5. Configure the OAuth consent screen if required -6. Choose **Web application** -7. Add authorized redirect URIs for your domain -8. Copy `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` - -#### Microsoft OneDrive - -1. Go to [Azure Portal](https://portal.azure.com) -2. Navigate to **Microsoft Entra ID** → **App registrations** -3. Click **"New registration"** -4. Name your app and set redirect URI -5. Go to **Certificates & secrets** → **New client secret** -6. Copy the **Application (client) ID** and **Client secret** -7. Use for `MICROSOFT_CLIENT_ID` and `MICROSOFT_CLIENT_SECRET` - -#### Notion - -1. Go to [Notion Developers](https://developers.notion.com) -2. Click **"Create new integration"** -3. Fill in the integration details -4. Copy the **Internal Integration Token** -5. Set up OAuth if needed for user connections -6. Use for `NOTION_CLIENT_ID` and `NOTION_CLIENT_SECRET` - ---- - -## Setup deployment files - -Extract the deployment package provided by the supermemory team to your preferred directory: - -```bash -# Extract the deployment package -$ unzip supermemory-enterprise-deployment.zip -$ cd supermemory-deployment -``` - ---- - -## Configure environment variables - -The deployment script reads **all** environment variables from your shell at runtime. We ship an example file that lists the full set supported by the worker. - -```bash -# Copy the template and start editing -$ cp packages/alchemy/env.example .env - -# Open the file in your editor of choice and fill in the blanks -$ $EDITOR .env -``` - -Below is a quick reference. -**Required** values are mandatory for a successful deploy – leave optional ones empty if you don't need the related feature. - -| Name | Required? | Description | -|------|-----------|-------------| -| `NODE_ENV` | ✅ | `development`, `staging` or `production`. | -| `NEXT_PUBLIC_HOST_ID` | ✅ | Your unique Host ID provided by the supermemory team. | -| `BETTER_AUTH_SECRET` | ✅ | Random 32-byte string – run `openssl rand -base64 32`. | -| `BETTER_AUTH_URL` | ✅ | Public base URL for the API (no trailing `/`). Example: `https://api.example.com`. | -| `DATABASE_URL` | ✅ | Postgres connection string (e.g. `postgres://user:pass@host:5432/db`). | -| `CLOUDFLARE_ACCOUNT_ID` | ✅ | Your Cloudflare account ID. | -| `CLOUDFLARE_API_TOKEN` | ✅ | Token created in *Prerequisites*. | -| `OPENAI_API_KEY` | ✅ | Key from [platform.openai.com](https://platform.openai.com). | -| `RESEND_API_KEY` | ✅ | E-mail provider key if you plan to send e-mails. | -| `ANTHROPIC_API_KEY` | | Needed to use Claude models. | -| `GEMINI_API_KEY` | | Key for Google Gemini models. | -| `GROQ_API_KEY` | | Key for Groq models. | -| `AUTH_GITHUB_ID` / `AUTH_GITHUB_SECRET` | | Enable GitHub OAuth login. | -| `AUTH_GOOGLE_ID` / `AUTH_GOOGLE_SECRET` | | Enable Google OAuth login. | -| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | | Needed for Google Drive connector. | -| `MICROSOFT_CLIENT_ID` / `MICROSOFT_CLIENT_SECRET` | | Needed for OneDrive connector. | -| `NOTION_CLIENT_ID` / `NOTION_CLIENT_SECRET` | | Needed for Notion connector. | -| `CLOUDFLARE_AI_GATEWAY_NAME` / `CLOUDFLARE_AI_GATEWAY_TOKEN` | | Only if you want to route requests through an AI Gateway. | -| `SENTRY_DSN` | | If you use Sentry for error reporting. | - ---- - -## Deploy - -With your `.env` in place, run the deployment script: - -```bash -# Run the deployment script provided in your package -$ bun ./deploy.ts -``` - - ---- - -## Updating Your Deployment - -To update your supermemory deployment, follow the same process as the initial deployment described in the **Deploy** section above. You can reuse your existing `.env` file and add/remove any new environment variables as needed. - ---- \ No newline at end of file diff --git a/apps/docs/docs.json b/apps/docs/docs.json index f2bb9b807..f77b1882a 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -71,6 +71,15 @@ "group": "Getting Started", "pages": ["intro", "quickstart", "vibe-coding"] }, + { + "group": "Self-Hosting", + "pages": [ + "self-hosting/overview", + "self-hosting/quickstart", + "self-hosting/configuration", + "self-hosting/local-vs-enterprise" + ] + }, { "group": "Concepts", "pages": [ diff --git a/apps/docs/integrations/claude-code.mdx b/apps/docs/integrations/claude-code.mdx index 7e12099da..204014712 100644 --- a/apps/docs/integrations/claude-code.mdx +++ b/apps/docs/integrations/claude-code.mdx @@ -19,6 +19,10 @@ This integration requires the **Supermemory Pro plan**. [Upgrade here](https://c [Claude-Supermemory](https://github.com/supermemoryai/claude-supermemory) is a Claude Code plugin that gives your AI persistent memory across sessions. Your agent remembers what you worked on — across sessions, across projects. + +**Prefer to keep everything on your machine?** This plugin works with [self-hosted Supermemory](/self-hosting/overview) — run `npx supermemory local`, then `export SUPERMEMORY_API_URL="http://localhost:6767"` and use the API key printed on first boot. + + ## Get Your API Key Create a Supermemory API key from the [API Keys](https://console.supermemory.ai/keys) page, then add it to your shell profile so it persists across sessions: diff --git a/apps/docs/integrations/codex.mdx b/apps/docs/integrations/codex.mdx index 46eef9452..6307d9967 100644 --- a/apps/docs/integrations/codex.mdx +++ b/apps/docs/integrations/codex.mdx @@ -10,6 +10,10 @@ icon: "terminal" - **Implicit** (hooks) — automatically recalls context before each prompt and captures conversations after each session. - **Explicit** (skills) — lets you or the agent save, search, and manage memories on demand. + +**Prefer to keep everything on your machine?** This plugin works with [self-hosted Supermemory](/self-hosting/overview) — run `npx supermemory local`, then `export SUPERMEMORY_API_URL="http://localhost:6767"` (or set `baseUrl` in `~/.codex/supermemory.json`) and use the API key printed on first boot. + + ## Get Your API Key Create a Supermemory API key from the [API Keys](https://console.supermemory.ai/keys) page, then export it in your shell profile: diff --git a/apps/docs/integrations/openclaw.mdx b/apps/docs/integrations/openclaw.mdx index 436022e84..aacc7ef01 100644 --- a/apps/docs/integrations/openclaw.mdx +++ b/apps/docs/integrations/openclaw.mdx @@ -11,6 +11,10 @@ This integration requires the **Supermemory Pro plan**. [Upgrade here](https://c [OpenClaw](https://github.com/supermemoryai/openclaw-supermemory) is a multi-platform AI messaging gateway that connects to WhatsApp, Telegram, Discord, Slack, iMessage, and other messaging channels. The Supermemory plugin gives OpenClaw memory across every channel. + +**Prefer to keep everything on your machine?** This plugin works with [self-hosted Supermemory](/self-hosting/overview) — run `npx supermemory local`, then `export SUPERMEMORY_BASE_URL="http://localhost:6767"` (or set `baseUrl` in the plugin config) and use the API key printed on first boot. + + ## Install the Plugin Get started by installing the plugin with a single command. diff --git a/apps/docs/integrations/opencode.mdx b/apps/docs/integrations/opencode.mdx index d1a11b675..9f47706c4 100644 --- a/apps/docs/integrations/opencode.mdx +++ b/apps/docs/integrations/opencode.mdx @@ -11,6 +11,10 @@ This integration requires the **Supermemory Pro plan**. [Upgrade here](https://c [OpenCode-Supermemory](https://github.com/supermemoryai/opencode-supermemory) is an OpenCode plugin that gives your AI persistent memory across sessions. Your agent remembers what you worked on — across sessions, across projects. + +**Prefer to keep everything on your machine?** This plugin works with [self-hosted Supermemory](/self-hosting/overview) — run `npx supermemory local`, then `export SUPERMEMORY_API_URL="http://localhost:6767"` and use the API key printed on first boot. + + ## Get Your API Key Create a Supermemory API key from the [API Keys](https://console.supermemory.ai/keys) page, then add it to your shell profile so it persists across sessions: diff --git a/apps/docs/integrations/supermemory-sdk.mdx b/apps/docs/integrations/supermemory-sdk.mdx index 33c80517d..474976d53 100644 --- a/apps/docs/integrations/supermemory-sdk.mdx +++ b/apps/docs/integrations/supermemory-sdk.mdx @@ -14,6 +14,10 @@ icon: "/images/supermemory.svg" + +Both SDKs also work against [self-hosted Supermemory](/self-hosting/overview) — pass `baseURL: "http://localhost:6767"` (TypeScript) or `base_url="http://localhost:6767"` (Python) when creating the client. + + ## Installation diff --git a/apps/docs/intro.mdx b/apps/docs/intro.mdx index 0712406dd..319a55eac 100644 --- a/apps/docs/intro.mdx +++ b/apps/docs/intro.mdx @@ -82,5 +82,8 @@ All three approaches share the **same context pool** when using the same user ID Understand the knowledge graph architecture + + Run Supermemory on your own machine — one binary, zero config, fully offline + diff --git a/apps/docs/quickstart.mdx b/apps/docs/quickstart.mdx index 963f13896..8953c1755 100644 --- a/apps/docs/quickstart.mdx +++ b/apps/docs/quickstart.mdx @@ -8,6 +8,10 @@ icon: "play" **Using Vercel AI SDK?** Check out the [AI SDK integration](/integrations/ai-sdk) for the cleanest implementation with `@supermemory/tools/ai-sdk`. + +**Prefer to run it locally?** Supermemory is also a [self-hostable single binary](/self-hosting/overview) — `curl -fsSL https://supermemory.ai/install | bash` and you're running. + + ## Memory API **Step 1.** Sign up for [Supermemory's Developer Platform](http://console.supermemory.ai) to get the API key. Click on **API Keys -> Create API Key** to generate one. diff --git a/apps/docs/self-hosting/configuration.mdx b/apps/docs/self-hosting/configuration.mdx new file mode 100644 index 000000000..bde7882f4 --- /dev/null +++ b/apps/docs/self-hosting/configuration.mdx @@ -0,0 +1,105 @@ +--- +title: "Self-Hosting Configuration" +sidebarTitle: "Configuration" +description: "Every environment variable the self-hosted server understands." +icon: "settings" +--- + +The self-hosted server aims for **zero configuration** — the only thing it needs is one model provider key, which the first-boot wizard collects interactively (or set it via env var for non-interactive deployments). Everything else below is opt-in, layered on top as you need it. + +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. + +## Core + +| Variable | Purpose | Default | +|---|---|---| +| `PORT` (or `SUPERMEMORY_PORT`) | HTTP listen port | `6767` | +| `SUPERMEMORY_DATA_DIR` | Where the graph engine's data, auth secret, and model cache live | `./.supermemory` | + +## LLM providers + +In production, Supermemory uses its own proprietary models tuned for long-horizon data understanding. Self-hosted, you bring your own: embeddings are computed locally, and a model of your choice powers the intelligent steps — summaries, contextual chunking, and memory extraction. Configure **at least one**: + +| Variable | Provider | +|---|---| +| `OPENAI_API_KEY` | OpenAI — or any OpenAI-compatible endpoint, see below | +| `ANTHROPIC_API_KEY` | Anthropic | +| `GEMINI_API_KEY` | Google AI Studio (Gemini) | +| `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. + + +Image, video, and high-fidelity PDF understanding require a Gemini or Vertex AI key. Text ingestion, memory extraction, and search work with any provider. + + +### Fully offline with local models + +`OPENAI_API_KEY` + `OPENAI_BASE_URL` covers any OpenAI-compatible endpoint: Ollama, LM Studio, vLLM, llama.cpp server, Together, Fireworks, and more. + +```bash +# Ollama example — gpt-oss-20b works great +OPENAI_BASE_URL=http://localhost:11434/v1 +OPENAI_API_KEY=ollama # any non-empty string for local runners +OPENAI_MODEL=gpt-oss:20b +``` + +| Variable | Purpose | Default | +|---|---|---| +| `OPENAI_BASE_URL` | OpenAI-compatible endpoint URL | OpenAI | +| `OPENAI_MODEL` | Model ID sent to that endpoint | `gpt-5.1` | +| `OPENAI_FAST_MODEL` | Override for fast/light tasks | `OPENAI_MODEL` | +| `OPENAI_TEXT_MODEL` | Override for heavier text tasks | `OPENAI_MODEL` | + +## File storage + +Nothing to configure. Uploaded files (PDFs, images) are stored on local disk inside `$SUPERMEMORY_DATA_DIR` and served by the server at `/files/:key`. + +## Embedding performance + +Local embeddings are prewarmed at startup with conservative defaults — one worker, minimal CPU footprint. Turn these up if you're ingesting heavily and prefer throughput over headroom: + +| 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 | + +## Telemetry + +The self-hosted binary sends no analytics — there is nothing to opt out of. The only related switch: + +| Variable | Purpose | Default | +|---|---|---| +| `SUPERMEMORY_DISABLE_TELEMETRY` | Set to `1` to also disable internal AI SDK telemetry instrumentation | unset | + +## Platform-only features + +These exist in the codebase but are exclusive to the [hosted platform](https://console.supermemory.ai) — the self-hosted binary doesn't include them: + +- **Connectors** — Google Drive, Notion, Gmail, OneDrive background sync +- **Supermemory MCP** — managed MCP server endpoints +- **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. + +## Example: production-ish `.env` + +```dotenv +# Persistent data location +SUPERMEMORY_DATA_DIR=/var/lib/supermemory + +# One LLM provider +OPENAI_API_KEY=sk-... +``` + +That's enough for full ingestion, memory extraction, and hybrid search. diff --git a/apps/docs/self-hosting/local-vs-enterprise.mdx b/apps/docs/self-hosting/local-vs-enterprise.mdx new file mode 100644 index 000000000..3aecdf100 --- /dev/null +++ b/apps/docs/self-hosting/local-vs-enterprise.mdx @@ -0,0 +1,56 @@ +--- +title: "Local vs. Enterprise" +sidebarTitle: "Local vs. Enterprise" +description: "Supermemory local is for builders. Supermemory Enterprise is for organizations." +icon: "building-2" +--- + +Supermemory local — the self-hosted binary — is free, open source, and built for individual developers: local-first workflows, prototyping, air-gapped experiments, privacy-sensitive side projects. + +**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. + +## At a glance + +| | Supermemory local | Enterprise | +|---|---|---| +| **Memory engine** | Full graph engine, embedded | Full graph engine, managed | +| **Models** | Bring your own key (any provider, incl. fully offline) | Proprietary models tuned for long-horizon data understanding | +| **Authentication** | Single auto-generated API key | Organization-wide authentication and access controls | +| **Team access** | Single org on one machine | Multi-member organizations, roles, and scoped API keys | +| **Observability** | Server logs | Control dashboard: usage analytics, ingestion monitoring, request logs | +| **Control** | Env vars on your box | Org-wide settings, key management, and governance from the console | +| **Connectors** | — | Google Drive, Notion, Gmail, OneDrive with continuous background sync | +| **Scalability** | One machine, one process | Globally distributed, scales elastically with your workload | +| **Hosting** | You run it | Fully managed — or dedicated deployments for compliance needs | +| **Support** | Community ([GitHub](https://git.new/memory)) | Dedicated support, onboarding, and SLAs | + +## What Enterprise adds + +### Auth and team access + +Local runs as a single-tenant server with one API key. Enterprise gives your whole organization structured access: member roles, and API keys scoped per environment, per team, or per app — all revocable from one place. + +### Observability and the control dashboard + +Local gives you logs. Enterprise gives you the console: live usage analytics, ingestion pipeline visibility, search and request logs, and per-key attribution — so you always know what your agents are remembering, and what it costs. + +### Memory quality + +Local runs the extraction pipeline on whatever model you bring. Enterprise runs it on Supermemory's proprietary models, purpose-tuned for long-horizon data understanding — higher-quality memories at a lower effective cost than any bring-your-own-key setup. + +### Scale and hosting + +Local is bounded by one machine — which is the point. Enterprise runs on globally distributed infrastructure that scales with your ingestion volume and query load, with no capacity planning on your side. For strict data residency or compliance requirements, dedicated deployment options are available. + +## 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. + + + + Get a walkthrough of Supermemory Enterprise for your team + + + Install the binary and build against the same API today + + diff --git a/apps/docs/self-hosting/overview.mdx b/apps/docs/self-hosting/overview.mdx new file mode 100644 index 000000000..b9db33e44 --- /dev/null +++ b/apps/docs/self-hosting/overview.mdx @@ -0,0 +1,85 @@ +--- +title: "Self-Hosting Supermemory" +sidebarTitle: "Overview" +description: "State-of-the-art memory, running on your machine. One binary, zero config." +icon: "server" +--- + +Supermemory runs on your own hardware. It's the same memory engine behind the [hosted platform](https://console.supermemory.ai) — ingestion, memory extraction, hybrid semantic search, and the full API — as a single self-contained binary. + + +```bash curl +curl -fsSL https://supermemory.ai/install | bash +``` + +```bash npx +npx supermemory local +``` + + +No Docker. No database to provision. No config files. It boots in seconds with everything built in, and it's [open source](https://git.new/memory). + +## Zero config, actually + +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** — vectors are computed on your machine. Nothing is sent anywhere to be embedded. +- **An API key, generated for you** — printed on first boot, ready to paste into any SDK. +- **The full Memory API** — `/v3/documents`, `/v4/search`, `/v4/profile`, spaces, the works. + +The only thing you bring is a model. In production, Supermemory runs its own proprietary models, purpose-tuned for long-horizon data understanding and memory extraction. Self-hosted, the same pipeline runs on whatever model you point it at — OpenAI, Anthropic, Gemini, Groq, or any OpenAI-compatible endpoint. Bring a key and go. Or don't bring one at all: + +## Runs fully offline + +Supermemory works with any OpenAI-compatible endpoint, which means it runs end-to-end on your machine with a local model — Ollama, LM Studio, vLLM, llama.cpp. `gpt-oss-20b` is a great fit: + +```bash +OPENAI_BASE_URL=http://localhost:11434/v1 \ +OPENAI_API_KEY=ollama \ +OPENAI_MODEL=gpt-oss:20b \ +supermemory-server +``` + +Local graph engine, local embeddings, local LLM. Your data never leaves the building. + +## Drop-in with your existing code + +The self-hosted server speaks the same API as the hosted platform. Point any Supermemory SDK at it with a one-line change: + +```typescript +const client = new Supermemory({ + apiKey: "sm_...", // printed on first boot + baseURL: "http://localhost:6767", +}) +``` + +Everything in the [Memory API docs](/quickstart) works the same way. The coding plugins do too — [Claude Code](/integrations/claude-code), [Codex](/integrations/codex), and [OpenCode](/integrations/opencode) all target your local server with `SUPERMEMORY_API_URL=http://localhost:6767`. + +## Self-hosted vs. the platform + +Self-hosted is free, open source, and great for local development, air-gapped environments, and privacy-sensitive workloads. The hosted platform is where the full product lives: + +| | Self-hosted | Platform | +|---|---|---| +| Full Memory API | ✅ | ✅ | +| Hybrid semantic search | ✅ | ✅ | +| Local embeddings | ✅ | Managed | +| File ingestion (PDFs, images) | ✅ | ✅ | +| [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 `baseURL` change away. Running this for a team or organization? See [Local vs. Enterprise](/self-hosting/local-vs-enterprise). + +## Next steps + + + + Install, run, and store your first memory in under two minutes + + + Every environment variable: LLM providers, storage, auth, tuning + + diff --git a/apps/docs/self-hosting/quickstart.mdx b/apps/docs/self-hosting/quickstart.mdx new file mode 100644 index 000000000..713ea98be --- /dev/null +++ b/apps/docs/self-hosting/quickstart.mdx @@ -0,0 +1,151 @@ +--- +title: "Self-Hosting Quickstart" +sidebarTitle: "Quickstart" +description: "From zero to your first memory in under two minutes." +icon: "play" +--- + +## Install + + + +```bash +curl -fsSL https://supermemory.ai/install | bash +``` + + +```bash +npx supermemory local +``` + + +```bash +bunx supermemory local +``` + + + +The installer detects your OS and architecture, downloads the right binary, verifies it, and (when run interactively) prompts you for an LLM API key. Supported platforms: macOS (Apple Silicon & Intel), Linux (x64 & arm64). + +## Run + +```bash +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 │ + └──────────────────────────────────────────────────┘ +``` + +Save that API key — it's your bearer token for every request. + + +In production, Supermemory runs proprietary models tuned for long-horizon data understanding. Self-hosted, you bring any model: if no provider key is set, first boot launches an interactive setup wizard — pick a provider (OpenAI, Anthropic, Gemini, Groq, or any OpenAI-compatible endpoint like Ollama), paste your key, and it's saved encrypted for every future launch. See [all providers](/self-hosting/configuration#llm-providers), including [fully-offline local models](/self-hosting/configuration#fully-offline-with-local-models). + + +## Add your first memory + + + +```typescript +import Supermemory from "supermemory" + +const client = new Supermemory({ + apiKey: "sm_...", + baseURL: "http://localhost:6767", +}) + +await client.memories.add({ + content: "I'm Dhravya. I love building dev tools and I'm allergic to peanuts.", + containerTag: "user_dhravya", +}) +``` + + +```python +from supermemory import Supermemory + +client = Supermemory( + api_key="sm_...", + base_url="http://localhost:6767", +) + +client.memories.add( + content="I'm Dhravya. I love building dev tools and I'm allergic to peanuts.", + container_tag="user_dhravya", +) +``` + + +```bash +curl http://localhost:6767/v3/documents \ + -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.", + "containerTag": "user_dhravya" + }' +``` + + + +## Search it + + + +```typescript +const results = await client.search.memories({ + q: "what food should I avoid?", + containerTag: "user_dhravya", +}) +``` + + +```python +results = client.search.memories( + q="what food should I avoid?", + container_tag="user_dhravya", +) +``` + + +```bash +curl http://localhost:6767/v3/search \ + -H "Authorization: Bearer sm_..." \ + -H "Content-Type: application/json" \ + -d '{ + "q": "what food should I avoid?", + "containerTag": "user_dhravya" + }' +``` + + + +That's it. Everything in the [Memory API](/quickstart) — documents, memories, user profiles, spaces, filtering — works identically against your local server. + +## Where things live + +By default, all state lives in a single directory you can back up or move: + +| Path | Contents | +|---|---| +| `./.supermemory/` (or `$SUPERMEMORY_DATA_DIR`) | The Supermemory graph engine's data, auth secret, embedding model cache | +| `~/.supermemory/env` | API keys saved by the installer, loaded on every launch | + +## Next steps + + + + LLM providers, local models, performance tuning + + + The full API — it all works against your local server + + diff --git a/apps/web/components/integrations-view.tsx b/apps/web/components/integrations-view.tsx index 558660781..6379aa89b 100644 --- a/apps/web/components/integrations-view.tsx +++ b/apps/web/components/integrations-view.tsx @@ -19,7 +19,13 @@ import { AppleShortcutsIcon, RaycastIcon, } from "@/components/integration-icons" -import { GoogleDrive, Notion, OneDrive, MCPIcon } from "@ui/assets/icons" +import { + GoogleDrive, + Notion, + OneDrive, + MCPIcon, + Granola, +} from "@ui/assets/icons" import * as DialogPrimitive from "@radix-ui/react-dialog" import { ArrowLeft, @@ -68,11 +74,12 @@ import { } from "@/lib/plugin-catalog" import { INSET, InstallSteps, PillButton } from "./integrations/install-steps" import { MCPSteps } from "./mcp-modal/mcp-detail-view" +import { GranolaConnectModal } from "./granola-connect-modal" import { detectPluginSpace, detectPluginSource } from "@/lib/plugin-space" type Connection = z.infer -type ConnectorProvider = "google-drive" | "notion" | "onedrive" +type ConnectorProvider = "google-drive" | "notion" | "onedrive" | "granola" interface ConnectedKey { keyId: string @@ -232,6 +239,7 @@ function mcpClientIconSrc(key: MCPClientKey): string { const PLUGIN_SIMPLE_TITLES: Record = { claude_code: "Remembers your code conventions and decisions", codex: "Codex sessions that remember your project", + cursor: "Cursor sessions with persistent project memory", opencode: "OpenCode with persistent project memory", openclaw: "Save chats from Telegram, Discord and Slack", hermes: "Persistent memory for the Hermes agent", @@ -297,6 +305,7 @@ interface BaseItem { icon: ReactNode docsUrl?: string pro?: boolean + max?: boolean kind: ItemKind simpleTitle?: string dev?: boolean @@ -427,6 +436,16 @@ const SECTIONS: Array<{ pro: true, docsUrl: "https://supermemory.ai/docs/connectors/onedrive", }, + { + kind: "connector", + id: "granola", + provider: "granola", + name: "Granola", + tagline: "Sync AI meeting notes into your memory", + simpleTitle: "Your meeting notes, ready to recall", + icon: , + max: true, + }, ], }, { @@ -517,7 +536,7 @@ export function DetailWrapper({ ) } -function ProChip() { +function ProChip({ children = "Pro" }: { children?: ReactNode }) { return ( - Pro + {children} ) } @@ -822,109 +841,124 @@ function ItemInfoDialog({ closeWithReason("dismiss") }} > - e.stopPropagation()} - style={{ - boxShadow: - "0 2.842px 14.211px 0 rgba(0,0,0,0.25), 0.711px 0.711px 0.711px 0 rgba(255,255,255,0.10) inset", - }} - className={cn( - dmSans125ClassName(), - "flex max-h-[88dvh] flex-col gap-3 overflow-hidden border border-white/[0.12] bg-[#1B1F24] p-0 px-3 pt-3 pb-4 text-[#FAFAFA] rounded-2xl md:px-4 sm:max-w-[560px] sm:rounded-[22px]", - )} - > - {name} use cases and docs -
- {icon} -
-

- {name} -

-

- Use cases that apply to this Supermemory connection. -

-
-
- {docsUrl && ( - + e.stopPropagation()} + onClick={(e) => { + e.stopPropagation() + closeWithReason("dismiss") + }} + className="data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 fixed inset-0 z-50 bg-black/50 backdrop-blur-[4px]" + /> + e.stopPropagation()} + onInteractOutside={(e) => e.preventDefault()} + style={{ + boxShadow: + "0 2.842px 14.211px 0 rgba(0,0,0,0.25), 0.711px 0.711px 0.711px 0 rgba(255,255,255,0.10) inset", + }} + className={cn( + dmSans125ClassName(), + "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 fixed top-[50%] left-[50%] z-50 grid w-full max-w-[calc(100%-2rem)] translate-x-[-50%] translate-y-[-50%] duration-100", + "flex max-h-[88dvh] flex-col gap-3 overflow-hidden border border-white/[0.12] bg-[#1B1F24] p-0 px-3 pt-3 pb-4 text-[#FAFAFA] rounded-2xl md:px-4 sm:max-w-[560px] sm:rounded-[22px]", + )} + > + + {name} use cases and docs + +
+ {icon} +
+

+ {name} +

+

+ Use cases that apply to this Supermemory connection. +

+
+
+ {docsUrl && ( + + Docs + + )} + +
+
+
+
- - -
-
-
-
-
- {useCases.map((useCase, index) => ( -
-
- + {useCases.map((useCase, index) => ( +
+
+ + {index + 1} + + {index < useCases.length - 1 && ( + )} - > - {index + 1} - - {index < useCases.length - 1 && ( - - )} -
-
-

- {useCase.title} -

-

- {useCase.description} -

+
+
+

+ {useCase.title} +

+

+ {useCase.description} +

+
-
- ))} + ))} +
-
-
- - {/* biome-ignore lint/a11y/noStaticElementInteractions: closes the info dialog after the nested action button runs. */} - {/* biome-ignore lint/a11y/useKeyWithClickEvents: keyboard handling stays on the nested real button. */} -
closeWithReason("action")}>{actionSlot}
-
- +
+ + {/* biome-ignore lint/a11y/noStaticElementInteractions: closes the info dialog after the nested action button runs. */} + {/* biome-ignore lint/a11y/useKeyWithClickEvents: keyboard handling stays on the nested real button. */} +
closeWithReason("action")}>{actionSlot}
+
+ + ) } @@ -1683,24 +1717,28 @@ function RecentlyAddedCard({ function ItemCard({ actionSlot, + infoActionSlot, icon, id, kind, name, tagline, pro, + max, isNew, docsUrl, leftIndicator, statusSlot, }: { actionSlot: ReactNode + infoActionSlot?: ReactNode icon: ReactNode id: string kind: ItemKind name: string tagline: string pro?: boolean + max?: boolean isNew?: boolean docsUrl?: string leftIndicator?: ReactNode @@ -1726,7 +1764,7 @@ function ItemCard({ > setInfoOpen(true)} /> {isNew && } - {pro && } + {max ? Max : pro && }

(null) const [connectingProvider, setConnectingProvider] = useState(null) + const [granolaModalOpen, setGranolaModalOpen] = useState(false) const [newKey, setNewKey] = useState<{ open: boolean key: string @@ -2286,6 +2327,7 @@ export function IntegrationsView({ "google-drive": [], notion: [], onedrive: [], + granola: [], } for (const c of connections) { const p = c.provider as ConnectorProvider @@ -2383,10 +2425,10 @@ export function IntegrationsView({ } } - const handleUpgrade = async () => { + const handleUpgrade = async (planId: "api_pro" | "api_max" = "api_pro") => { try { const result = await autumn.attach({ - planId: "api_pro", + planId, successUrl: `${window.location.origin}/?view=integrations`, }) if (result?.paymentUrl) { @@ -2808,7 +2850,7 @@ export function IntegrationsView({ } if (needsProUpgrade) { return ( - + handleUpgrade()}> Upgrade ) @@ -2834,29 +2876,44 @@ export function IntegrationsView({ } case "connector": { const count = connectionsByProvider[item.provider].length - const needsProUpgrade = !isAutumnLoading && !hasProProduct + const isGranola = item.provider === "granola" + const needsPlanUpgrade = + !isAutumnLoading && (isGranola ? !hasMaxProduct : !hasProProduct) if (count > 0) { return ( - +

+ + +
) } - if (needsProUpgrade) { + if (needsPlanUpgrade) { return ( - + handleUpgrade(isGranola ? "api_max" : "api_pro")} + > Upgrade ) @@ -2866,6 +2923,14 @@ export function IntegrationsView({ { trackCard(item) + if (isGranola) { + if (!hasMaxProduct) { + handleUpgrade("api_max") + return + } + setGranolaModalOpen(true) + return + } addConnectionMutation.mutate(item.provider) }} disabled={!!connectingProvider} @@ -2941,6 +3006,61 @@ export function IntegrationsView({ } } + const renderInfoRight = (item: Item): ReactNode => { + if (publicMode) return renderRight(item) + + switch (item.kind) { + case "plugin": { + const activeKey = activePluginById.get(item.pluginId) + const needsProUpgrade = + !isAutumnLoading && !hasProProduct && !isFreeTierPlugin(item.pluginId) + if (activeKey) { + const busy = connectingPlugin === item.pluginId + return ( + { + if (needsProUpgrade) { + handleUpgrade() + return + } + trackCard(item) + createPluginKeyMutation.mutate(item.pluginId) + }} + disabled={!!connectingPlugin} + > + {busy ? ( + <> + Connecting… + + ) : ( + "Connect" + )} + + ) + } + return renderRight(item) + } + case "connector": { + const count = connectionsByProvider[item.provider].length + if (count > 0) { + return ( + { + trackCard(item) + void setAddDoc("connect") + }} + > + Connect + + ) + } + return renderRight(item) + } + default: + return renderRight(item) + } + } + const renderStatus = (item: Item): ReactNode => { if (publicMode) return null @@ -2973,12 +3093,14 @@ export function IntegrationsView({
{connectedDialogNeedsPro ? ( - + handleUpgrade()}> Upgrade to connect more @@ -3564,6 +3686,11 @@ export function IntegrationsView({
+ +
) } diff --git a/apps/web/lib/plugin-catalog.ts b/apps/web/lib/plugin-catalog.ts index e1a4ffdee..4653f7f97 100644 --- a/apps/web/lib/plugin-catalog.ts +++ b/apps/web/lib/plugin-catalog.ts @@ -74,6 +74,42 @@ export const PLUGIN_CATALOG: Record = { }, ], }, + cursor: { + id: "cursor", + name: "Cursor", + tagline: "Persistent memory, session hooks, and MCP tools inside Cursor", + icon: "/images/plugins/cursor.png", + docsUrl: "https://github.com/supermemoryai/cursor-supermemory#readme", + githubUrl: "https://github.com/supermemoryai/cursor-supermemory", + installSteps: [ + { + title: "Install the Cursor plugin", + description: + "Install cursor-supermemory from the Cursor Marketplace, then run the auth command on the machine where Cursor runs.", + code: "bunx cursor-supermemory@latest login", + copyLabel: "Login command", + }, + { + title: "Finish browser authentication", + description: + "The login command opens Supermemory in your browser and stores Cursor credentials in ~/.supermemory-cursor/credentials.json.", + }, + { + title: "Manual API-key fallback", + description: + "If browser login is not available, set this environment variable before starting Cursor. This key is shown only once - save it now.", + code: 'export SUPERMEMORY_API_KEY="sm_..."', + copyLabel: "API key command", + secret: true, + optional: true, + }, + { + title: "Restart Cursor", + description: + "Restart Cursor after installing or changing credentials so the plugin hooks and MCP tools are loaded.", + }, + ], + }, opencode: { id: "opencode", name: "OpenCode", @@ -143,6 +179,7 @@ export const PLUGIN_CATALOG: Record = { const SPACE_TO_CATALOG_ID: Record = { "claude-code": "claude_code", codex: "codex", + cursor: "cursor", opencode: "opencode", openclaw: "openclaw", hermes: "hermes",