---
title: Beliefs
description: "The unit of account inside a world model: text, type, confidence, evidence, lifecycle."
---

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.

```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',
  // Engine-tracked alongside this belief:
  //   evidence:    middleware.ts, auth.test.ts, architecture.md
  //   contradicts: /api/internal/export bypasses middleware
  //   next move:   inspect route-level auth coverage before modifying export flow
}
```

- **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

| Type | One-line gloss | Use case |
|------|----------------|----------|
| `claim` | An evidenced assertion | Supported or refuted by collected evidence |
| `assumption` | An untested supposition | Stated as true without direct evidence yet |
| `risk` | A potential negative outcome | Something the agent should hedge against |
| `evidence` | A data point or source | Used to support/refute other beliefs |
| `gap` | A known unknown | Something the agent has flagged as unresolved |
| `goal` | A pursued outcome | What the agent is trying to accomplish |

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:

| Type | Description |
|------|-------------|
| `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 inference from available data |
| `assumption` | Explicit assumption, no supporting evidence |

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.

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

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

```ts
const agent = createAgent({
  hooks: beliefsHooks(beliefs, { capture: 'all' }),
})
```

## Manual Assertion

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

```ts
await beliefs.add('Market size is $4.2B', {
  confidence: 0.85,
  type: 'assumption',
})
```

Manual assertions and automatic extraction feed the same update pipeline.

<CardGroup cols={2}>
  <DocsCard title="Intent" description="Goals, gaps, and the normative layer." href="/dev/core/intent" />
  <DocsCard title="Core API" description="The full SDK API surface." href="/dev/sdk/core-api" />
</CardGroup>