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/health
# {"status": "ok"}

​
Configuration

Environment variables in docker-compose.yml:
VariableDefaultDescription
DATABASE_URLpostgresql://mengram:mengram@postgres:5432/mengramPostgreSQL connection string
REDIS_URLredis://redis:6379Redis connection string
OPENAI_API_KEYrequiredOpenAI API key for embeddings and LLM
LLM_PROVIDERopenaiLLM provider (openai, anthropic, ollama)
LLM_MODELgpt-4o-miniModel for memory extraction

​
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

​
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
The easiest way to deploy is Railway — just connect your GitHub repo and set environment variables. Mengram’s cloud version runs on Railway.