beliefs

A belief layer for AI agents.

Private Beta — Request access.

The Missing Layer

Your agent remembers things. It retrieves context. It calls tools. But ask it what it currently believes about the problem it is solving — what is strong, what is weak, what conflicts, what is missing — and it has no answer.

beliefs gives your agent a structured model of its current understanding: what it thinks is true, how confident it is, and why.

Install

npm i beliefs

The Pattern

import Beliefs from 'beliefs'

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

// 1. Before work: read what the agent believes
const context = await beliefs.before(userMessage)

// 2. Run your agent with belief context
const result = await myAgent.run({ context: context.prompt })

// 3. After work: feed the observation
const delta = await beliefs.after(result.text)

console.log(delta.clarity)    // 0-1 readiness to act
console.log(delta.moves)      // suggested next actions

before() returns what the agent currently believes — claims with confidence, goals, gaps, a clarity score, and suggested next moves. after() submits what happened — the infrastructure handles extraction, conflict detection, fusion, and provenance tracking.

For chat-style session memory, use thread scope and bind a thread:

const baseBeliefs = new Beliefs({
  apiKey: process.env.BELIEFS_KEY,
  namespace: 'support',
  writeScope: 'thread',
})

const beliefs = baseBeliefs.withThread(conversationId)

writeScope: 'thread' is the default. If you do not have a thread ID yet, either bind one later with withThread() or choose writeScope: 'agent' / writeScope: 'space'.

API

| Method | Description | |--------|-------------| | beliefs.before(input?) | Read beliefs + clarity + moves before agent acts | | beliefs.after(text, opts?) | Feed observation → extract → fuse → get delta. Use source to label where it came from. | | beliefs.add(text, opts?) | Assert a specific belief, goal, or gap. Use source to track provenance. | | beliefs.resolve(text) | Mark a gap as resolved | | beliefs.read() | Read the full fused world state (each belief has a source field) | | beliefs.snapshot() | Lightweight read of beliefs/goals/gaps/edges — no clarity/moves | | beliefs.list(opts?) | Paged read with query/filter/cursor/limit (canonical app-builder read) | | beliefs.get(beliefId) | Detail page payload — belief + relations + links + history + recommended move | | beliefs.graph(opts?) | Render-focused projection (nodes + weighted edges + structured contradictions) | | beliefs.search(query) | Deprecated alias for list({ query }).then(r => r.beliefs) | | beliefs.trace(id?) | Query the belief audit trail (each entry has a source field) | | beliefs.retract(id, reason?) | Mark a belief as retracted (stays in graph, lifecycle changes) | | beliefs.remove(id) | Delete a belief entirely (ledger entry recorded) | | beliefs.removeWhere({ source }) | Bulk remove beliefs that share a '<kind>:<id>' provenance ref (currently block:) | | beliefs.reset() | Clear all beliefs, goals, gaps, and intents in this scope | | beliefs.subscribe(handler, opts?) | Subscribe to live belief-stream events for this scope (returns { done, unsubscribe }) | | beliefs.streamExtraction(req, h?) | Run a request-scoped extraction stream and yield each frame | | beliefs.moves.list() | List recommended next-best-move actions | | beliefs.moves.generate({ beliefId }) | Generate or fetch the best next move for a belief | | beliefs.moves.act(moveId, action) | Accept / snooze / dismiss a move | | beliefs.trust.set(target, opts) | Tell the engine "I trust this agent (or evidence source) at confidence X, strength Y" | | beliefs.trust.list({ kind? }) | List the current scope's trust overrides | | beliefs.trust.get(target) | Fetch one override by {kind, id}, or null when none is set | | beliefs.trust.unset(target) | Revert an override; returns { removed } | | beliefs.admin.auditMoves(spaceId) | (serviceToken only) Inspect persisted thinking moves for a space | | beliefs.admin.regenerateMoves(spaceId) | (serviceToken only) Regenerate suggested moves for a space | | beliefs.withThread(threadId) | Clone a client with the same config but a bound thread |

Scope Model

Use namespace to isolate one project or tenant from another.

Use writeScope to choose where authoritative memory lives:

• thread — per conversation or task. Requires thread or withThread(threadId).
• agent — durable per-agent memory across threads inside a namespace.
• space — one shared memory for the whole namespace.

Use contextLayers to control what before() and read() merge in:

• thread default: ['self', 'agent', 'space']
• agent default: ['self', 'space']
• space default: ['self']

What the Hosted API Does for You

• Extraction — LLM-powered belief extraction from agent output and tool results
• Linking — Automatic detection of contradictions, support, and derivation relationships
• Deduplication — Embedding-based similarity matching to prevent duplicate beliefs
• Fusion — Trust-weighted merging across multiple agents
• Clarity — Readiness assessment based on decision resolution, certainty, coherence, and coverage
• Thinking Moves — POMDP-based suggestion of highest-value next actions
• Provenance — Full audit trail of every belief transition

What the SDK Does Not Do

• Does not replace your agent framework
• Does not decide what your agent does
• Does not require a specific LLM provider
• Does not sit in the critical path of your LLM calls

The SDK wraps your loop. It does not own it.

Links

• Documentation
• Beta Access

License

Apache-2.0