****
# Belief Context Graph
**Reasoning-Traceable Graph ยท Belief-Conditioned Loop**
[](https://www.python.org/)
[](https://opensource.org/licenses/MIT)
[](https://docs.astral.sh/uv/)
[](https://bigai-nlco.github.io/belief-context-graph/)
[](https://belief-context-graph.docs.buildwithfern.com/)
[](assets/bcg_qr_code.png)
[](assets/bcg_discard_qr_code.png)
Agent: gpt-5.6-luna with low-effort thinking ยท Graph/Summary: gpt-5.6-luna with thinking disabled ยท Harness: repository harness
## News
> [!IMPORTANT]
> ### ๐ Bring Belief Context Graph to Codex!
>
> **BCG for Codex is here!** Bring belief-aware memory to your coding workflow and take on long-horizon tasks.
>
> **[โ Get started with BCG for Codex](#use-bcg-with-codex)**
>
## **Why Belief Context Graph**
**Current agent memory systems fall short.** Conversation memory preserves history. Vector memory retrieves similar fragments. GraphRAG extracts entities and relations. Trace memory records tool calls. Temporal KGs track facts over time.
> These systems answer **retrieval questions**: *which text is relevant? which entities are related? what happened in the past?*
But agents executing real tasks also need to answer **belief questions**:
> - Should I actually believe this fact?
> - Is it still valid, or has it expired?
> - Did it come from a reliable source?
> - Does it conflict with other evidence?
> - Is it certain enough to act on?
> - Did the outcome prove my prior belief wrong?
Belief Context Graph (`BCG`) upgrades agent memory from **retrieval memory** to **belief context graph**. It is a probabilistic, temporal, evidence-grounded and computational memory substrate that helps agents continuously maintain: what to believe, at what confidence, from which evidence, and whether uncertainty should block action. The result is agent memory you can query, audit, and trust.
## **Core capabilities:**
- **Belief Extraction:** Segment trajectories, extract structured beliefs that counts for agent reasoning and link them into a connected graph
- **Deterministic Confidence:** Auditable posterior confidence computed from `initial_confidence`, `evidence_confidence`, and relation-derived `factor_confidence`; source reliability and stance quality set the prior, while relation weights and activation thresholds propagate support or contradiction deterministically
- **Evidence Provenance:** Every belief carries exact-offset source references back to the originating conversation turn
- **Temporal Awareness:** Run-based lifecycle with sessions and timestamps โ know when each belief was formed and how it evolved
- **Relation Linking:** Forward and backward relationship edges between beliefs, forming a casual decision graph/trace.
## Live Demo
https://github.com/user-attachments/assets/fa10c247-7f6f-4567-9a1f-648c79b1df44
---
News ยท
Quick Start ยท
Architecture ยท
Case Study ยท
Project Status ยท
Comparison ยท
Contributing
---
## Quick Start
Requires Python 3.11โ3.13. The optional reference terminal Agent additionally requires Node.js 22.19+.
```bash
git clone https://github.com/bigai-nlco/belief-context-graph.git
cd belief-context-graph
make install
uv run bcg --version
```
Launch the bundled reference Agent to try BCG immediately โ integrating BCG into your own Agent does not require this CLI:
```bash
uv run bcg
```
The first run walks you through model credentials, context mode, and Graph Construction backend, and saves your choices under `~/.bcg`. See the [documentation](https://belief-context-graph.docs.buildwithfern.com/) for everything else.
> ๐จ `BCGRunner` โ build the first belief context graph โ [**Construct the first BCG**](https://belief-context-graph.docs.buildwithfern.com/quickstart) ยท [**Understand your graph**](https://belief-context-graph.docs.buildwithfern.com/first-graph)
>
> ๐ง `BCGMemory` โ query beliefs and assemble context โ [**Read Memory**](https://belief-context-graph.docs.buildwithfern.com/guides/python) ยท [**Memory Methods**](https://belief-context-graph.docs.buildwithfern.com/sdk/memory/observe-belief)
### Use BCG with Codex
Bring belief-backed memory to your existing Codex workflow. Install Codex separately and sign in with ChatGPT using `codex login`. BCG for Codex requires Python 3.11โ3.13 and `uv`.
#### 1. Install and initialize
From this repository, install BCG, then initialize the project where you want to use it:
```bash
uv tool install --force --python 3.13 .
cd /path/to/your/project
bcg codex init \
--env-file ~/.bcg/.env \
--allow-graph-upload
```
Project settings and session records stay in `.bcg-codex/`. Initialization does not change your Codex configuration or sign-in, and running it again preserves your existing Graph settings and records.
#### 2. Configure the Graph model
The default Graph model is `openai/gpt-6-luna` through OpenRouter with `reasoning_effort=none`. Create or edit `~/.bcg/.env` and add your Graph API key:
```dotenv
OPENROUTER_OPENAI_API_KEY=your-graph-api-key
```
To use another model or provider, edit `model`, `base_url`, `api_key_env`, and `reasoning_effort` in `.bcg-codex/graph-model.json`. The key named by `api_key_env` must exist in your selected env file. Graph API usage is billed separately from your Codex subscription. A local embedding model may download on first use.
#### 3. Start Codex with BCG
```bash
bcg codex
```
Use `bcg codex` whenever you want BCG enabled; plain `codex` does not enable it. Arguments after `--` are passed to Codex, so you can also specify your preferred model and reasoning settings. Exit Codex to end the session.
To continue a previous conversation from the same project:
```bash
bcg codex resume # Choose a saved session
```
**Records and privacy.** Graph records are in `.bcg-codex/state/graphs/`, and request audits are in `.bcg-codex/state/gateway/requests.jsonl`. Add `--record-model-io` before the `--` separator to save full request/response logs. The `--allow-graph-upload` flag authorizes sending conversation and tool text to your Graph provider. Keep keys and private records out of version control. See the [Codex integration guide](docs/codex-native-integration.md) for diagnostics and limitations.
---
## Architecture
BCG is an optional context layer between an Agent and its model. In BCG mode, the initial user input and recent completed turns remain in the raw context, while older completed turns stream into Graph Construction; the resulting belief snapshot is then injected into the system prompt. Both the HTTP service and the Python SDK use the same backend registry, construction pipeline, confidence semantics, and graph artifacts.
---
## Gains of BCG for Agentic Tasks
This successful BrowseComp case (`browsecomp-0836`) shows Kimi K3 using belief identities and confidence from BCG instead of repeating an already completed search.
---
## Project Status
BCG currently provides a belief-native memory SDK, unified and hybrid graph-construction backends, an optional HTTP service, a reference Agent integration, reproducible benchmark tooling, and graph visualization support. The next development phase focuses on two directions:
1. **A more principled probabilistic foundation.** Develop probability calculation and propagation methods that are more reasonable and better grounded in Bayesian inference or other mathematically justified uncertainty frameworks. This includes clarifying priors, likelihoods, evidence dependence, contradiction handling, graph-path effects, and calibration while preserving auditability.
2. **Deep Research.** Extend BCG from belief-aware context management toward a Deep Research workflow that can plan investigations, track source provenance and temporal validity, reconcile conflicting findings, identify missing evidence, and produce auditable research outputs.
---
## Comparison with Relevant Solutions
Agent memory systems serve different purposes. Below is a feature-level comparison of BCG against the most widely-used memory and knowledge graph solutions in the LLM agent ecosystem.
| | Mem0 | Zep | Letta (MemGPT) | LangChain Memory | LlamaIndex | TrustGraph | Semantica | **BCG** |
|---|---|---|---|---|---|---|---|---|
| **Belief-native extraction** |โก | โก|โ |โก |โก |โก |โก |โ
|
| **Deterministic confidence** | โ| โ|โ |โ |โ |โ |โก |โ
|
| **Evidence provenance** | โก|โ
| โก| โก| โก| โ
|โ
| โ
|
| **Temporal lifecycle** | โก| โ
| โก| โก| โ|โก| โ
| โก|
| **Relation linking** |โก | โ
| โ|โ | โก| โ
| โ
| โ
|
| **Local-first artifacts** |โก | โ| โ
| โก| โ
|โ
| โ
|โ
|
| **Graph queryability** | โ| โ
|โ |โ | โก| โ
|โ
|โก |
| **Merge / dedup** |โก |โ
| โก|โก |โก |โก |โ
| โ
|
| **Conflict detection** |โก | โ
|โ | โก| โ|โ |โ
| โ
|
| **Run without an independent DB** | โ
|โ
| โ
|โ
| โ
| โ|โ
|โ
|
> โ
Full support โก Partial / optional โ Not supported
---
## License
MIT โ see the [LICENSE](LICENSE) file for details.
---
## Corresponding and Contributing
We are very pleased to answer any questions about BCG: [lijiaqi@bigai.ai](mailto:lijiaqi@bigai.ai), [zlzheng@bigai.ai](mailto:zlzheng@bigai.ai) We appreciate your interest in contributing to our open-source initiative.