Beliefs

A belief is something held true about the project — a convention, a constraint, a "this is how we do it." Beliefs are first-class in Mneva because they revise differently from memories.

Belief vs memory

A memory is something that happened. We wrote the rate limiter on Tuesday is a memory. It is forever true that we wrote it on Tuesday; the memory does not become wrong, it just gets dated.

A belief is something currently held to be the case. Our rate limiter is sized for 100 req/min is a belief. It can become wrong — we might raise the limit. When that happens, the belief must be revised, and a recall against the topic should never resurface the old wording.

Mneva treats this structurally:

beliefs (
  id              INTEGER PRIMARY KEY,
  project         TEXT,
  text            TEXT,
  confidence      REAL DEFAULT 0.7,
  embedding       BLOB,
  superseded_by   INTEGER REFERENCES beliefs(id),  -- null = current
  sprt_log_ratio  REAL DEFAULT 0,
  evidence_count  INTEGER DEFAULT 0,
  sprt_status     TEXT DEFAULT 'accumulating',
  ...
)

The superseded_by column is the trick. When you revise a belief, the new row is inserted and the old row's superseded_by is set to the new id. The old row is not deleted. currentBeliefs() returns only rows where superseded_by IS NULL. Recalls cannot reach the superseded belief; history can.

A corrected belief stays corrected.

Confidence

Every belief has a confidence on [0.05, 0.95]. By default a freshly asserted belief gets 0.7. The score is editable two ways:

  • Manually — pass confidence to believe or revise.
  • Earned — every evidence call shifts the SPRT log ratio, and when it crosses a threshold the belief's confidence shifts by +0.10 (promote) or −0.20 (demote).

The asymmetric −0.20 vs +0.10 is intentional. Refutation should move faster than support; an unmoved-by-evidence belief is the failure mode we are trying to avoid.

Revision (manual)

revise(belief_id=12, new_text="our rate limiter is now 250 req/min after the LB upgrade", confidence=0.9)

Done. Belief #12 is superseded; the new row is current.

This is the right call when you know the belief is wrong and have the new wording — for instance, when you just shipped the change. Don't make Mneva infer what you can state.

Revision (earned)

For beliefs where evidence accumulates over time, use evidence. Each call records one supporting or refuting observation with a strength on [0.1, 0.9]. When the accumulated log-likelihood ratio crosses the demote threshold, sprt_status flips to demoted and confidence drops to 0.5 (from 0.7). That's the signal the belief is in trouble — and the agent can decide whether to call revise() with the new wording.

Mneva deliberately does not auto-supersede on demote. Structural revision is an explicit act; invisible auto-supersession would surprise the customer and corrupt the audit trail. See Evidence (SPRT) for the math.

See also

Was this page helpful?