MCP tools

The Ergo MCP adapter exposes 11 tools, each a 1:1 mapping to an HTTP endpoint. It's a thin stdio HTTP client — it never opens the SQLite file directly. Your agent calls these tools; you don't write glue code.

Registering the adapter

The adapter speaks MCP over stdio, so a host launches it as a subprocess and passes the engine location through environment variables:

ERGO_API_URL=http://127.0.0.1:8788 \
ERGO_API_TOKEN=your-secret-token \
  python -m ergo.mcp.server

Every tool is scoped to an (org_id, project). The adapter's defaults are:

• org_id = "claude-code"
• project = the git-repo basename of the current working directory
• who = "claude-code"

All three are overridable per call. See Recipes for a full .mcp.json registration entry.

Write tools (contradiction-guarded)

ergo_remember

Record a decision, constraint, rejection, or convention. Runs the full contradiction gate (normalize → structural → NLI → judge). Always include a reason — a reason-less claim can never win an ergo_why query.

• statement — the claim, in plain declarative prose (required)
• reason — why it holds (strongly recommended; required in spirit for decisions)
• org_id, project, who — scope/authorship overrides
• force_exception — a justification string to store anyway despite a conflict

A detected contradiction comes back as a structured conflict (the conflicting claim, tier, and reason) — not an error. Resolve it: cancel, ergo_supersede, or retry with force_exception.

ergo_learn

Record a belief formed from a source — the bridge between raw ergo_ingest and a fully-guarded ergo_remember. Runs the same contradiction gate and folds the provenance into the stored reason.

• statement — the belief (required)
• source — where it came from: file:line, doc, URL (required)
• reason, org_id, project, who, force_exception

ergo_supersede

Replace an active claim with a revised one — "I changed my mind, and here's why." The old row becomes superseded and links to the new one, preserving the why-chain. The new claim is contradiction-checked against all other active claims first, so it can still be refused with a conflict.

• existing_id — the claim being replaced (required)
• statement — the revised claim (required)
• reason, org_id, project, who

ergo_retract

Remove a claim that was wrong at birth — a typo, test junk, or a mis-scoped write. Flips it to retracted and drops it from the active set; it stays in ergo_history. No contradiction gate. Removal is audit-loud, so a reason is required.

• claim_id — the claim to retract (required)
• reason — why it's being removed (required)
• org_id, project, who

Read tools

ergo_recall

Hybrid semantic search over active claims — sqlite-vec cosine similarity blended with keyword overlap. Returns score, vec_sim, and kw per result so you can tell a semantic-only match from a keyword hit.

• query — natural-language query (required)
• limit — max results (clamped to [1, 50])
• org_id, project

ergo_why

Like ergo_recall, but reasoned-only and single-answer: returns the best reasoned belief for the query plus its reason and full supersede history. A reason-less claim can never win here. Returns null when nothing reasoned matches.

• query — natural-language query (required)
• org_id, project

ergo_active

List every active claim in a scope.

• org_id, project

ergo_history

Full claim history for a scope — active plus superseded plus retracted, ordered by claim sequence. Use this to walk how beliefs evolved.

• org_id, project

Reference & ops tools

ergo_ingest

Bulk-load reference content (a runbook, README, or design doc) for later recall. Skips the contradiction gate — facts upsert freely — chunks the text word-safely, embeds it, and stores it. Use this for material you want recall-able, not for decisions you want guarded. It's the fast path: much cheaper than a guarded write.

• text — the content to ingest (required)
• source — provenance string appended to each chunk
• org_id, project, who

ergo_diagnose

Report-only ops view of the running engine: live counts, conflict telemetry, version drift, and anti-zombie warnings (missing owner/backup, drift). It never mutates beliefs — any fix still requires an explicit write.

(No parameters.)

ergo_health

Liveness probe (no auth). status: ok with retrieval: true means the whole API — including recall, why, and ingest — is available. Call it once before relying on the store.

(No parameters.)