The hosted API is in private beta. Request access to get an API key.
The Loop
Every agent using beliefs follows the same cycle:
Create a belief state
1import Beliefs from 'beliefs'
2
3const beliefs = new Beliefs({
4 apiKey: process.env.BELIEFS_KEY,
5 namespace: 'quickstart',
6 writeScope: 'space',
7})Before work: read what the agent believes
1const context = await beliefs.before(userMessage)context.prompt is a serialized belief brief. Drop it straight into your agent's system prompt. context.clarity is a 0–1 score: how much does the agent know vs. how much is still uncertain? context.moves are ranked next actions.
After work: feed the observation
1const result = await myAgent.run({ context: context.prompt })
2const delta = await beliefs.after(result.text)The infrastructure extracts beliefs from the output, detects conflicts, updates confidence, and records provenance, automatically. delta.clarity tells you whether to keep investigating or act.
Three steps, repeated every turn.
Run It
A 30-line script that exercises the whole loop without a real LLM. Save as quickstart.ts and run with BELIEFS_KEY=bel_live_xxx npx tsx quickstart.ts.
1import Beliefs from 'beliefs'
2
3const beliefs = new Beliefs({
4 apiKey: process.env.BELIEFS_KEY!,
5 namespace: `quickstart-${Date.now()}`,
6 writeScope: 'space',
7})
8
9// 1. Seed a goal and a few priors.
10await beliefs.add('Determine the size of the AI dev tools market', { type: 'goal' })
11await beliefs.add('Market is around $4B', { confidence: 0.6, type: 'assumption' })
12
13// 2. Feed agent output. Beliefs are extracted automatically.
14const research = `Per Gartner 2024, the AI developer tools market is $4.2B, growing 25% YoY.
15GitHub Copilot, Cursor, and Tabnine account for about 65% of the market.`
16const first = await beliefs.after(research)
17console.log(`turn 1: clarity ${first.clarity.toFixed(2)}, ${first.changes.length} changes`)
18
19// 3. Feed contradicting evidence. Conflict is detected.
20const idc = `IDC Q4 2025 reports the market at $6.8B, not $4.2B.
21The earlier figure excluded embedded AI in mainstream IDEs.`
22const second = await beliefs.after(idc, { tool: 'market_research' })
23console.log(`turn 2: clarity ${second.clarity.toFixed(2)}, contradictions ${second.state.contradictions.length}`)
24
25// 4. Read the fused world state.
26const world = await beliefs.read()
27console.log(`final: ${world.beliefs.length} beliefs, clarity ${world.clarity.toFixed(2)}`)You'll see clarity move turn-over-turn, a contradiction surface when sources disagree, and the fused world state at the end. Exact numbers vary across runs (extraction is LLM-driven) but the pattern (clarity rising, conflicts detected) is stable.