Install

This page is for self-hosting the engine yourself. If you just want to use Ergo, skip this — see Quickstart to connect your agent to the hosted endpoint at https://api.ergomem.com/mcp in one line, no install required.

Ergo has two parts:

1. The engine — a self-contained Docker image that serves the HTTP API.
2. The MCP adapter — a thin stdio client that lets a coding agent host talk to the engine as MCP tools.

You run the engine once; each agent host points its adapter at it.

Requirements

• Docker to build and run the engine.
• Network access once, at build time, so the image can bake the embedder and NLI model. After that the default configuration runs fully offline.
• For the MCP adapter: Python with pip.

There are no external services to stand up. The image bundles SQLite + sqlite-vec, the embedder, the NLI model, and a stdlib http.server — no web framework, no separate vector DB.

Run the engine

The container listens on port 8000. The convention is to map it to host 8788:

docker build -t ergo .                       # bakes embedder + NLI (needs network once)
docker run -d --name ergo -p 8788:8000 \
  -e ERGO_API_TOKEN=your-secret-token \
  -v ergo-data:/data \
  ergo

The -v ergo-data:/data volume persists the SQLite store (default /data/ergo.db) across container restarts.

Auth: set ERGO_API_TOKEN and every endpoint except /health requires Authorization: Bearer <token>. Omit it and the API is open — acceptable for local dev/test only, and the server prints a warning at boot.

Verify it's working

/health needs no auth and is the right liveness probe:

curl -s http://127.0.0.1:8788/health

A healthy response reports status: ok and retrieval: true (retrieval true means recall/why/ingest are all available), plus the active embedder and NLI model. For deeper operational detail — live counts, conflict telemetry, and version drift — call /diagnose (this one needs the token).

Embedding providers

Ergo embeds every claim so it can be recalled semantically. The provider is chosen with ERGO_EMBED_PROVIDER, and the embedding dimension is locked at the first write — so decide before you start storing claims. Switching providers to a different dimension later means starting a fresh store.

How to pick: the default fastembed needs nothing and runs offline — use it unless you have a reason not to. Choose a hosted provider (openai, cohere, voyage) if you want higher-dimensional embeddings and don't mind an API dependency, or ollama if you already run one locally and want larger vectors while staying self-hosted.

Key environment variables

For a multi-tenant deployment (see Multi-tenancy) there are three more, all optional — the engine runs single-tenant without them:

Install the MCP adapter

The adapter is a thin HTTP client over the API — it never opens the SQLite file directly. Install it with the mcp extra (pulls in the MCP SDK and a pinned httpx):

pip install ".[mcp]"

Run it, pointing it at your engine:

ERGO_API_URL=http://127.0.0.1:8788 \
ERGO_API_TOKEN=your-secret-token \
  python -m ergo.mcp.server          # speaks MCP over stdio

The adapter speaks MCP over stdio, so a host launches it as a subprocess rather than connecting over a socket. See MCP tools for the tool reference and Recipes for a ready-to-paste .mcp.json entry.