Concepts

One store, two behaviors

Everything Ergo remembers is a claim — a statement scoped to an (org_id, project). But claims come in two flavors, and the difference is the whole point.

Facts are cheap, high-churn context — paths, versions, who-owns-what. They upsert without ceremony and skip the contradiction gate.

Decisions, constraints, rejections, and conventions are the durable choices you don't want a future session to reverse by accident. They are append-only, they must carry a reason, and the only way to change one is to supersede it — which keeps the old version linked in history.

Why reasons are mandatory

A decision without a reason can't defend itself. When a later session asks "why do we deploy only on green CI?", Ergo's why query returns the best reasoned belief plus its rationale and full supersede history. A reason-less claim can never win that query — so decisions require one at write time.

The contradiction guard

A guarded write (remember, learn, supersede) doesn't just append. It runs the candidate claim through a pipeline before it's allowed to land:

1. Normalize — an LLM normalizer parses the statement into a structured form (subject, stance, scope, and an atomic value where one exists — a color, port, version, hostname, or number).
2. Structural — compares the normalized claim against active claims in the same scope: same subject, same-direction stance, overlapping scope, but a disagreeing atomic value flags a conflict.
3. NLI — natural-language inference checks for entailment/contradiction that the structural pass can't see from values alone.
4. Judge — decides the outcome: a HIGH-confidence contradiction blocks the write; softer signals surface as an advisory warning.

A blocked write returns HTTP 409 (the MCP tools surface this as a structured conflict, not an error). That 409 is the product working — it's Ergo refusing to let the agent quietly contradict itself.

The gate is deliberately selective. It runs on decisions/constraints, where a stale claim is costly. Bulk reference content goes through ingest, which skips the gate entirely (see below).

Resolving a conflict: supersede vs. retract

When you hit a 409 — or when a decision simply changes — you have two distinct tools, and the difference matters:

• supersede — "I changed my mind, and here's why." The decision genuinely changed. Ergo writes a new row, flips the old one to superseded, and links them so the why-chain survives. Use this to preserve history.
• retract — "this was wrong at birth." A typo, test junk, or a mis-scoped write that never should have existed. It flips to retracted (reason required) and leaves the active set, but stays visible in history. Retract runs no contradiction gate — it's pure removal.

Rule of thumb: if the world changed, supersede. If the claim was a mistake, retract.

Provenance

Beliefs formed from a source keep that source attached. learn takes a required source and folds it into the reason, so a later why/recall can tell you not just what is believed and why, but where it came from — a file and line, a doc, a URL. This is the bridge between raw ingested reference (no gate) and a contradiction-checked claim.

Scope

Every read and write is scoped to an (org_id, project) pair. Claims in one scope are never contradiction-checked against another — no cross-contamination between repos or teams. The MCP adapter defaults the scope to org_id="claude-code" and project = the git-repo basename of the working directory, both overridable per call.

One SQLite file

The entire store — claims, reasons, history, and the sqlite-vec embedding index — is a single SQLite file. One file, one embedding space, one backup. That makes Ergo trivially air-gappable and portable: copy the file and you've copied the memory. The embedding dimension is locked at the first write, so pick your embedding provider before you start writing.