Beliefs

In a typical prompt, a peer-reviewed citation, an agent's quick inference, and a guess made three turns ago all look the same. Same font, same weight, same authority. The model has no way to tell them apart, so it interpolates across all of them.

A belief is what makes that distinction structural instead of accidental. It captures what the agent currently holds true: the claim, how confident the agent is, what evidence backs it, and how it has evolved.

Beliefs are the unit of the agent's belief state, its evolving understanding of the environment over time. Together, beliefs track what's been observed, what's currently held true, and what action would move the world model closer to reality.

What a Belief Is

A belief is a structured assertion your agent holds about the world. It has a type, a confidence score, an optional evidence weight, and an optional label for richer categorization.

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  // Engine-tracked alongside this 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 modifying export flow
13}

• text. The natural language assertion.
• type. What kind of belief: claim, assumption, risk, evidence, gap, goal.
• confidence. A 0–1 score reflecting the current evidence balance.
• evidenceWeight. How much evidence backs this belief. 0 means stated but uninvestigated; higher means corroborated.
• label. A semantic label for richer categorization: risky-assumption, load-bearing, limiting-belief, pain-point, opportunity, etc.

The example above is from a coding agent's world model, a repo. The same shape applies to any domain: a research agent's belief about market size, an analyst's belief about a customer's churn risk, a finance agent's belief about a portfolio position. The structure is the same; only the content changes.

Belief Types

The system assigns types automatically during extraction. You can also specify a type when adding beliefs manually via beliefs.add(text, { type: 'assumption' }).

How Confidence Works

Confidence reflects the balance of evidence behind a belief. When new evidence arrives, confidence shifts. How much depends on the evidence quality.

A Gartner report citing $4.2B market size carries more weight than an agent's inference from incomplete data. Both update beliefs, but by different amounts.

Evidence Types

Different evidence types carry different weight:

A single verified measurement shifts confidence more than several inferences. The SDK calibrates the weight of each type so that evidence quality matters, not just volume.

Direction

Every piece of evidence has a direction:

• supports. Increases confidence in the claim.
• refutes. Decreases confidence in the claim.
• neutral. Adds information weight without shifting direction.

When the research agent finds a Gartner report supporting "Market size is $4.2B," confidence increases. When it finds an SEC filing showing a smaller number, that refuting evidence decreases confidence. Both are captured. Nothing is discarded.

Extraction

The SDK extracts beliefs automatically when you pass output to after. You do not need to parse agent outputs yourself.

1// Beliefs are extracted from the output automatically
2const delta = await beliefs.after(result.text)

With an adapter, the lifecycle is wired up for you:

1const agent = createAgent({
2  hooks: beliefsHooks(beliefs, { capture: 'all' }),
3})

Manual Assertion

When you have domain-specific knowledge, you can add beliefs explicitly:

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

Manual assertions and automatic extraction feed the same update pipeline.