---
title: Environment
description: "The world the agent operates on: the entities and relations that structure it, declared per domain."
---
Every agent wakes up asking the same question: *where am I, and what is this place?* A codebase. An account. A production line. A portfolio. A patient. The same engine runs all of them. What changes from one world to the next is never the engine. It is the declaration.
An environment is the world the agent acts on and the structure of that world: the things that exist in it and the ways they connect. Beliefs live inside an environment, which is what gives them something to refer to. A claim about a service is a claim *about something in this world*, and the environment is what makes "something" a first-class object the agent can reason over.
## Entities and Relations
Two pieces structure a world.
**Entities** are the things that exist in it. A service. A customer. A position. A route. A test suite. Each is a thing the agent's beliefs can be *about*.
**Relations** connect them. `depends_on`, `documented_by`, `owns`. A relation ties two entities together with a typed predicate, so "the ledger service depends on Postgres" is a structured fact, not a sentence the agent has to re-parse every turn.
Both are first-class nodes in the belief graph. That choice is load-bearing. The engine stays *uncertain about its own structure*: it does not treat the entity set and the wiring between entities as fixed truth handed down from a config file. It treats them as claims it holds, with the same evidence and confidence machinery every other belief gets. The graph can be wrong about what exists, and find out it was wrong, the same way it can be wrong about any fact.
## Relations Are Claims, Not Raw Edges
In most graph stores an edge is a hard link. It is there or it is not. An entity-to-entity relation here is a belief: it carries its own posterior and its own evidence. "Service A depends on service B" can be supported by what the engine has seen, refuted by later evidence, or superseded when the dependency moves. It updates like any other claim, because it *is* one.
A graph edge, then, is the projected view of that relation once it clears a threshold. The relation belief accumulates evidence; when its confidence rises past the bar for its kind, it surfaces as an edge you can draw and traverse. Below the bar, the relation still exists as a claim under consideration. The edge you see is the confident slice of a richer, uncertain structure underneath.
This is why a connection can disagree with itself, age out, or get reconsidered. The structure is held as belief, not asserted as fact.
## A World Is Declared Per Domain
A world is declared once, per domain. The declaration names three things:
- its **kind** (what sort of place this is),
- its **entity types** (what kinds of things exist here), and
- the **relation kinds** it supports (which predicates connect them).
The engine reads this declaration to route extraction and to shape the graph. When an observation comes in about a codebase, the declaration tells the extractor that services and modules are entities worth pulling out, and that `depends_on` is a relation worth drawing. Point the same engine at a portfolio and the entity types become positions and instruments, the relations become `hedges` and `correlates_with`. Nothing in the engine changes.
Adding a world is shipping a declaration. It is not editing the engine. That is the whole design: the inference machinery is fixed and shared, and a domain is a file that tells that machinery what its world is made of.
The set of entity types and relation kinds a world supports is the lever a developer pulls to teach the engine a new domain. The math, the fusion, the calibration, and the projection are constant across every world. Domain knowledge enters as the declaration, not as forked engine code.
## Ground Truth and the Belief Over It
The environment has a real state, whether or not anyone has observed it. The dependency graph of a codebase exists as it actually is. Call that ground truth: the latent state of the world.
The belief state is the agent's posterior over that latent state. The agent never sees ground truth directly. It sees observations, and from them holds an estimate of what is true, calibrated against outcomes where a claim resolves and balance-of-evidence where it does not. The environment is the thing being estimated. The belief state is the estimate.
When an agent orients, the environment slice of its worldview surfaces what it needs to know before it reasons: the world id, the world kind, the entities currently in play, and the source-of-truth ranking (which sources outrank which when they disagree). That slice answers *what am I looking at* so the rest of the orientation, what's true now and what to do next, has a place to stand.
## Reading Relations Back from the Graph
`beliefs.graph()` returns the environment as a graph: the entities and the typed relationships between them. Each relationship carries confidence rather than a flat link, so the view tells you how strongly the evidence backs a connection, not only that the connection exists.
```ts
const projection = await beliefs.graph({
filter: { kinds: ['claim', 'goal'], minConfidence: 0.4 },
})
for (const node of projection.nodes) renderNode(node)
for (const edge of projection.edges) {
// edge.confidence is the posterior on the relation, not a 0/1 link
renderEdge(edge)
}
```
The `minConfidence` filter drops edges below a confidence floor, which is the threshold idea made concrete: ask for the confident structure and the low-evidence relations stay out of the view. The full belief state, including the relations still under consideration, is always there to read; the graph projection is the slice you draw.
For the broader read shape, `beliefs.read()` returns the entities and edges alongside the rest of the world model (beliefs, gaps, contradictions, moves), so the environment is never separated from the claims that live in it.