--- title: Belief state description: "The graph of explicit posteriors over the environment: the belief as the unit, with confidence, evidence weight, edges, and lifecycle." --- 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](/dev/core/environment), the [intent](/dev/core/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. ```ts { id: 'belief_auth_middleware', text: 'Authentication is enforced at the API middleware layer', type: 'claim', confidence: 0.82, evidenceWeight: 4, label: 'load-bearing', createdAt: '2026-04-15T10:30:00Z', // Tracked alongside the belief: // evidence: middleware.ts, auth.test.ts, architecture.md // contradicts: /api/internal/export bypasses middleware // next move: inspect route-level auth coverage before touching export } ``` - **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 | Type | Gloss | Use | |------|-------|-----| | `claim` | An evidenced assertion | Supported or refuted by collected evidence | | `assumption` | An untested supposition | Held true without direct evidence yet | | `risk` | A potential negative outcome | Something to hedge against | | `evidence` | A data point or source | Backs or refutes other beliefs | | `gap` | A known unknown | Flagged as unresolved | | `goal` | A pursued outcome | What the agent is trying to accomplish | `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](/dev/core/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: | Type | What it is | |------|------------| | `measurement` | Audited metric, verified data point | | `citation` | Research report, external source with provenance | | `user-assertion` | User explicitly stated this | | `expert-judgment` | Expert opinion with rationale | | `inference` | Agent-derived from available data | | `assumption` | Explicit assumption, no supporting evidence | ## Edges, gaps, and contradictions Beliefs relate to each other, and those relations are the graph. | Edge type | Meaning | |-----------|---------| | `supports` | Evidence or reasoning that backs a claim | | `contradicts` | Direct conflict between two beliefs | | `supersedes` | A newer belief replaces an older one | | `derived_from` | One belief was inferred from another | | `depends_on` | A conclusion that rests on an assumption | 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. ```ts const 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](/dev/core/world). ## Seeding a belief by hand When you already hold domain knowledge, assert it directly: ```ts await beliefs.add('Market size is $4.2B', { confidence: 0.85, type: 'assumption', }) ``` 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()`](/dev/core/observations) or an agent's output to `after()`, and the engine extracts and folds them in for you.