Self-Hosting

Quick Start

The fastest way to get Engrammic running locally:

curl -fsSL https://get.engrammic.ai | 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

Requirements

• Docker 20.10+ with Compose v2
• 5GB RAM minimum (8GB recommended)
• 20GB disk space
• License key from engrammic.ai/self-hosted

Fully-local turnkey images (standalone and standalone-lite, with models bundled) are also available. Documentation for those is coming separately.

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:

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

curl -fsSL https://raw.githubusercontent.com/engrammic-ai/mcp/main/docker-compose.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:

Total memory: ~5GB (8GB recommended for production workloads)

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