Start Here

An agent's world model has two layers. The environment is what the agent operates on: a codebase, a market, a customer, a patient. The belief state is its evolving understanding of that environment: what's been observed (past), what's currently held true (present), and what action would move closer to reality (future).

Beliefs are how you build the belief state. Claims with confidence, evidence, and lifecycle. The unit that keeps the world model accurate as reality changes.

1npm i beliefs

1import Beliefs from 'beliefs'
2
3const beliefs = new Beliefs({
4  apiKey: process.env.BELIEFS_KEY,
5  namespace: 'my-project',
6  writeScope: 'space',
7})
8
9// Before the agent acts: read current understanding
10const context = await beliefs.before(userMessage)
11
12// Run your agent with belief context injected
13const result = await myAgent.run({ system: context.prompt })
14
15// Feed the output: beliefs extracted, conflicts detected, state updated
16const delta = await beliefs.after(result.text)

That's the loop. Three calls per turn, regardless of which framework you ship on.

Works with your stack

1import { beliefsHooks } from 'beliefs/claude-agent-sdk'   // Anthropic Claude Agent SDK
2import { beliefsMiddleware } from 'beliefs/vercel-ai'     // Vercel AI SDK
3// React hooks + browser DevTools (coming soon)

Or call beliefs.before() / beliefs.after() manually around any LLM (OpenAI, plain fetch, your own agent loop). See the Hack Guide for working recipes across frameworks.

I want to...

Why coding agents first

A codebase is already a compact world. It has laws (types, invariants), assumptions (architecture decisions, dependencies), history (commits, PRs), ownership, and contradictions (stale docs, drifted assumptions). Coding agents are already operating inside this world, but with short-lived context and weak memory.

The first world model thinkⁿ targets is the one your coding agent already lives in. Concrete beliefs the engine can hold for a repo:

1belief:    Authentication is enforced at the API middleware layer
2confidence: 0.82
3evidence:   middleware.ts, auth.test.ts, architecture.md
4contradicts: /api/internal/export bypasses middleware
5next move:  inspect route-level auth coverage before modifying export flow

The same machinery applies to research agents (claims about a market), analyst agents (beliefs about a customer or portfolio), or any system that needs to maintain a coherent picture of reality across many turns and many sources.