Belief state

The belief state answers one question for the agent: what is true here, and how sure am I? The other parts of the world model (the environment, the intent, the action set) frame the decision. The belief state holds the agent's read on reality while it makes that decision.

It is a graph of explicit posteriors over the environment, not an opaque latent vector. The belief is the unit of account: each one records what the agent holds true and why, so a peer-reviewed citation and a guess from three turns ago carry different authority instead of reading as equally settled. Retrieval hands both back the same way; the belief state weighs which one still holds.

The state lives outside the model. It survives the context window, stays inspectable, and lets you read it, write to it, and trace any belief back to the observations that produced it.

What a belief is

A belief carries text, a type, an explicit posterior over its truth, an evidence weight, and an optional label.

1{
2  id: 'belief_auth_middleware',
3  text: 'Authentication is enforced at the API middleware layer',
4  type: 'claim',
5  confidence: 0.82,
6  evidenceWeight: 4,
7  label: 'load-bearing',
8  createdAt: '2026-04-15T10:30:00Z',
9  // Tracked alongside the belief:
10  //   evidence:    middleware.ts, auth.test.ts, architecture.md
11  //   contradicts: /api/internal/export bypasses middleware
12  //   next move:   inspect route-level auth coverage before touching export
13}

• text. The natural-language assertion.
• type. What kind of belief: claim, assumption, risk, evidence, gap, goal.
• confidence. A 0-1 posterior: where the balance of evidence currently sits, a best estimate that moves as evidence arrives rather than a verdict.
• evidenceWeight. How much evidence stands behind the belief. 0 means stated but uninvestigated; higher means corroborated.
• label. A richer category: risky-assumption, load-bearing, limiting-belief, and so on.

The engine assigns the type and label during extraction. You can also set them by hand via add(). The example comes from a coding agent's world model, a repo, but the shape is fixed across domains: a research agent's read on market size, an analyst's call on churn, a finance agent's position on a book. Only the content changes.

Belief types

goal and gap share this store for convenience, but they are firewalled from the posterior math: neither carries a probability, and setting out to prove a goal is not evidence for it. They are intent, and they live on a separate track.

Two channels, not one number

A belief carries two readings, and they answer different questions:

• confidence is where the balance of evidence currently sits, on a 0-1 scale.
• evidence weight is how much evidence stands behind that reading.

A claim at 50 percent with no evidence and a claim at 50 percent with forty split observations are different situations. The first is an open question nobody has touched. The second is a genuine standoff where the evidence is real and contested. A single number collapses both into one ambiguous middle. Two channels keep them apart, so the agent can chase the first and adjudicate the second.

How confidence moves

How far confidence moves on a new observation depends on the quality of that observation. A verified measurement moves the posterior more than several inferences. Corroboration is a likelihood, not a vote: ten paraphrases of one source do not count as ten sources.

The direction of each piece of evidence sets which way the posterior goes:

• supports raises the posterior.
• refutes lowers it.
• neutral adds weight without shifting the estimate.

When a research agent finds a Gartner report backing "Market size is $4.2B," the posterior goes up. An SEC filing with a smaller number pushes it back down. Both are kept. The disagreement is not averaged away; it surfaces as a contradiction (wider uncertainty, flagged explicitly) rather than papered over.

Evidence quality

Different evidence types carry different weight, so quality counts for more than repetition:

Edges, gaps, and contradictions

Beliefs relate to each other, and those relations are the graph.

Edges are themselves claims with their own posteriors, so the graph carries uncertainty about its own structure: a depends_on link can be strong or tentative, and the confidence on it says which.

Gaps are known unknowns the agent has flagged: the open questions, weighted by stake against uncertainty. Contradictions are where the state disagrees with itself or with new evidence. Rather than collapsing to whichever side an agent happened to read last, a contradiction widens uncertainty and is surfaced as a first-class object the agent can act on.

Staleness

Old evidence weighs less than new under an explicit decay schedule: a half-life. An observation's contribution drops to half its weight after one half-life, so a stale fact and a fresh one do not read identically. When support has decayed past the floor, the belief is flagged stale rather than silently trusted. Freshness carries into the reading itself, so the agent knows when a claim is coasting on aging evidence.

Provenance

Provenance is first class. Every belief traces back to the observations that produced it, so why do we believe this, who said it, when, and how sure were they is answerable.

1const chain = await beliefs.trace('belief_auth_middleware')

trace(id) walks that chain: the evidence behind the belief, the sources, and how confidence moved over time. get(id) returns a single belief by id, and list() returns the active set. The full read shape (beliefs, edges, gaps, contradictions, and ranked moves) comes back from read(); see the world model.

Seeding a belief by hand

When you already hold domain knowledge, assert it directly:

1await beliefs.add('Market size is $4.2B', {
2  confidence: 0.85,
3  type: 'assumption',
4})

The confidence you pass is a weak prior. It seeds the posterior, and the first corroborating or refuting evidence starts moving it from there. Manual assertions feed the same fusion pipeline as extracted ones, so a hand-entered claim and one the engine lifted from an artifact reconcile under the same rules. Most beliefs arrive automatically: pass an artifact to observe() or an agent's output to after(), and the engine extracts and folds them in for you.