---
title: Why beliefs
description: "Why agents drift, why memory and RAG don't fix it, and what beliefs change."
---
## A bug you've already debugged
Your agent looks up a market size on turn 3 and says "$4.2B." On turn 12 a tool returns SEC filings showing "$3.8B." On turn 18 the agent cites "$4.2B" again — because that's what it said first, and the context window doesn't distinguish "stated earlier" from "verified."
You've seen this. It looks like flakiness, or hallucination, or model error. It's none of those. **It's the absence of a primitive your agent doesn't have: a structured model of what it currently believes, and how that belief changed when new evidence arrived.**
```
Turn 3 ─▶ "Market is $4.2B" ⟵ stated. no source.
Turn 12 ─▶ "SEC filings suggest $3.8B" ⟵ different number. no comparison.
Turn 18 ─▶ "Market is $4.2B" ⟵ first one wins. drift wins.
```
There's no tracked confidence. No evidence weight. No detection that the numbers disagree. No awareness that one came from a tool and the other from a guess. A peer-reviewed study and a guess three turns ago look identical to the model.
With beliefs, the same trace becomes:
```ts
// Turn 3
await beliefs.add('Market is $4.2B', { confidence: 0.5 }) // stated, no evidence
// Turn 12
await beliefs.after(secFilings)
// engine extracts "$3.8B", detects contradicts edge to "$4.2B"
// world.contradictions surfaces both with sources
// Turn 18
const context = await beliefs.before(userMessage)
// context.prompt surfaces both numbers, their sources, the conflict
// the agent now knows the question is unsettled
```
The agent stops self-contradicting because the infrastructure remembers what it has and hasn't investigated.
## The five symptoms
These are what drift looks like in practice — what you've seen if you've shipped agents that run more than a few turns:
1. **Agents contradict themselves.** Turn 3 cites $4.2B, turn 18 cites $4.2B again because it appeared first. No detection, no resolution.
2. **Confidence is invisible.** A claim from one source and a claim from ten look identical in the context window. A three-month-old estimate sits next to yesterday's verified data with no distinction.
3. **Guesses and facts are indistinguishable.** A user's intuition and a peer-reviewed study carry equal weight in the prompt. There's no separation between assumption and evidence.
4. **Agents don't know what they don't know.** No concept of "gap." No mechanism to prioritize what would reduce the most uncertainty.
5. **Bigger context makes it worse.** A 200K window doesn't fix any of this — it carries more conflicting claims with more fluency, and the model interpolates fluently across all of it. Wider window, murkier understanding.
## Memory and RAG don't fix it
Memory and retrieval each solve a piece of the problem (recall what was said, find similar text), but neither models what's *currently* believed. Here's what the gap looks like in practice:
| Dimension | Memory / RAG | Beliefs |
|-----------|-------------|---------|
| **What it stores** | Text chunks and vectors (similarity-based retrieval) | Structured claims with confidence and evidence |
| **Uncertainty** | None — every retrieved chunk looks equally valid | Two channels: decision resolution + knowledge certainty |
| **Conflicts** | Returns both conflicting chunks, or last-write-wins | Detects, tracks, and resolves by source reliability |
| **Decay** | Falls out of context window randomly | Principled decay toward an uninformative prior over time |
| **Provenance** | "This chunk was retrieved" | Full trail: who stated it, what evidence, how confidence evolved |
| **What is missing** | No concept | Gaps are first-class — they drive the next action |
A three-month-old market estimate and a verified data point from yesterday look identical in memory. Beliefs distinguishes them by confidence, evidence, and recency.
Memory says "this was mentioned before." Belief state says "this is probably true, but confidence dropped after the latest filing — here's the contradiction, here's the next move." That's the difference between *recall* and *judgment*.
## What changes when beliefs are explicit
A worked example. Three agents audit a legacy auth module — a code analyst reads the files, an architecture agent maps service dependencies, a runtime profiler watches actual traffic. They share a `namespace` with `writeScope: 'space'`, so every observation lands in one fused belief state.
```ts
// Code analyst
await analyst.after(
'Auth module has 3 token validation paths. Path A uses JWT. ' +
'Path B uses custom HMAC. Path C checks a session cookie ' +
'but never validates expiry. 14 services import this module.'
)
// Architecture agent
await architect.after(
'Only 6 of 14 services use JWT. 5 use HMAC. ' +
'3 services use Path C — all customer-facing payment APIs.'
)
// Runtime profiler
await profiler.after(
'Path C handles 73% of all auth requests. It was a "temporary bypass" ' +
'added during a migration 2 years ago. The migration completed ' +
'but the bypass was never removed. 4.2M active sessions use this path.'
)
```
The fused world state reveals what no single agent could have seen alone:
```ts
const world = await analyst.read()
world.beliefs
// [
// { text: 'Path C handles 73% of auth traffic', confidence: 0.92 },
// { text: 'JWT is the primary auth mechanism', confidence: 0.15 },
// { text: 'Path C has no session expiry validation', confidence: 0.85 },
// ]
world.edges
// [{ type: 'contradicts', source: 'JWT is primary', target: 'Path C handles 73%' }]
world.moves
// [{ action: 'research',
// target: 'Audit Path C session security',
// reason: 'Payment-facing path with no expiry on 4.2M sessions',
// value: 0.96 }]
```
The team's stated belief was "JWT is our auth." The agents' fused observation was "73% of traffic runs on a forgotten bypass." That contradiction is invisible in any single agent's report. It's the belief state that makes it visible.
## What this unlocks
When beliefs are explicit, the world model stops being read-only:
- **Hidden assumptions become examinable.** Beliefs that were silently driving decisions get named, scored, and traceable.
- **Uncertainty becomes directional.** The system knows which gap, if filled, would reduce the most uncertainty — and surfaces it as a recommended next move.
- **Contradictions become signal, not noise.** A swarm of agents producing partially-overlapping views isn't a coordination failure; it's the input to a fusion engine that resolves through evidence.
- **The frontier becomes visible.** What was never investigated is just as trackable as what was.
This is what beliefs change. The rest of these docs show you how.
## Where to next