> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mengram.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-hosting

> Run Mengram on your own infrastructure with Docker Compose — PostgreSQL, Redis, and Mengram API in one command.

## Prerequisites

* Docker and Docker Compose
* An OpenAI API key (or compatible LLM provider)

## Quick start

```bash theme={null}
git clone https://github.com/alibaizhanov/mengram.git
cd mengram

# Set your OpenAI API key
export OPENAI_API_KEY=sk-your-key

# Start everything
docker compose up -d
```

This starts three services:

* **PostgreSQL 16** on port 5432
* **Redis 7** on port 6379
* **Mengram API** on port 8420

## Verify it's running

```bash theme={null}
curl http://localhost:8420/v1/health
# {"status": "ok", "version": "2.22.0"}
```

<Note>
  Both `/health` and `/v1/health` work.
</Note>

## Create your first account

By default, Mengram requires email verification via [Resend](https://resend.com). For self-hosting without an email provider, set `DISABLE_EMAIL_VERIFICATION=true`:

```yaml theme={null}
environment:
  DISABLE_EMAIL_VERIFICATION: "true"
```

With this enabled, the signup endpoint returns your API key immediately — no verification code needed.

<Tip>
  If you prefer to keep email verification, set `RESEND_API_KEY` and `EMAIL_FROM` (see Configuration below). Without Resend, verification codes are logged to stdout — check `docker compose logs mengram` to find them.
</Tip>

## Configuration

Environment variables in `docker-compose.yml`:

### Required

| Variable         | Default  | Description                           |
| ---------------- | -------- | ------------------------------------- |
| `OPENAI_API_KEY` | required | OpenAI API key for embeddings and LLM |

### Core

| Variable             | Default                                              | Description                                                                                                |
| -------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL`       | `postgresql://mengram:mengram@postgres:5432/mengram` | PostgreSQL connection string                                                                               |
| `REDIS_URL`          | `redis://redis:6379`                                 | Redis connection string                                                                                    |
| `LLM_PROVIDER`       | `openai`                                             | LLM provider (`openai`, `anthropic`, `ollama`)                                                             |
| `LLM_MODEL`          | `gpt-4o-mini`                                        | Model for memory extraction                                                                                |
| `EMBEDDING_PROVIDER` | `openai`                                             | Embedding provider (`openai` or `cohere`). See [Multilingual support](#multilingual-support-cohere) below. |
| `COHERE_API_KEY`     | *(required if cohere)*                               | Cohere API key — needed when `EMBEDDING_PROVIDER=cohere`                                                   |
| `BASE_URL`           | `https://mengram.io`                                 | Your instance's public URL (used in emails, OAuth redirects)                                               |

### Self-hosting

| Variable                     | Default                           | Description                                                  |
| ---------------------------- | --------------------------------- | ------------------------------------------------------------ |
| `DISABLE_EMAIL_VERIFICATION` | `false`                           | Skip email verification on signup — returns API key directly |
| `RESEND_API_KEY`             | *(optional)*                      | [Resend](https://resend.com) API key for sending emails      |
| `EMAIL_FROM`                 | `Mengram <onboarding@resend.dev>` | Sender address for emails                                    |

### GitHub OAuth (optional)

GitHub login is optional — email signup works without it.

| Variable               | Default      | Description                    |
| ---------------------- | ------------ | ------------------------------ |
| `GITHUB_CLIENT_ID`     | *(optional)* | GitHub OAuth App client ID     |
| `GITHUB_CLIENT_SECRET` | *(optional)* | GitHub OAuth App client secret |

To enable GitHub login:

1. Create a GitHub OAuth App at [github.com/settings/developers](https://github.com/settings/developers)
2. Set the callback URL to `http://your-host:8420/auth/github/callback`
3. Add both env vars to your `docker-compose.yml`

## Multilingual support (Cohere)

Mengram cloud uses Cohere `embed-multilingual-v3.0` for native quality across 23 languages — Russian, Chinese, Spanish, Japanese, Korean, Arabic, and more. To use the same on a self-hosted instance:

```yaml theme={null}
environment:
  EMBEDDING_PROVIDER: cohere
  COHERE_API_KEY: your-cohere-key
```

Get a Cohere API key at [dashboard.cohere.com](https://dashboard.cohere.com). The trial tier is free and rate-limited — sufficient for development and small workloads.

<Tip>
  Stick with the default `EMBEDDING_PROVIDER=openai` (uses `text-embedding-3-large`, 1536 dim) if your data is mostly English. Switch to Cohere if you have non-English users or need cross-lingual retrieval (e.g. English queries finding Russian documents).
</Tip>

Embeddings are written to a separate `embedding_v2` column (1024 dim) so you can switch providers without losing existing data — Mengram routes search to the right column based on query vector size.

## Use with Ollama (fully local)

Run Mengram with a local LLM — no external API calls:

```yaml theme={null}
environment:
  LLM_PROVIDER: ollama
  LLM_MODEL: llama3.2
  OLLAMA_HOST: http://host.docker.internal:11434
```

Make sure Ollama is running on your host machine with the model pulled:

```bash theme={null}
ollama pull llama3.2
```

## Use with LM Studio

```yaml theme={null}
environment:
  LLM_PROVIDER: openai
  LLM_MODEL: your-model-name
  OPENAI_API_KEY: lm-studio
  OPENAI_API_BASE: http://host.docker.internal:1234/v1
```

## Use with OpenRouter

```yaml theme={null}
environment:
  LLM_PROVIDER: openai
  LLM_MODEL: qwen/qwen3.6-plus:free
  OPENAI_API_KEY: sk-or-v1-your-key
  OPENAI_BASE_URL: https://openrouter.ai/api/v1
```

## Connect your tools

### MCP server (Claude Desktop, Cursor, Windsurf)

```json theme={null}
{
  "mcpServers": {
    "mengram": {
      "command": "uvx",
      "args": ["mengram-ai"],
      "env": {
        "MENGRAM_API_KEY": "om-your-key",
        "MENGRAM_URL": "http://localhost:8420"
      }
    }
  }
}
```

### VS Code extension

1. Install the **Mengram** extension from the marketplace
2. Open Settings and set:
   * `mengram.apiKey` → your API key
   * `mengram.baseUrl` → `http://localhost:8420`

### Claude Code hooks

```bash theme={null}
export MENGRAM_API_KEY=om-your-key
export MENGRAM_URL=http://localhost:8420
mengram hook install
```

### Python SDK

```python theme={null}
from mengram import Mengram

m = Mengram(api_key="om-your-key", base_url="http://localhost:8420")
```

### JavaScript SDK

```javascript theme={null}
import { MengramClient } from 'mengram-ai';

const m = new MengramClient('om-your-key', 'http://localhost:8420');
```

## Data persistence

PostgreSQL data is stored in a Docker volume (`pgdata`). Your memories persist across container restarts.

To backup:

```bash theme={null}
docker compose exec postgres pg_dump -U mengram mengram > backup.sql
```

To restore:

```bash theme={null}
docker compose exec -T postgres psql -U mengram mengram < backup.sql
```

## Production deployment

For production, consider:

* Use a managed PostgreSQL (e.g., Supabase, Neon, RDS)
* Use a managed Redis (e.g., Upstash, ElastiCache)
* Set strong database passwords
* Put behind a reverse proxy with TLS (nginx, Caddy)
* Set `GUNICORN_WORKERS` for concurrency
* Set `BASE_URL` to your public domain

<Tip>
  The easiest way to deploy is [Railway](https://railway.app) — just connect your GitHub repo and set environment variables. Mengram's cloud version runs on Railway.
</Tip>