Persistent memory for LLM applications.
Extract facts, resolve contradictions, and recall knowledge — automatically.
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.
BeliefState sits between your LLM and your application. Every time the LLM responds, it silently:
- Extracts facts — "user prefers Rust", "project uses PostgreSQL", "works at Google"
- Detects contradictions — if the user says "I live in Tokyo" after saying "I live in Berlin", it flags the conflict
- Stores beliefs — persisted in SQLite, PostgreSQL, or Redis with full history
- 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"}| 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 |
pip install beliefstateWith 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]" # EverythingFor provider setup, store configuration, framework integrations, advanced usage, and API reference:
https://AltioraLabs.github.io/beliefstate/
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"),
)git clone https://github.com/AltioraLabs/beliefstate.git
cd beliefstate
pip install -e ".[dev]"
pytest
ruff check beliefstate/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.
Apache License 2.0. See LICENSE for details.