Install

Ergo has two parts:

The engine — a self-contained Docker image that serves the HTTP API.
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.

Provider	Needs	Default model	Dim
`fastembed` (default, baked)	nothing — offline	bge-small-en-v1.5	384
`ollama`	a reachable Ollama	nomic-embed-text	768
`openai`	`OPENAI_API_KEY`	text-embedding-3-small	1536
`cohere`	`COHERE_API_KEY`	embed-english-v3.0	1024
`voyage`	`VOYAGE_API_KEY`	voyage-3-lite	512

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

Variable	Purpose	Default
`ERGO_API_TOKEN`	Bearer token for the API (unset = open)	—
`ERGO_API_URL`	Where the MCP adapter reaches the engine	—
`ERGO_DB_PATH`	SQLite store path inside the container	`/data/ergo.db`
`ERGO_HTTP_HOST`	Host the engine binds to	—
`ERGO_HTTP_PORT`	Port the engine listens on	`8000`
`ERGO_EMBED_PROVIDER`	Embedding provider (see table above)	`fastembed`
`ERGO_BACKUP_PATH`	Where backups are written	—

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.