Self-hosting

Prerequisites

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

Quick start

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

curl http://localhost:8420/v1/health
# {"status": "ok", "version": "2.22.0"}

Both /health and /v1/health work.

Create your first account

By default, Mengram requires email verification via Resend. For self-hosting without an email provider, set DISABLE_EMAIL_VERIFICATION=true:

environment:
  DISABLE_EMAIL_VERIFICATION: "true"

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

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.

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 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)

Variable	Default	Description
`DISABLE_EMAIL_VERIFICATION`	`false`	Skip email verification on signup — returns API key directly
`RESEND_API_KEY`	(optional)	Resend 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:

Create a GitHub OAuth App at github.com/settings/developers
Set the callback URL to http://your-host:8420/auth/github/callback
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:

environment:
  EMBEDDING_PROVIDER: cohere
  COHERE_API_KEY: your-cohere-key

Get a Cohere API key at dashboard.cohere.com. The trial tier is free and rate-limited — sufficient for development and small workloads.

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).

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:

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:

ollama pull llama3.2

Use with LM Studio

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

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)

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

VS Code extension

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

Claude Code hooks

export MENGRAM_API_KEY=om-your-key
export MENGRAM_URL=http://localhost:8420
mengram hook install

Python SDK

from mengram import Mengram

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

JavaScript SDK

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:

docker compose exec postgres pg_dump -U mengram mengram > backup.sql

To restore:

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

The easiest way to deploy is Railway — just connect your GitHub repo and set environment variables. Mengram’s cloud version runs on Railway.

Getting Started

Concepts

SDKs

Integrations

Reference

Self-hosting

Prerequisites

Quick start

Verify it’s running

Create your first account

Configuration

Required

Core

Self-hosting

GitHub OAuth (optional)

Multilingual support (Cohere)

Use with Ollama (fully local)

Use with LM Studio

Use with OpenRouter

Connect your tools

MCP server (Claude Desktop, Cursor, Windsurf)

VS Code extension

Claude Code hooks

Python SDK

JavaScript SDK

Data persistence

Production deployment

​Prerequisites

​Quick start

​Verify it’s running

​Create your first account

​Configuration

​Required

​Core

​Self-hosting

​GitHub OAuth (optional)

​Multilingual support (Cohere)

​Use with Ollama (fully local)

​Use with LM Studio

​Use with OpenRouter

​Connect your tools

​MCP server (Claude Desktop, Cursor, Windsurf)

​VS Code extension

​Claude Code hooks

​Python SDK

​JavaScript SDK

​Data persistence

​Production deployment

Prerequisites

Quick start

Verify it’s running

Create your first account

Configuration

Required

Core

Self-hosting

GitHub OAuth (optional)

Multilingual support (Cohere)

Use with Ollama (fully local)

Use with LM Studio

Use with OpenRouter

Connect your tools

MCP server (Claude Desktop, Cursor, Windsurf)

VS Code extension

Claude Code hooks

Python SDK

JavaScript SDK

Data persistence

Production deployment