feat(memory): belief layer for atomic-fact conflict resolution

[dereksgithub]

Summary

Closes the gap described in #382: atomic facts have no arbitration. When two facts contradict each other, both are stored, both are indexed, both match the same query, and BM25 score plus embedding distance decides which one reaches the model — neither of which knows which one is true. deprecated_by is a Reflection consolidation marker rather than a contradiction verdict, and nothing else in the write path notices the disagreement.

Adds everos.memory.belief, a domain-layer module where mutually exclusive facts share a belief_key and hold a categorical distribution, updated by a Bayesian rule whose evidential weight is capped by the provenance of the channel each fact arrived on. Pure functions plus a resolver and a keyer — no I/O, no LLM, no new dependencies.

Two properties, each pinned by tests:

• a channel at or below reliability 0.5 cannot change what the memory asserts, at any volume, including via a candidate the belief has never seen. Admission is gated by the same pivot the likelihood ratio uses; without that the guarantee is vacuous, since an attacker just asserts something novel and is admitted before any reliability test runs;
• a single trusted correction can still supersede a single trusted claim — the property a fixed entry mass silently makes impossible.

Those two are the same knob, and #382 has the table showing that no single setting of it satisfies both.

Nothing is wired into persistence, search, or the cascade. This is the domain rule and its measurements, deliberately standalone so the direction can be judged before anything invasive is built on it.

Area

• Architecture method
• Benchmark
• Use case
• Documentation
• Developer experience
• CI, build, or release

Verification

Two offline benchmarks are included. Both isolate the update rule — gold evidence spans go straight into the resolver, so no extractor, retriever or LLM sits between the input and the number. No server, no providers, no API key, a couple of seconds each.

Supersession on LongMemEval knowledge-update (70 instances with gold spans in both sessions). clean is a pure recency test where last-write-wins is optimal by construction, so it shows no-regression rather than a win. The poisoning arms are constructed overlays on the benchmark's own text and are labelled as such in the output.

arm	last-write-wins	belief
clean	100.0%	78.6%
poison-5 — stale claim replayed on web_fetch	0.0%	78.6%
novel-5 — unseen claim asserted on web_fetch	0.0%	78.6%
lowtrust-fix — true update arrives on web_fetch	100.0%	0.0%

The identical figure across the three arms is the result: the attacks have zero effect, not reduced effect. lowtrust-fix = 0.0% is the honest cost and it is symmetric by construction — a ceiling that stops a bad correction on a low-trust channel stops a good one identically.

Belief-key derivation, labels taken from KU pair membership. The two columns are not symmetric: a missed link leaves a contradiction unarbitrated, which is today's behaviour, while a false link lets an unrelated fact suppress a true one. The default sits on the precision side of the curve, not the F1 peak.

threshold	true pairs linked	unrelated pairs linked
0.20	85.7%	1.60%
0.25 (default)	81.4%	0.45%
0.30	68.6%	0.12%

Re-running supersession with derived keys — nothing telling the resolver what competes, and scoring an instance correct only when the memory asserts the update and has stopped asserting the stale claim — gives 78.6% clean and 78.6% under poison-5.

make lint          ruff + import-linter + deprecated-name + datetime + openapi checks — clean
make test          1908 passed
make integration   180 passed, 7 deselected

uv run python benchmarks/belief_ku.py  --data data/longmemeval_oracle.json
uv run python benchmarks/belief_key.py --data data/longmemeval_oracle.json

Checklist

• I kept the change scoped to the relevant area.
• I am opening this from a separate branch, not pushing directly to main.
• I updated docs, examples, or setup notes when behavior changed.
• I added or updated tests when the change affects behavior.
• I did not commit secrets, .env files, dependency folders, or generated output.
• Active relative links in Markdown files resolve.

Notes for Reviewers

The belief_key question is where a maintainer's call changes the design most, and it is the one thing I would not merge without your opinion. An atomic fact is an undecomposed sentence, so nothing groups mutually exclusive candidates today. BeliefKeyer groups lexically — value-bearing tokens dropped, topic terms kept, IDF-weighted — and that is a stand-in, not a proposal. EverOS already embeds every fact; matching on those embeddings is the better implementation, and the class takes its similarity as a constructor argument so the swap is not a rewrite. The lexical version exists to establish the problem is tractable before anyone spends embedding calls on it. If the algo layer could emit an optional subject / attribute alongside the fact, that would be better than either.

This has never run against real everalgo extraction. Every number here feeds benchmark sentences in as stand-ins for atomic facts. That isolation is deliberate — it is what makes a result attributable to the update rule — but the extraction seam is untested, and the benchmark's content-confidence rubric is a crude regex placeholder for what the algo layer would emit.

Deliberately left out, since each depends on the answer to the above: persistence (BeliefState / BeliefRevision are derived state and belong in SQLite, not the LanceDB fact table — no index migration, and states rebuild from the revision log); search integration (rank or filter by posterior, surface probability on the recall DTO); tier assignment (mapping owner_type / app_id / sender_ids onto tiers should be operator config in everos.toml, never inferred, and never from anything an agent can write).

On the probabilities themselves: the layer reports them, but whether they are calibrated is an empirical question needing outcomes to score against (Brier / ECE over resolved beliefs). Until that is measured, entropy is the honest thing to show a caller and probability should be read as a ranking rather than a frequency. The docstrings say so; I would rather that be explicit than have a number leak into a UI implying more than it has earned.

Happy to split this, rescope it, or close it if the direction isn't wanted.

By submitting this pull request, I agree that my contribution is licensed under
the Apache License 2.0.