---

Belief Context Graph

Reasoning-Traceable Graph · Belief-Conditioned Loop

_{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

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

bcg-demo-release.mp4

---

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+.

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:

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 for everything else.

🔨  BCGRunner — build the first belief context graph  →  Construct the first BCG · Understand your graph

🧠  BCGMemory — query beliefs and assemble context  →  Read Memory · Memory Methods

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:

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:

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

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:

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 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 file for details.

---

Corresponding and Contributing

We are very pleased to answer any questions about BCG: lijiaqi@bigai.ai, zlzheng@bigai.ai We appreciate your interest in contributing to our open-source initiative.