Myzona

Ergo Remember

Record a contradiction-guarded decision/constraint/convention. Always include a `reason` — reason-less claims can never win an ergo_why query. Be specific, no pronouns, one claim per call. If the engine detects a contradiction it returns a structured conflict (result="conflict", with the conflicting claim, tier, and reason) instead of storing — resolve it (cancel, ergo_supersede the old id, or retry with `force_exception`). Set `force_exception` to a justification string

Ergo Learn

Record a belief learned FROM a source, contradiction-guarded with provenance. The bridge between ergo_ingest (raw reference chunks, no gate) and ergo_remember (decisions, full gate): use this when you read something and formed a belief — e.g. `statement="sessions are never reused across gateway restarts", source="sessions.py:847"`. Runs the SAME contradiction pipeline as ergo_remember, and folds `source` into the stored reason so the provenance is retrievable via ergo_wh

Ergo Ingest

Bulk-ingest reference content (runbook/README/design doc). Skips the LLM normalizer + contradiction gate ("facts upsert freely"), chunks word-safely, embeds, and stores for later recall. Use this for documents you want recall-able — NOT for decisions you want contradiction-checked (use ergo_remember for those). `source` is a provenance string appended to each chunk as `[source: ...]`.

Ergo Supersede

Replace an existing active claim with a revised one ("I changed my mind"). Get `existing_id` from ergo_recall / ergo_why / ergo_active. The new claim is contradiction-checked against all OTHER active claims first; if it would itself conflict, the supersede is refused with a structured conflict set. The old row becomes status='superseded' and the new one links back to it — this is what ergo_why walks for history.

Ergo Retract

Retract a wrong-at-birth claim — remove it from the active belief set. Retract vs supersede: use ergo_retract when the claim should NEVER have been stored (typo, test junk, mis-scoped write); use ergo_supersede when a decision genuinely CHANGED (that keeps the why-chain). `reason` is required — removal is audit-loud. Get `claim_id` from ergo_recall / ergo_active / ergo_history. The claim vanishes from ergo_active / ergo_recall / ergo_why and is no longer contradiction-ch

Ergo Recall

Hybrid semantic search over active claims in a scope. Returns results scored `0.7*vec_sim + 0.3*keyword_overlap`. Read `score`, `vec_sim`, and `kw` independently — a high `vec_sim` with `kw=0` is a semantic-only match; verify before treating it as authoritative. `limit` is clamped to [1, 50] by the engine.

Ergo Why

Best REASONED belief for a query, plus its supersede history. Like ergo_recall but reasoned-only (a reason-less fact can never win), returns the single top hit and walks the supersede chain. Always includes `score` when a claim is returned, so you can judge confidence yourself. Returns `{"why": null}` in TWO distinct cases — check for `suppressed` to tell them apart: - No reasoned claim exists in scope at all (no `suppressed` key). - A claim exists but scored below

Ergo Active

Enumerate active claims in a scope, capped by default (issue #185). Returns `{"state": "project_missing"|"empty"|"has_active_claims", "count": <total in scope>, "returned": <this page>, "truncated": bool, "truncated_reason": "row_limit"|"byte_budget"|null, "next_offset": <int or null>, "claims": [...]}`. `state` describes the SCOPE, not the page -- claims beyond your `offset` still read `has_active_claims`, never `empty`. If `truncated` is true, call again with `offset=n

Ergo History

Full claim history for a scope — active + superseded + retracted. Ordered by claim_seq ascending. Use ergo_active for just the live set.

Ergo Audit

Tenant-facing audit trail: this scope's own `writes` + `conflict_events` rows (issue #124). Self-serve read for a compliance/security need — the caller only ever sees its OWN org's rows (the engine's `forced_org` always wins over any org_id passed here, same isolation guarantee as ergo_active/ergo_history). Returns `{"writes": [...], "conflict_events": [...]}`, each ordered oldest -> newest. `limit` caps EACH stream independently (not their sum); omitted, the engine

Ergo Diagnose

Ops view of the running engine: counts, conflict telemetry, warnings. Report-only — it never mutates beliefs. `warnings[]` is the anti-zombie field (missing owner/backup, version drift). Any fix still requires an explicit ergo_supersede.

Ergo Health

Liveness probe (no auth). Call once before relying on Ergo. `status: ok` with `retrieval: true` means the whole API (incl. recall/why/ ingest) is available.

Ergo Export

Export the scope's active claims as a portable document (no vectors). Open to every plan (issue #109) — data portability is never gated, and reads never consume the monthly guarded-write allowance. `ergo_import` stays Pro/Team-gated; a free plan calling that one gets back a structured `{"result": "error", "status_code": 403, ...}` with `error.error == "import_requires_pro_or_team"`, not an exception. Returns `{ergo_export_version, org_id, exported_at, embedder:{provider,

Ergo Import

Contradiction-checked MERGE of claims (e.g. from ergo_export) into a scope. `claims` is the `claims` array from an ergo_export result (or any list of claim-shaped dicts). Each incoming claim runs through the SAME guarded write path ergo_remember/ergo_learn use — never force-written: an exact-text duplicate is skipped (`skipped_duplicate`), a blocking contradiction is reported in `conflicts[]` (the "import audit") and left unstored, everything else is stored. A claim's `r

Ergo Import Status

Poll a background import job's progress/result (issue #122). `job_id` comes from ergo_import's `202` response. Tenant-scoped read — a caller can only ever see its OWN jobs (same isolation guarantee as ergo_active/ergo_audit; a job belonging to a different tenant, or an unknown job_id, both come back as the SAME structured 404, never distinguished). `status` is one of `"pending"` (queued, not yet claimed by the drain), `"running"` (claimed, actively merging), `"succeeded"