BeliefLang · experimental language

Beliefs as state.
Decisions as code.

Define beliefs, track uncertainty, and update state from new observations. Use deterministic rules to decide what happens next.

Try the playground GitHub ↗ Documentation

observe request("A flight or a hotel")
infer beliefs from request

when entropy(intent) > 0.5:
  ask_user("Which would you like to book?")

intent:
  book_flight = 0.50
  book_hotel  = 0.50

[ask_user] Which would you like to book?

Run this example ↓

Playground

Example Trace

Runs in your browser. No API key required. Help.

Belief state

Variables

Observations

Tools and actions

Execution trace

BeliefLang v3 · October 18, 2026

Incremental memory benchmark

20.5%fewer tokensvs full-history retrieval

26.4%lower estimated LLM costvs full-history retrieval

48.9%fewer tokensvs rolling summaries

59.6%lower estimated LLM costvs rolling summaries

One repetition of three scripted 24-turn conversations using GPT-6 Luna. Costs are estimated from measured tokens and frozen pricing assumptions.

Plain JSON achieved essentially identical accuracy, token use, and cost to BeliefLang v3. The gains came from structured state and deterministic processing, not the language syntax.

Totals across sparse and dense demand
Approach	Accuracy	Estimated model cost
Full history	89.22%	$0.00598334
Rolling summary	91.18%	$0.01089550
Plain JSON	100%	$0.00440132
BeliefLang v3	100%	$0.00440352

Results and limitations · Methodology · Reproduce the results

Earlier experiments.

Observe, infer, merge, then act

Observe a message, infer and merge updates, then check confidence and entropy.

let message = "I need a cheap direct flight to Berlin"

observe user_message(message)
infer beliefs from user_message

let extracted = call extract_patch()
merge beliefs from extracted

when confidence(intent.book_flight) > 0.7 && confidence(user.budget_sensitive) > 0.5:
  call rank_flights()

when entropy(intent) > 0.5:
  ask_user("Can you clarify your travel intent?")

intent.book_flight = 0.920
user.budget_sensitive = 0.860
entropy(intent) = 0.402
rule 1 => true
rule 2 => false
[call] rank_flights()

Run this example ↓

Language and runtime

Write rules in `.bel`

Belief declarations, confidence and entropy operations, conditional rules, variables, tool calls, observations, inference adapters, and merging updates.

Language reference →

TypeScript runtime

Snapshots and provenance inspection. V3 factual-memory APIs retain historical values, track conflicts, and check evidence and authorization before actions.

Memory and action checks →

Use OpenAI or Jev for inference, or connect another model through the TypeScript inference adapter.

Current limitations

V3 factual memory and decision guards are TypeScript APIs, not .bel syntax.
Fact verification and action authorization come from the host application.
Change history is bounded; saved state can grow. Automatic archival is not implemented.
General dependency tracking, selective invalidation, and broader caching remain research directions.

Quick start

Node.js 22 or later.

git clone https://github.com/belieflang/belieflang.git
cd belieflang
npm ci
npm run build
node dist/src/cli.js run examples/intent.bel --trace

README and quick start · Model integrations and experiment commands

Roadmap

Test longer conversations and less expensive models against JSON and full history.
Work out when a changed value means a saved answer must be recalculated.
Test whether dedicated syntax adds enough value over an ordinary TypeScript library.

What we've learned so far · Source and issues on GitHub →