---
title: World Model
description: "The agent's current understanding of reality: beliefs, gaps, conflicts, and recommended next steps."
---

## What a World Model Is

A world model has two layers.

The **environment** is what the agent operates on: a codebase, a market, a customer, a patient. The ground.

The **belief state** is the agent's evolving understanding of that environment. It spans three tenses:

- **Past:** what's been observed, what evidence has arrived (the ledger).
- **Present:** what's currently held true, with confidence and provenance (the active claim set).
- **Future:** what action would move the world model closer to reality (the next moves, ranked).

Beliefs are the unit of the belief state. Edges are how beliefs relate. Gaps are open questions. Contradictions are where the belief state disagrees with itself or with new evidence. Moves rank what action would close those gaps fastest.

For the full loop (observe, hold, inject, act), see [Architecture](/dev/internals/architecture).

`beliefs.read()` returns this world model in full: the agent's beliefs, the relationships between them (what supports, contradicts, derives), all open gaps, active contradictions, the clarity score, and recommended next moves.

```ts
const world = await beliefs.read()

world.beliefs        // all beliefs the agent holds
world.goals          // what the agent is pursuing
world.gaps           // unknowns and open questions
world.edges          // relationships: supports, contradicts, derives
world.contradictions // active conflicts that need resolution
world.clarity        // 0-1 readiness score
world.moves          // suggested next actions
world.prompt         // serialized context for LLM injection
```

## Edges

Beliefs form a coherence graph. Each edge represents a relationship between two beliefs.

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

```ts
{
  type: 'contradicts',
  source: 'belief_gartner_tam',
  target: 'belief_sec_tam',
  confidence: 0.9,
}
```

Edges are detected automatically during extraction. When the research agent finds a Gartner report citing $4.2B and an SEC filing showing $3.8B, the system creates a `contradicts` edge between them.

## Contradictions

Contradictions are surfaced explicitly in `world.contradictions`. They penalize the [clarity](/dev/core/clarity) score and generate `clarify` [moves](/dev/core/moves).

A contradiction between two load-bearing beliefs has more impact on clarity than one between peripheral claims. The system weights contradictions by how many downstream beliefs depend on the conflicting pair.

## The Prompt Field

`world.prompt` is a serialized summary of the current belief state, formatted for LLM injection. It includes the most relevant beliefs, open gaps, contradictions, and recommended moves.

```ts
const context = await beliefs.before(userMessage)

const result = await myAgent.run({
  systemPrompt: context.prompt,
  message: userMessage,
})
```

The prompt is constructed to give the agent awareness of its current understanding without overwhelming the context window.

## Multi-Agent Fusion

When multiple agents contribute beliefs, the world model is the fused view: a single picture of reality assembled from every agent's contributions.

Each agent contributes via its own `agent` identifier. The backend merges contributions across agents into one shared state.

<Callout type="info">
To share one fused world model, every contributing agent must use the same `namespace` (the logical problem space) and `writeScope: 'space'` (so writes land in the shared store rather than per-agent or per-thread). With different namespaces or scopes, each agent maintains a separate world model and cross-agent contradictions won't be detected. See [Scopes](/dev/sdk/scoping) for the full breakdown.
</Callout>

```ts
const researcher = new Beliefs({
  apiKey: process.env.BELIEFS_KEY,
  agent: 'researcher',
  namespace: 'market-map',
  writeScope: 'space',
})

const analyst = new Beliefs({
  apiKey: process.env.BELIEFS_KEY,
  agent: 'analyst',
  namespace: 'market-map',
  writeScope: 'space',
})

// Both contribute to the same namespace
await researcher.after(researchResult)
await analyst.after(analysisResult)

// The world model includes beliefs from both, fused by the backend
const world = await analyst.read()
```

If you have a single agent, the world model is your agent's belief state. Multi-agent fusion activates when different `agent` values write to the same namespace with a shared space scope.

<Callout type="info">
Trust weight configuration and conflict resolution strategy selection are handled by the hosted backend. Per-agent views and advanced fusion controls are planned for a future SDK release.
</Callout>

<CardGroup cols={2}>
  <DocsCard title="Core API" description="The full SDK API surface." href="/dev/sdk/core-api" />
  <DocsCard title="Patterns" description="Multi-agent patterns and other common patterns." href="/dev/sdk/patterns" />
</CardGroup>