Self-Hosting

Quick Start

The fastest way to get Engrammic running locally:

curl -fsSL https://get.engrammic.ai/install.sh | sh
engrammic selfhost

The wizard will:

1. Check Docker is running
2. Validate your license key
3. Configure ports and storage
4. Set up LLM integration (optional)
5. Start the services
6. Configure your code editor

Deployment Tiers

Choose a tier based on your hardware and whether you want fully local inference:

Standalone tiers (Lite/Standard/Pro) bundle Ollama and TEI so everything runs locally with no external API calls after initial model download. Cloud tier uses your existing API keys. The installer auto-detects your RAM and recommends a tier.

Requirements

• Docker 20.10+ with Compose v2
• RAM per tier (see table above)
• 20GB disk space (standalone tiers need more for model storage)
• License key from engrammic.ai/self-hosted

CLI Reference

Installation Commands

Management Commands

Log Viewing

# Interactive service selection
engrammic logs

# Specific service
engrammic logs --service app

# Follow logs
engrammic logs --service app --follow

# Show more lines
engrammic logs --service dagster --lines 500

Available services: app, reaction-worker, dagster, dagster-daemon, memgraph, qdrant, redis, postgres

Configuration

After running engrammic selfhost, your configuration is stored in ~/.engrammic/:

~/.engrammic/
  docker-compose.yml   # Service definitions
  .env                 # Configuration
  README.md            # Quick reference

Environment Variables

Edit ~/.engrammic/.env to configure:

# License (required)
ENGRAMMIC_LICENSE_KEY=ENGR_...

# Database
POSTGRES_PASSWORD=your-secure-password

# Embedding model (required, otherwise remember/learn/recall fail)
EMBEDDING_MODEL=openai/text-embedding-3-small
OPENAI_API_KEY=sk-...

# Telemetry (opt out with false)
TELEMETRY__ENABLED=true

The embedding model is the required piece, and you set it here with EMBEDDING_MODEL plus its provider key. The generation LLM is optional and is configured differently (see below). See Configuration for the full variable reference and Running Models Locally to run either without cloud keys.

Choosing the generation LLM

The SAGE generation LLM provider and model live in config/models.yaml, not in .env. The default tier uses Google Vertex (Gemini). To use a different provider:

1. Override models.yaml through the host config directory (see Config Files).
2. Set the active tier's reasoning, fast, and query_expander entries to your provider and model.
3. Supply that provider's credentials in .env:

Without usable LLM credentials, Engrammic runs in passive mode: storage and recall work, but SAGE synthesis (automatic deduplication, insight generation) is disabled.

Custom Ports

During engrammic selfhost, you can configure custom ports:

• MCP server: Default 8000 (your editor connects here)
• Dagster UI: Default 3000 (SAGE pipeline dashboard)

After setup, edit docker-compose.yml to change internal service ports.

Upgrading

Pull the latest images and restart:

engrammic upgrade

This will:

1. Pull new images
2. Restart services
3. Clean up old images

Version deprecation warnings appear in logs when running outdated versions.

Backup and Restore

Manual Backup

cd ~/.engrammic

# Stop services
docker compose down

# Backup volumes
docker run --rm -v engrammic_postgres-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/postgres-backup.tar.gz -C /data .

docker run --rm -v engrammic_qdrant-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/qdrant-backup.tar.gz -C /data .

docker run --rm -v engrammic_memgraph-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/memgraph-backup.tar.gz -C /data .

# Restart
docker compose up -d

Restore

cd ~/.engrammic
docker compose down

# Restore volumes (example for postgres)
docker run --rm -v engrammic_postgres-data:/data -v $(pwd):/backup alpine \
  sh -c "rm -rf /data/* && tar xzf /backup/postgres-backup.tar.gz -C /data"

docker compose up -d

Troubleshooting

Health Check

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "services": {
    "memgraph": "connected",
    "redis": "connected",
    "qdrant": "connected",
    "postgres": "connected"
  }
}

Diagnostics

engrammic doctor

Checks:

• Docker daemon status
• Container health
• Service connectivity
• License validity

Common Issues

Services not starting:

docker compose logs app

Port already in use: Run engrammic selfhost again and choose a different port.

License expired:

engrammic license

Out of memory:

engrammic scale

Manual Setup

If you prefer manual configuration over the CLI wizard:

Standalone Tiers (Lite/Standard/Pro)

For fully local deployment with bundled models:

mkdir -p ~/.engrammic && cd ~/.engrammic

# Choose one:
# Lite (8GB RAM)
curl -fsSL https://raw.githubusercontent.com/engrammic-ai/context-service/main/docker/docker-compose.standalone-lite.yml -o docker-compose.yml

# Standard (24-32GB RAM)
curl -fsSL https://raw.githubusercontent.com/engrammic-ai/context-service/main/docker/docker-compose.standalone-standard.yml -o docker-compose.yml

# Pro (48-64GB RAM)
curl -fsSL https://raw.githubusercontent.com/engrammic-ai/context-service/main/docker/docker-compose.standalone-pro.yml -o docker-compose.yml

cat > .env << 'EOF'
# License (required)
ENGRAMMIC_LICENSE_KEY=ENGR_your_key_here

# Database
POSTGRES_PASSWORD=your-secure-password

# Telemetry (opt out with false)
TELEMETRY__ENABLED=true
EOF

docker compose up -d

docker compose logs -f ollama

{
  "mcpServers": {
    "engrammic": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Cloud Tier

For deployment using your own API keys:

mkdir -p ~/.engrammic && cd ~/.engrammic

curl -fsSL https://raw.githubusercontent.com/engrammic-ai/context-service/main/docker/docker-compose.selfhosted.yml -o docker-compose.yml

cat > .env << 'EOF'
ENGRAMMIC_LICENSE_KEY=ENGR_your_key_here
POSTGRES_PASSWORD=your-secure-password

# Embedding model (required)
EMBEDDING_MODEL=openai/text-embedding-3-small
OPENAI_API_KEY=sk-...

TELEMETRY__ENABLED=true

# Optional: LLM for SAGE synthesis (provider/model set in models.yaml; supply its key)
# OPENAI_API_KEY=sk-...
EOF

docker compose up -d

{
  "mcpServers": {
    "engrammic": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Architecture

The self-hosted stack includes:

Standalone tiers add:

Memory requirements by tier:

• Cloud: ~5GB
• Lite: ~8GB
• Standard: ~24GB
• Pro: ~48GB

Kubernetes Deployment

If you need Kubernetes deployment before official charts are available, email founders@engrammic.ai and we can help with your setup.

Cloud Provider Guides

Guides for deploying on AWS, GCP, and Azure are in development. The Docker Compose setup works on any cloud VM with Docker installed.

Get Access

Self-hosting requires a license key. Request one at engrammic.ai/self-hosted or email founders@engrammic.ai.

Helpful Links

• engrammic.ai/self-hosted - license keys and release notes
• Configuration reference - full environment variable reference
• Running Models Locally - Ollama and TEI setup, no cloud keys required
• LiteLLM - embedding and LLM routing used internally
• Ollama - run LLMs and embedding models locally
• Hugging Face Text Embeddings Inference - high-throughput embedding sidecar
• Qdrant documentation - vector database
• Memgraph documentation - graph database
• Dagster documentation - SAGE pipeline orchestration