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 runs as a hosted MCP server — no install, no container to run. Connect your agent in one line:

claude mcp add --transport http ergo https://api.ergomem.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

That's Claude Code; Codex CLI and Cursor are just as short. See Quickstart for all three, plus what to say to your agent once it's connected.

Prefer to self-host? Ergo also ships as a self-contained Docker image (SQLite + sqlite-vec, the embedder and NLI model baked in) — see Install.

Next steps

• Quickstart — connect Claude Code, Codex, or Cursor to the hosted endpoint and start recording decisions.
• 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.
• MCP tools — the 11 ergo_* tools your agent calls.
• Recipes — more end-to-end walkthroughs, including raw curl.
• Install — self-hosting: Docker build/run, health check, embedding providers, env vars, and the stdio MCP adapter.
• HTTP API — the raw HTTP reference, advanced/self-host oriented.
• Multi-tenancy — silo isolation, per-principal tokens, and the /admin/* provisioning API for running Ergo as a team server.