---
title: Quickstart
description: "The 3-step loop, plus a runnable example that prints clarity rising in under a minute."
---

<Callout type="info">
The hosted API is in private beta. [Request access](https://thinkn.ai/waitlist) to get an API key.
</Callout>

## The Loop

Every agent using beliefs follows the same cycle:

<Steps>
  <Step title="Create a belief state">

```ts
import Beliefs from 'beliefs'

const beliefs = new Beliefs({
  apiKey: process.env.BELIEFS_KEY,
  namespace: 'quickstart',
  writeScope: 'space',
})
```

  </Step>
  <Step title="Before work: read what the agent believes">

```ts
const 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.

  </Step>
  <Step title="After work: feed the observation">

```ts
const result = await myAgent.run({ context: context.prompt })
const 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.

  </Step>
</Steps>

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

```ts
import Beliefs from 'beliefs'

const beliefs = new Beliefs({
  apiKey: process.env.BELIEFS_KEY!,
  namespace: `quickstart-${Date.now()}`,
  writeScope: 'space',
})

// 1. Seed a goal and a few priors.
await beliefs.add('Determine the size of the AI dev tools market', { type: 'goal' })
await beliefs.add('Market is around $4B', { confidence: 0.6, type: 'assumption' })

// 2. Feed agent output. Beliefs are extracted automatically.
const research = `Per Gartner 2024, the AI developer tools market is $4.2B, growing 25% YoY.
GitHub Copilot, Cursor, and Tabnine account for about 65% of the market.`
const first = await beliefs.after(research)
console.log(`turn 1: clarity ${first.clarity.toFixed(2)}, ${first.changes.length} changes`)

// 3. Feed contradicting evidence. Conflict is detected.
const idc = `IDC Q4 2025 reports the market at $6.8B, not $4.2B.
The earlier figure excluded embedded AI in mainstream IDEs.`
const second = await beliefs.after(idc, { tool: 'market_research' })
console.log(`turn 2: clarity ${second.clarity.toFixed(2)}, contradictions ${second.state.contradictions.length}`)

// 4. Read the fused world state.
const world = await beliefs.read()
console.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.

## Where to next

<CardGroup cols={3}>
  <DocsCard title="Tutorial" description="A 30-minute guided build. Goals, priors, contradictions, moves, trace. One concept per section." href="/dev/tutorial/research-agent" />
  <DocsCard title="Hack Guide" description="Framework recipes for Vercel AI, Anthropic, OpenAI, and plain fetch. Pick your stack and ship." href="/dev/tutorial/hack-guide" />
  <DocsCard title="Core API" description="Full method reference: every method, every option." href="/dev/sdk/core-api" />
</CardGroup>