MemgraphAI

Self-Hosted Deployment

Deploy Memgraph on your own infrastructure. Full control over your data, no external dependencies except PostgreSQL and an OpenAI API key.

Requirements

PostgreSQL 15+

Required

With pgvector extension installed. Required for vector search and embeddings.

Python 3.10+

Required

For running the API server. 3.11+ recommended.

OpenAI API Key

Required

Used for belief extraction, episode summarization, and Cognitive Dreaming.

Node.js 20+

Only needed if you want to run the Studio dashboard.

Redis

Optional. Enables distributed rate limiting and context caching in multi-instance setups.

Docker

Optional. Simplifies deployment — recommended for production.

Docker Compose (Recommended)

The project includes a docker-compose.yml that runs PostgreSQL with pgvector. The API can optionally run in Docker too.

Quick start: The default compose file starts just the database. Add the --profile full flag to also start the API server in Docker.

yaml
# docker-compose.yml (included in repo)
services:
  db:
    image: pgvector/pgvector:pg15
    container_name: memgraph-db
    environment:
      POSTGRES_USER: memgraph
      POSTGRES_PASSWORD: password
      POSTGRES_DB: memgraph_os
    ports:
      - "5432:5432"
    volumes:
      - memgraph_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U memgraph"]
      interval: 5s
      timeout: 5s
      retries: 5

  api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8001:8001"
    environment:
      - DATABASE_URL=postgresql+asyncpg://memgraph:password@db:5432/memgraph_os
      - SECRET_KEY=local-dev-secret-key-minimum-32-chars
      - ENVIRONMENT=development
      - APP_PORT=8001
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    depends_on:
      db:
        condition: service_healthy
    profiles:
      - full  # only starts with --profile full

volumes:
  memgraph_data:
bash
# Start database only (run API locally for development)
docker compose up -d

# Or start everything (database + API)
OPENAI_API_KEY=sk-your-key docker compose --profile full up -d

# Check health
curl http://localhost:8001/health

# View logs
docker compose logs -f api

Production Docker Compose

For production, override the defaults with secure credentials:

yaml
# docker-compose.prod.yml
services:
  db:
    image: pgvector/pgvector:pg15
    environment:
      POSTGRES_USER: memgraph
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: memgraph_os
    volumes:
      - memgraph_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U memgraph"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  api:
    build: .
    ports:
      - "8001:8001"
    environment:
      - DATABASE_URL=postgresql+asyncpg://memgraph:${DB_PASSWORD}@db:5432/memgraph_os
      - SECRET_KEY=${SECRET_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ENVIRONMENT=production
      - APP_PORT=8001
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

volumes:
  memgraph_data:
bash
# Generate secure credentials
export SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
export DB_PASSWORD=$(python3 -c "import secrets; print(secrets.token_urlsafe(16))")
export OPENAI_API_KEY=sk-your-key-here

# Start production
docker compose -f docker-compose.prod.yml up -d

Migrations: The Dockerfile runs Alembic migrations automatically on startup via start_railway.sh. The database schema is created and updated before the API starts.

Bare Metal

Run directly on a server without Docker. Contact us at [email protected] for access to the source code for bare-metal deployments.

bash
# 1. Install Python dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install .
python -m spacy download en_core_web_sm

# 2. Set up PostgreSQL with pgvector
sudo apt install postgresql-15 postgresql-15-pgvector
sudo -u postgres createdb memgraph_os
sudo -u postgres psql -c "CREATE USER memgraph WITH PASSWORD 'your-password';"
sudo -u postgres psql -c "GRANT ALL ON DATABASE memgraph_os TO memgraph;"
sudo -u postgres psql -d memgraph_os -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 3. Configure environment
cp .env.example .env
# Edit .env — set DATABASE_URL, SECRET_KEY, OPENAI_API_KEY

# 4. Run database migrations
alembic upgrade head

# 5. Start the API server
python -m uvicorn src.main:app --host 0.0.0.0 --port 8001

Kubernetes (Helm Chart)

The repo includes a production-ready Helm chart at deploy/helm/memgraph/ with Deployment, Service, HPA, Ingress, resource limits, and health probes.

1. Build & push your image

bash
# Build the API image
docker build -t your-registry/memgraph-api:latest .

# Push to your registry
docker push your-registry/memgraph-api:latest

2. Create the Kubernetes Secret

bash
kubectl create secret generic memgraph-secrets \
  --from-literal=DATABASE_URL="postgresql+asyncpg://user:pass@db-host:5432/memgraph_os" \
  --from-literal=SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')" \
  --from-literal=OPENAI_API_KEY="sk-your-key-here"

3. Install with Helm

bash
helm install memgraph deploy/helm/memgraph/ \
  --set image.repository=your-registry/memgraph-api \
  --set image.tag=latest

Helm values overview

Key settings in values.yaml:

yaml
# deploy/helm/memgraph/values.yaml
replicaCount: 2

image:
  repository: memgraph/memgraph-api
  tag: latest
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 8001

resources:
  limits:
    cpu: "1"
    memory: 1Gi
  requests:
    cpu: 250m
    memory: 512Mi

# Horizontal Pod Autoscaler
autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

# Ingress (nginx example)
ingress:
  enabled: false
  className: nginx
  hosts:
    - host: api.memgraph.local
      paths:
        - path: /
          pathType: Prefix
  tls: []

# Redis for distributed rate limiting (optional)
redis:
  enabled: false
  externalUrl: ""

# Secrets — references K8s Secret "memgraph-secrets"
# with keys: DATABASE_URL, SECRET_KEY, OPENAI_API_KEY
secretName: memgraph-secrets

env:
  ENVIRONMENT: production
  APP_PORT: "8001"
  DREAMING__ENABLED: "true"
  DREAMING__INTERVAL_MINUTES: "10"

Enable Ingress

bash
helm upgrade memgraph deploy/helm/memgraph/ \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=api.yourdomain.com \
  --set ingress.hosts[0].paths[0].path=/ \
  --set ingress.hosts[0].paths[0].pathType=Prefix

Enable autoscaling

bash
helm upgrade memgraph deploy/helm/memgraph/ \
  --set autoscaling.enabled=true \
  --set autoscaling.minReplicas=2 \
  --set autoscaling.maxReplicas=10 \
  --set autoscaling.targetCPUUtilizationPercentage=70

Database: The Helm chart expects an external PostgreSQL database (managed service like RDS, Cloud SQL, Supabase, or Neon). Set the connection string in the memgraph-secrets Secret.

Migrations: The Docker image runs Alembic migrations on startup via start_railway.sh. With multiple replicas, the first pod to start will run migrations — subsequent pods will see the schema already exists. This is safe for concurrent startup.

Multi-replica: Enable Redis when running 2+ replicas. Without it, each pod tracks rate limits independently and context caching is per-pod (no sharing).

Kubernetes (Raw YAML)

If you prefer raw manifests over Helm:

yaml
# 1. Secret
apiVersion: v1
kind: Secret
metadata:
  name: memgraph-secrets
type: Opaque
stringData:
  DATABASE_URL: "postgresql+asyncpg://user:pass@db:5432/memgraph_os"
  SECRET_KEY: "your-32-char-secret-key-here-min"
  OPENAI_API_KEY: "sk-your-key-here"
---
# 2. Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: memgraph-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: memgraph-api
  template:
    metadata:
      labels:
        app: memgraph-api
    spec:
      containers:
        - name: api
          image: your-registry/memgraph-api:latest
          ports:
            - containerPort: 8001
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: memgraph-secrets
                  key: DATABASE_URL
            - name: SECRET_KEY
              valueFrom:
                secretKeyRef:
                  name: memgraph-secrets
                  key: SECRET_KEY
            - name: OPENAI_API_KEY
              valueFrom:
                secretKeyRef:
                  name: memgraph-secrets
                  key: OPENAI_API_KEY
            - name: ENVIRONMENT
              value: "production"
            - name: APP_PORT
              value: "8001"
          resources:
            requests:
              cpu: 250m
              memory: 512Mi
            limits:
              cpu: "1"
              memory: 1Gi
          livenessProbe:
            httpGet:
              path: /health
              port: 8001
            initialDelaySeconds: 15
            periodSeconds: 30
          readinessProbe:
            httpGet:
              path: /health
              port: 8001
            initialDelaySeconds: 5
            periodSeconds: 10
---
# 3. Service
apiVersion: v1
kind: Service
metadata:
  name: memgraph-api
spec:
  selector:
    app: memgraph-api
  ports:
    - port: 8001
      targetPort: 8001
      protocol: TCP
  type: ClusterIP

Environment Variables

Full reference from .env.example. Nested settings use __ delimiter (e.g. LLM__EXTRACTION_MODEL).

VariableReqDefaultDescription
DATABASE_URLYes—PostgreSQL connection string (postgresql+asyncpg://user:pass@host:5432/db)
SECRET_KEYYes—JWT signing key. Minimum 32 characters
OPENAI_API_KEYYes—OpenAI key for extraction, summarization, dreaming
APP_HOSTNo0.0.0.0Server bind address
APP_PORTNo8001Server port
ENVIRONMENTNoproductionproduction, development, or staging. Dev mode allows anonymous access
API_BASE_URLNoautoPublic API URL (e.g. https://api.yourdomain.com). Auto-derived from host/port if empty
STUDIO_URLNoautoStudio dashboard URL. Auto-derived if empty
STUDIO_PORTNo3000Studio port (used for auto-derived URL)

LLM Models

VariableReqDefaultDescription
LLM__EXTRACTION_MODELNogpt-4o-miniModel for belief extraction from conversations
LLM__SUMMARIZATION_MODELNogpt-4o-miniModel for episode summarization
LLM__REASONING_MODELNogpt-4o-miniModel for complex reasoning tasks

Cognitive Dreaming

VariableReqDefaultDescription
DREAMING__ENABLEDNotrueEnable background belief consolidation
DREAMING__INTERVAL_MINUTESNo10How often the dreaming worker runs
DREAMING__LOOKBACK_MINUTESNo30How far back to look for pending episodes

Caching & Performance

VariableReqDefaultDescription
CACHE__ENABLEDNotrueEnable Redis context caching
CACHE__REDIS_URLNoredis://localhost:6379/0Redis connection URL
DB_POOL_SIZENo20Database connection pool size
DB_MAX_OVERFLOWNo30Max overflow connections beyond pool size
LOG_LEVELNoINFOLogging level (DEBUG, INFO, WARNING, ERROR)

Database Options

Memgraph requires PostgreSQL with pgvector. No other databases are supported. Migrations run automatically via Alembic on startup.

Self-managed PostgreSQL

Install pgvector extension manually. Best for full control.

AWS RDS

PostgreSQL 15+ with pgvector support (available since 2023).

Supabase

pgvector pre-installed. Use the connection string from your project settings.

Neon

Serverless Postgres with pgvector. Good for development.

Google Cloud SQL

PostgreSQL with pgvector extension enabled.

Azure Flexible Server

Azure PostgreSQL supports pgvector.

Not supported: MySQL, SQLite, MongoDB. Memgraph uses PostgreSQL-specific features (pgvector, JSONB, UUID, recursive CTEs) extensively.