SDK Overview

Architecture

The SDK has two layers:

Core (beliefs). The foundation. Framework-agnostic. Works with any agent loop. Provides before, after, add, resolve, read, snapshot, search, trace, reset, retract, and remove.

Adapters (built-in). Framework-specific wrappers that automatically hook into your agent's lifecycle. beliefs/claude-agent-sdk for Anthropic, beliefs/vercel-ai for Vercel AI SDK.

1Your Agent Loop
2    │
3    ├── beliefs.before()  ←── get context + moves
4    │
5    ├── agent.run()       ←── your agent, unchanged
6    │
7    └── beliefs.after()   ←── feed observation → extract → fuse

Layered Memory

The SDK separates where you write from what context you read.

• namespace isolates one project or tenant from another.
• writeScope chooses the authoritative layer: thread, agent, or space.
• contextLayers chooses which layers before() and read() merge together.

For the simplest setup, start with a shared namespace-wide state:

1const beliefs = new Beliefs({
2  apiKey,
3  namespace: 'project-a',
4  writeScope: 'space',
5})

For chat or session memory, keep the default thread scope and bind a thread:

1const baseBeliefs = new Beliefs({
2  apiKey,
3  namespace: 'support',
4  writeScope: 'thread',
5})
6
7const beliefs = baseBeliefs.withThread(conversationId)

How It Works

1. Before the agent acts, call beliefs.before(). You get the current belief state, a clarity score, and suggested next moves. Inject context.prompt into your agent's system prompt.

2. The agent runs normally. The SDK does not modify agent behavior. It observes.

3. After the agent acts, call beliefs.after(output). The infrastructure processes the output as an observation:

   • Extract — LLM-powered belief extraction finds claims, assumptions, risks, gaps
   • Link — Detects relationships: supports, contradicts, derives
   • Deduplicate — Embedding-based similarity prevents duplicate beliefs
   • Fuse — Trust-weighted merge into the world state
   • Trace — Every transition recorded with entropy and provenance

4. On the next turn, beliefs.before() reflects the updated state. Clarity has changed. Moves have shifted. The agent acts with better context.

Core API

See the Core API reference for full method signatures and return types.

Multi-Agent

Multiple agents contribute to the same shared belief state by using different agent identifiers with writeScope: 'space':

1const researcher = new Beliefs({
2  apiKey,
3  namespace: 'project-a',
4  agent: 'researcher',
5  writeScope: 'space',
6})
7
8const analyst = new Beliefs({
9  apiKey,
10  namespace: 'project-a',
11  agent: 'analyst',
12  writeScope: 'space',
13})
14
15await researcher.after(researchOutput)
16await analyst.after(analysisOutput)
17// Both contribute to the same world state, fused by trust weight

If each agent needs private working memory plus shared background context, use writeScope: 'agent' and keep the default layered reads.

Namespace Isolation

Each namespace is an independent belief state:

1const projectA = new Beliefs({ apiKey, namespace: 'project-a', writeScope: 'space' })
2const projectB = new Beliefs({ apiKey, namespace: 'project-b', writeScope: 'space' })
3// Completely separate belief states