Why not just keep a markdown file the agent reads?
A CLAUDE.md, a notes doc, a pinned system prompt: this is the real baseline, and for a single short task it is often enough. It breaks down the moment the work runs long or spans more than one agent.
A markdown file is a flat blob of text. It has no confidence, so a line someone wrote once reads with the same authority as a fact verified ten times. It has no provenance, so you cannot tell who claimed something or what evidence stands behind it. It has no contradiction detection, so when two lines disagree the agent acts on whichever it read last. Nothing decays, so a note that was true six months ago still reads as current. And it is single-writer by nature: two agents editing the same file clobber each other instead of merging.
A belief state is the same instinct built to be acted on. Every claim carries a posterior and its evidence, conflicting claims are surfaced and resolved by source reliability, stale evidence loses weight on a schedule, and many agents fuse into one shared, auditable picture. You still write to it in plain language through observe() and after(); the engine does the judging the markdown file leaves to you. If your agent never runs long enough to contradict itself, keep the file. When it does, that file is the bug.
How is it different from memory or RAG?
Memory systems and vector stores (mem0, LangGraph state, the Claude memory tool, RAG over embeddings) all do one thing: retrieve text that resembles a query. None of them hold a model of what is currently true. They hand back chunks and leave the judgment to you.
| Dimension | Memory / RAG | Beliefs |
|---|---|---|
| What it stores | Text chunks and vectors | Structured claims with confidence and evidence |
| Uncertainty | None. Every chunk looks equally valid | Tracked per claim, separated from how much it has been investigated |
| Conflicts | Returns both, or last-write-wins | Detected, tracked, resolved by source reliability |
| Multi-agent | Per-agent stores, no shared coherence | One fused world; cross-agent contradictions become visible |
| Decay | Falls out of context randomly | Beliefs lose strength as their evidence ages |
| Provenance | "This chunk was retrieved" | Who stated it, what evidence, how confidence evolved |
| Unknowns | No concept | Gaps are first-class and drive the next action |
Retrieval returns what was said. A belief state returns a position on it: what holds, how sure, and what would change it. They solve different problems, and you can run both, retrieval to surface candidate text and beliefs to decide what to trust.
How is it different from a "world model"?
thinkⁿ is world model infrastructure, and the belief state is the live core of it. The world model is the whole frame an agent acts from: the environment, the observations streaming in, the belief state over it, the intent, the policy, and the actions available, projected into the bounded worldview it reads before each move. Beliefs are the part that stays current as reality changes: the claims with confidence, evidence, and lifecycle the rest of the frame is organized around. See World model for the full picture.
What do you mean by the "operating state" of a business?
It is the live picture a business runs on: what's true right now, what changed, what's uncertain, what conflicts, and what action is safe. Agents can already use tools and follow workflows, but they don't carry that picture, so a human keeps re-orienting them. Beliefs holds it as shared state every agent reads before it acts and writes back as work changes, so a company can scale work without scaling management.
How is it different from an agentic framework (LangChain, CrewAI, AutoGen)?
A framework orchestrates what your agent does: graphs of LLM calls, tool routing, multi-agent coordination, control flow. Beliefs holds what your agent thinks: the claims, confidence, evidence, contradictions, and gaps that persist across turns. They sit at different layers, so beliefs does not replace your framework, it wraps the loop. It works with LangGraph, CrewAI, AutoGen, the Claude Agent SDK, the Vercel AI SDK, or any custom loop.
How is it different from LLM observability (LangSmith, Langfuse, Helicone)?
Observability records what your agent did: traces, latency, token counts, replayable logs of past runs. Beliefs records what your agent currently believes. One is a backward-looking log; the other is decision-facing state. Observability answers "what happened?" Beliefs answers "what is true right now, and what should the agent do next?" Large deployments tend to run both.
When should I not use beliefs?
Skip beliefs if you do not have a coherence problem yet:
- Single-turn work. Q&A bots, content generation, one-shot tasks. Memory or nothing is enough.
- Pure ephemeral session memory with no cross-source claims, no evolving understanding, and no contradictions to track.
- Tasks where the agent never reasons about its own confidence or gaps.
Beliefs earns its keep when an agent runs more than a few turns on the same topic, accumulates information from multiple sources, or needs to know what it does not know. If none of those apply, use memory or skip both.
Do I need to understand probability to use it?
No. Confidence is a number between 0 and 1, and that is all you need to read it. The SDK handles the math. For the probabilistic foundations, see How it works.
What happens when two claims conflict?
The fusion engine detects the conflict, resolves it by trust weight, and keeps both in the trace. Nothing is silently discarded. You can read contradictions from beliefs.read() and decide how your agent handles them.
Can I use beliefs without an adapter?
Yes. The core before / after loop works with any framework:
1const context = await beliefs.before(input)
2const result = await yourAgent.run({ prompt: context.prompt })
3await beliefs.after(result)Adapters handle framework-specific plumbing, but the core SDK is framework-agnostic.
Does performance degrade with many claims?
No. The SDK prunes and decays automatically. Stale claims lose weight over time through temporal decay, so old, low-confidence claims do not accumulate indefinitely.
Do beliefs persist across sessions?
Yes. The hosted backend persists beliefs automatically; an API key is required. There is no local-only mode in the current release, and local persistence adapters are planned for a future version.
Where do I get help?
- Beta support channel. Direct access to the engineering team.
- GitHub. Open an issue on the beliefs repo.
- Beta access. Request access if you are not yet in the program.