Skip to main content

​
Prerequisites

  • Docker and Docker Compose v2
  • An embedding provider API key (OpenAI, or set EMBEDDING_PROVIDER=mock for testing)

​
Quick start

git clone https://github.com/Harshitk-cp/engram
cd engram
cp .env.example .env
Edit .env: 
# Required
ENGRAM_SETUP_TOKEN=change-this-to-a-secret-token

# Embeddings (choose one)
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...

# LLM for contradiction detection (optional — omit for embedding-only mode)
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
# or: LLM_PROVIDER=none  (embedding-only, zero LLM calls on store path)
Start everything: 
docker compose up -d --wait
curl http://localhost:8080/health
# {"status":"ok"}

​
Services

The Docker Compose setup includes three services:
ServiceDescription
postgresPostgreSQL 16 with pgvector extension
migrateRuns database migrations and exits
serverThe Engram Go API server

​
Configuration

All configuration is via environment variables:

​
Core

VariableDefaultDescription
SERVER_PORT8080HTTP port
DATABASE_URL—PostgreSQL connection string
ENGRAM_SETUP_TOKEN—Token required to create tenants
LOG_LEVELinfodebug, info, warn, error

​
Embeddings

VariableDefaultDescription
EMBEDDING_PROVIDERopenaiopenai or mock
OPENAI_API_KEY—Required when EMBEDDING_PROVIDER=openai

​
LLM

VariableDefaultDescription
LLM_PROVIDERopenaiopenai, anthropic, gemini, cerebras, mock, none
OPENAI_API_KEY—For LLM_PROVIDER=openai
ANTHROPIC_API_KEY—For LLM_PROVIDER=anthropic
Set LLM_PROVIDER=none to run in embedding-only mode. The memory store path makes zero external LLM API calls. Contradiction detection uses cosine similarity + text heuristics instead. Recommended for high-throughput production deployments.

​
Rate limiting

VariableDefaultDescription
RATE_LIMIT_RPS100Requests per second per tenant
RATE_LIMIT_BURST20Burst allowance

​
Health check

curl http://localhost:8080/health
# {"status":"ok"}

curl http://localhost:8080/metrics
# Server metrics JSON

​
Stopping and resetting

# Stop without losing data
docker compose down

# Stop and wipe all data (clean slate)
docker compose down -v

​
Next steps

Production deployment

Hardening checklist, connection pooling, HA Postgres, monitoring.