Skip to main content

​
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

VariableDefaultDescription
OPENAI_API_KEYrequiredOpenAI API key for embeddings and LLM

​
Core

VariableDefaultDescription
DATABASE_URLpostgresql://mengram:mengram@postgres:5432/mengramPostgreSQL connection string
REDIS_URLredis://redis:6379Redis connection string
LLM_PROVIDERopenaiLLM provider (openai, anthropic, ollama)
LLM_MODELgpt-4o-miniModel for memory extraction
BASE_URLhttps://mengram.ioYour instance’s public URL (used in emails, OAuth redirects)

​
Self-hosting

VariableDefaultDescription
DISABLE_EMAIL_VERIFICATIONfalseSkip email verification on signup — returns API key directly
RESEND_API_KEY(optional)Resend API key for sending emails
EMAIL_FROMMengram <onboarding@resend.dev>Sender address for emails

​
GitHub OAuth (optional)

GitHub login is optional — email signup works without it.
VariableDefaultDescription
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
  2. Set the callback URL to http://your-host:8420/auth/github/callback
  3. Add both env vars to your docker-compose.yml

​
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

  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

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.