Recipes

These recipes assume the engine is already running on host 8788 (see Install). Examples use synthetic data — swap in your own scope.

1. Wire the MCP adapter into a coding agent

The adapter is a stdio MCP server, so a host launches it as a subprocess and passes the engine location via env. Most MCP hosts (Claude Code, and other .mcp.json-style configs) use this shape:

{
  "mcpServers": {
    "ergo": {
      "command": "python",
      "args": ["-m", "ergo.mcp.server"],
      "env": {
        "ERGO_API_URL": "http://127.0.0.1:8788",
        "ERGO_API_TOKEN": "your-secret-token"
      }
    }
  }
}

Once registered, the 11 ergo_* tools appear to the agent. By default they scope to org_id="claude-code" and project = the git-repo basename of the working directory, so a per-repo memory just works — override org_id/project per call if you want a shared or custom scope.

A light operating instruction in your agent's AGENTS.md (or CLAUDE.md) is enough to make the agent use it well:

## Memory (Ergo)

- BEFORE reversing a settled choice, call `ergo_recall` or `ergo_why` first;
  if a decision exists, surface its statement + reason before overriding.
- AFTER a real decision with a reason, call `ergo_remember` with a clear
  statement + reason. A conflict flag is the guard working — inspect it and
  `ergo_supersede` the old claim rather than forcing the write.
- For a belief formed from a source you just read, use `ergo_learn` with
  statement + source.

2. Remember a decision, then recall and explain it (curl)

Every guarded endpoint takes a Bearer token; /health doesn't. Set the header once:

TOK="Authorization: Bearer your-secret-token"

Remember a decision (kind: decision → append-only, reason required, runs the contradiction gate):

curl -s -H "$TOK" -X POST http://127.0.0.1:8788/remember \
  -d '{"org_id":"acme","project":"kb","kind":"decision","statement":"Deploy only on green CI","reason":"A red build in prod cost us an outage in Q2"}'

Recall it later with hybrid semantic + keyword search over active claims:

curl -s -H "$TOK" "http://127.0.0.1:8788/recall?org_id=acme&project=kb&q=when%20to%20deploy&limit=3"

Ask why to get the best reasoned belief plus its rationale and supersede history:

curl -s -H "$TOK" "http://127.0.0.1:8788/why?org_id=acme&project=kb&q=when%20to%20deploy"

If you later try to record a directly contradicting decision in the same scope, the guarded write returns HTTP 409 with the conflicting claim — that's the signal to POST /supersede the old claim (which preserves the why-chain) rather than store a silent contradiction.

3. Bulk-load facts via /ingest

When you have reference material you want to be recall-able — a runbook, README, or design doc — use /ingest. It skips the contradiction gate (facts upsert freely), chunks the text, embeds it, and stores it. It's the fast path for bulk content:

curl -s -H "$TOK" -X POST http://127.0.0.1:8788/ingest \
  -d '{"org_id":"acme","project":"kb","source":"runbook.md","text":"The staging environment redeploys nightly at 02:00 UTC. Rollbacks are performed with the deploy script using the previous image tag."}'

Ingested chunks show up in recall alongside claims. Because they bypass the gate, they are neither contradiction-checked nor checked against — a later remember will not collide with them. Reserve remember/learn for the decisions and constraints you actually want guarded.