Welcome to Ergo

Ergo is a decision-memory backend for AI coding agents. Most agent memory does notes plus similarity search — it can tell you what was said. Ergo adds the parts that keep an agent honest over time:

• Reasons — every decision is stored with the rationale behind it.
• History — decisions are append-only; you can see how a belief evolved.
• Supersede-with-why — when a choice changes, the new claim links back to the old one and records why it changed.
• Contradiction auditing — a guarded write checks a new claim against what the store already believes and blocks a hard contradiction before it lands.

These are first-class types, not conventions layered on top of a note store.

Who is this for?

Ergo is selective safety rails for high-stakes, slow-changing decisions — conventions, configs, policies, architecture choices — not a universal memory firewall for every scrap of chatter. It earns its keep where a stale or reversed decision is expensive.

It's for developers running long-lived coding agents (Claude Code, OpenCode, Codex CLI, Cursor background agents, and anything that speaks MCP) who want their agent to:

1. Not silently reverse a decision whose rationale is already on file.
2. Explain itself — recall not just the current belief but why it holds and what it replaced.
3. Catch a contradiction at write time, before it pollutes the store.

How it works, in one breath

One store, two behaviors. Facts upsert freely (reason optional). Decisions, constraints, rejections, and conventions are append-only, require a reason, and change only through supersede. Everything lives in one SQLite file with one embedding space and one backup.

Quick start

Ergo ships as a self-contained Docker image (SQLite + sqlite-vec, the embedder and NLI model baked in, stdlib http.server — no external services). The container listens on port 8000, conventionally mapped 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
curl -s http://127.0.0.1:8788/health         # liveness (no auth)

Then point your agent at the MCP adapter (see Install) and every decision it records flows through Ergo's contradiction gate.

Setting no ERGO_API_TOKEN leaves the API open — fine for local dev/test, and the server warns you. Set a token for anything real.

Next steps

• Why Ergo — the case for a judgment layer over a bigger vector store, with the eval numbers.
• Concepts — the mental model: two kinds of memory, supersede vs. retract, provenance, scope.
• The contradiction guard — the four-stage write-time check, in detail.
• Install — Docker build/run, health check, embedding providers, env vars, and the MCP adapter.
• HTTP API — the 10-endpoint reference with request/response shapes.
• MCP tools — the 11 ergo_* tools your agent calls.
• Recipes — wiring the adapter into a coding agent, plus curl walkthroughs.