Engineering

In a codebase, the world model is the agent's live read on what is true about the system. Which invariants hold, where the risk sits, and how sure it is, checked against tests that actually run. A codebase checks itself. The tests pass or they don't, the build is green or red, the diff applies or it conflicts, which makes engineering the world where a shared, auditable belief state is easiest to prove. Picture a payments company whose platform agent is about to refactor the export flow. Before it touches code it needs the truth about auth coverage now, not a guess from training. That belief state lives outside the model, so the agent reads what is true now instead of re-deriving it every turn.

The world

The environment is the system under change: services, modules, endpoints, dependencies, and the trust boundaries between them. Entities are the components. Relations are the calls, imports, and ownership edges that bind them. Ground truth lives in the tests, the build, and the diff, so a belief about this world gets confirmed or refuted against a check that runs, never just asserted into the record.

What streams in

The agent's observations are the artifacts that report how the system actually behaves:

• diffs and PRs (what changed)
• CI runs and test output (what passed)
• dependency audits and CVE advisories (what's exposed)
• logs, traces, and incident reports (what broke)

Each one folds into the belief state as evidence for or against what the agent currently holds true. A green CI run on the auth suite raises confidence in "all routes require auth." A new CVE advisory drops confidence in "no critical CVEs in dependencies." The agent doesn't store these as facts to recall later; it updates a posterior it can defend.

The belief state

The agent's read on the system's security posture is a set of claims. Each one carries an explicit posterior, the evidence behind it, and a decay schedule, alongside the gaps it knows it hasn't closed.

1┌──────────────────────────────────────────────────────────────┐
2│  SECURITY POSTURE                                            │
3│                                                              │
4│  ● "No critical CVEs in dependencies"  74% │ audit 30d ago   │
5│  ● "All API routes require auth"       81% │ middleware scan │
6│  ● "SQL injection mitigated"           92% │ parameterized   │
7│  ● "No secrets in source control"      65% │ 3mo old scan    │
8│    └─ ⚠ Decayed - last scanned 90 days ago                   │
9│                                                              │
10│  Gap: "No SSRF analysis on new webhook handler"              │
11│  Gap: "Rate limiting untested on file upload endpoint"       │
12└──────────────────────────────────────────────────────────────┘

These usually live as unspoken assumptions. "All inputs are sanitized." "The auth middleware covers every state-changing endpoint." Once they are explicit, each becomes something the agent gathers evidence for. A contradiction then surfaces as a flagged conflict instead of a silent gamble: when a fresh CVE advisory lands against "no known vulnerabilities," the engine raises it rather than letting the newer artifact quietly win.

What we're after

A belief state without a goal is just a status board. The intent is what turns it into a plan. Here the goal is to ship the export refactor without regressing the system, and the engine ranks moves toward closing the distance to that goal, not toward shrinking raw uncertainty wherever it happens to be highest. An ambiguous belief in a quiet corner of the codebase stays low-priority; the one blocking the refactor rises to the top.

That limiting belief is why the top move points at evidence-gathering before code. Until it's re-verified, the refactor is a gamble against a stale scan, and the engine ranks the audit ahead of the diff.

The policy

A world has rules the agent should respect, independent of what it currently believes. In a codebase those are the invariants, the source hierarchy for resolving disagreement, the conventions, and the anti-patterns to avoid. You encode them in how you observe and act.

Two beliefs from different sources should not carry equal weight. When a stale comment claims one thing and a passing test shows another, the source hierarchy you've encoded is how your agent decides which to trust, and the comment loses.

The actions

The world also defines what the agent can do in it. Each action carries a safety class so the surface stays honest about blast radius:

The engine never takes these actions for you. Your agent does. What the engine provides is the picture the agent reads to choose among them, and the record of what each action changed.

Today, policy and actions are a modeling lens you encode. The invariants, source hierarchy, and safety classes live in how you observe and act, not in a policy the engine enforces. Read the tables above as the contract your agent upholds, not one the engine guarantees. A declarative config surface to register policy directly is on the roadmap.

Plan & act

With the frame in place, the loop is short. The agent orients on the current picture, reads the highest-value next move (ranked by expected information gain and already in hand), runs the matching action, and folds the result back in as the next observation:

1import Beliefs from 'beliefs'
2
3const beliefs = new Beliefs({
4  apiKey: process.env.BELIEFS_KEY,
5  agent: 'security-agent',
6  namespace: 'security-review',
7  writeScope: 'space',
8})
9
10// 1. Orient: read the current picture; the ranked next moves ride back on it
11const context = await beliefs.before('Review auth coverage before the export refactor')
12const [move] = context.moves   // top-ranked, already in hand; no extra call
13// → { action: 'gather_evidence', subType: 'audit-deps', valueOfInformation: 0.8, ... }
14
15// 2. Act: your agent dispatches the tool the move points to
16const audit = await runTool(move.subType)   // 'audit-deps' → your npm-audit runner
17
18// 3. Fold the result back in; it becomes the next observation
19await beliefs.after(JSON.stringify(audit), { tool: 'npm_audit', source: 'ci' })

The payoff is judgment, not just recall. A new CVE in that audit contradicts "no critical CVEs," and the engine flags the conflict instead of quietly overwriting the old claim. A RAG layer would hand the agent both strings and let the prompt sort them out. Here the conflict is a first-class object the agent has to address. Every belief traces back to the scan or test that produced it, so a reviewer can inspect why the agent thinks auth is covered before trusting that near the export flow. Replay the same observations and you rebuild the same picture.