How is this different from RAG?
RAG retrieves text by similarity and pastes it into a prompt. Beliefs maintains a probabilistic model of what your agent thinks is true. RAG can tell you "here is a relevant paragraph." Beliefs can tell you "this claim is 85% confident, based on 3 sources, and contradicted by one." They solve different problems. You can use both.
When should I NOT use beliefs?
Skip beliefs if you don't have a coherence problem yet.
- Single-turn agents. 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, no contradictions to track. Overkill.
- Tasks where the agent never reasons about its own confidence or gaps. Beliefs add overhead without payoff.
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 doesn't know. If those don't apply, use memory or skip both.
How is this different from a vector store?
A vector store recalls snippets. Beliefs models uncertainty, tracks provenance, detects contradictions, and decays stale evidence. A vector store answers "what text is related to this query." Beliefs answers "what does the agent currently believe, how strongly, and why."
How is this different from a "world model"?
A world model is the whole structure the system uses to represent reality: beliefs, goals, gaps, contradictions, clarity, recommended next moves. Beliefs are the operational core inside it: the claims with confidence, evidence, and lifecycle. Without beliefs, a "world model" is an intelligent archive. It can retrieve context, but it can't maintain coherence as reality changes. Beliefs are what make the model live.
How is this different from an agentic framework (LangChain, CrewAI, AutoGen)?
Agentic frameworks orchestrate what your agent does: graphs of LLM calls, tool routing, multi-agent coordination, control flow. Beliefs handles what your agent thinks: the structured model of claims, confidence, evidence, contradictions, and gaps that persists across turns. They sit at different layers. You use a framework to run your agent; you use beliefs to give it a coherent view of the world. Beliefs works with LangGraph, CrewAI, AutoGen, the Claude Agent SDK, the Vercel AI SDK, or any custom loop.
How is this different from LLM observability (LangSmith, Langfuse, Helicone)?
Observability tools record what your agent did. They give you traces, latency breakdowns, token counts, and replayable logs of past runs. Beliefs records what your agent currently believes. It is decision-facing state, not a backward-looking log. Observability answers "what happened?" Beliefs answers "what is true right now, and what should the agent do next?" They are complementary; large agent deployments tend to use both.
Does this replace my agent framework?
No. Beliefs wraps your loop. It does not replace it. Use it with Claude Agent SDK, Vercel AI SDK, LangGraph, or any custom agent loop. If you have a loop, beliefs works with it.
What if I only have a single-turn agent?
Beliefs is designed for multi-turn, multi-source scenarios. For single-turn Q&A, memory or retrieval is typically sufficient. Beliefs matters when agents run multiple turns on the same topic, accumulate information that might conflict, or need to coordinate across agents.
Do I need to understand probability to use it?
No. Confidence is a number between 0 and 1; that's all you need to read it. The SDK handles the math. If you want a deeper read on the probabilistic foundations, see Internals > Math.
What happens when two claims conflict?
The fusion engine detects conflicts, resolves them by trust weight, and keeps both in the trace. Nothing is silently discarded. You can query contradictions from beliefs.read() and decide how to handle them in your agent logic.
Can I use beliefs without an adapter?
Yes. The core before/after loop works with any agent framework:
1const context = await beliefs.before(input)
2const result = await yourAgent.run({ prompt: context.prompt })
3await beliefs.after(result)Adapters handle framework-specific plumbing for you, but the core SDK is framework-agnostic.
Does performance degrade with many claims?
The SDK handles pruning and decay. Stale claims lose weight over time through temporal decay. The system self-manages 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. 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.