beliefstate 1.2.0

A sidecar belief state tracker for LLM agents to detect contradictions and maintain persistent facts.

BeliefState

Persistent memory for LLM applications.
Extract facts, resolve contradictions, and recall knowledge — automatically.

---

The Problem

Every time a user starts a new conversation, your LLM starts from zero. It doesn't remember that the user is a Rust developer in Berlin, prefers dark mode, or already explained their project architecture three messages ago.

You can dump the full chat history into the system prompt, but that burns tokens fast — and most of it is noise. RAG helps with documents, but user facts (preferences, identity, context) fall through the cracks. There's no clean way to say "remember this about the user" without manual bookkeeping.

How BeliefState Works

BeliefState sits between your LLM and your application. Every time the LLM responds, it silently:

1. Extracts facts — "user prefers Rust", "project uses PostgreSQL", "works at Google"
2. Detects contradictions — if the user says "I live in Tokyo" after saying "I live in Berlin", it flags the conflict
3. Stores beliefs — persisted in SQLite, PostgreSQL, or Redis with full history
4. Injects context — on the next call, relevant beliefs are added to the system prompt automatically

All of this happens in the background. Zero added latency to your request path.

from beliefstate import BeliefTracker
from beliefstate.adapters import OpenAIAdapter

tracker = BeliefTracker(
    adapter=OpenAIAdapter(model="gpt-4o"),
    config=TrackerConfig(store_type="sqlite", store_kwargs={"db_path": "beliefs.db"})
)

@tracker.wrap
async def chat(messages):
    return await openai_client.chat.completions.create(model="gpt-4o", messages=messages)

tracker.set_session("user_123")
await chat([{"role": "user", "content": "I live in Tokyo and work at Google."}])
# BeliefState extracts: {subject: "user", predicate: "lives_in", value: "Tokyo"}

---

Features

Feature	Description
Zero-latency tracking	Background extraction pipeline — no added latency to your request path
Dual-source extraction	Extracts beliefs from both user messages and assistant responses every turn
5+ LLM providers	OpenAI, Anthropic, Gemini, Ollama, LiteLLM (100+ models via LiteLLM)
Dual-adapter architecture	Expensive model for your app, cheap/local model for background tracking
NLI contradiction detection	3-stage pipeline: rule-based → embedding similarity → LLM judge, with negation awareness and exact-match dedup
3 resolution strategies	overwrite, keep_old, or raise — with escalation logic (ASK → BLOCK) and per-belief resolution notes
Confidence calibration	Automatic hedging detection, per-source confidence caps (user/assistant), hypothetical flagging
Belief categorization	Extracted beliefs grouped into 5 categories: identity, technical, planning, constraint, state
Persistent stores	SQLite, PostgreSQL, Redis — with full audit trails, binary embedding storage, and automatic schema migration
Streaming support	@tracker.wrap(stream=True) intercepts async generators, accumulates text, and dispatches tracking on completion
Automatic context injection	Relevant beliefs injected into the system prompt on every call — with category-grouped summarization
Token-aware injection	Relevance-based belief selection within a configurable token budget using vector similarity
Framework integrations	LangChain, LlamaIndex, FastAPI, Flask, ASGI, WSGI, OpenAI Assistants
Production resilience	Retry with exponential backoff, circuit breakers (per operation), health checks, graceful shutdown with task draining
Pluggable dispatchers	Asyncio (in-process), Sync, Celery, Redis Queue — survives server restarts
GDPR-compliant	clear_session() with auditable deletion receipts and in-flight task draining
Staleness scoring & TTL	Automatic belief decay (confidence / days_since_reference) and configurable time-based pruning
Belief export/import	JSON round-trip for portable belief data; CSV export via dashboard
Developer Dashboard	Live browser UI with charts, session compare, contradiction heatmaps, global search, alert rules, keyboard shortcuts, and real-time SSE pipeline events
Observability	OpenTelemetry traces and metrics, structured TrackerEvent logging with JSON output

---

Installation

pip install beliefstate

With optional extras:

pip install "beliefstate[openai]"         # OpenAI adapter
pip install "beliefstate[anthropic]"      # Anthropic adapter
pip install "beliefstate[gemini]"         # Gemini adapter
pip install "beliefstate[ollama]"         # Ollama adapter (local)
pip install "beliefstate[litellm]"        # LiteLLM (100+ providers)
pip install "beliefstate[local]"          # Local embeddings (sentence-transformers)
pip install "beliefstate[redis]"          # Redis store
pip install "beliefstate[postgres]"       # PostgreSQL store
pip install "beliefstate[langchain]"      # LangChain integration
pip install "beliefstate[llamaindex]"     # LlamaIndex integration
pip install "beliefstate[fastapi]"        # FastAPI middleware
pip install "beliefstate[flask]"          # Flask middleware
pip install "beliefstate[dashboard]"      # Developer dashboard (fastapi, uvicorn)
pip install "beliefstate[all]"            # Everything

---

Documentation

For provider setup, store configuration, framework integrations, advanced usage, and API reference:

https://abhay-2108.github.io/beliefstate/

---

Quick Example: Dual-Adapter Setup

Use Claude for your app, Llama 3 for background tracking — zero API costs for belief extraction:

from beliefstate import BeliefTracker
from beliefstate.adapters import AnthropicAdapter, OllamaAdapter

tracker = BeliefTracker(
    adapter=AnthropicAdapter(model="claude-3-5-sonnet-latest"),
    internal_adapter=OllamaAdapter(model="llama3", embed_model="nomic-embed-text"),
)

---

Development

git clone https://github.com/abhay-2108/beliefstate.git
cd beliefstate
pip install -e ".[dev]"
pytest
ruff check beliefstate/

---

Contributing

Contributions are welcome! Please read our Contributing Guide for details on the development setup, coding standards, and pull request process.

This project follows a Code of Conduct. By participating, you agree to uphold it.

For security vulnerabilities, please see our Security Policy.

For version history, see the Changelog.

---

License

Apache License 2.0. See LICENSE for details.