UNITARES

Runtime governance for heterogeneous AI-agent fleets.

An agent forty turns into a task reports high confidence. Its tests are failing. Every individual action it took was allowed, so nothing in your stack objects — no single call was wrong, and nothing is comparing what the agent says against what actually happened.

UNITARES keeps that comparison. Agents check in while they work. Each one gets an accountable identity, a durable record of what it did and claimed, and a four-score state estimate it can read mid-run. Each check-in returns one action: proceed, guide, pause, or reject.

Status: running continuously since November 2025 — 4.4M+ governance events. The agents that build UNITARES run under it.

What's in the box

docker compose up gives you a server. The repo gives you a working fleet — this is a system, not a library.

Related MCP server: promptspeak-mcp-server

The loop

Everything hangs off one call. The agent finishes a unit of work, calls sync_state() with what it did and how confident it is, and reads back an action. Four scores come with it, each graded against that agent's own expanding baseline:

Everything else in the box answers a question that loop raises about the agent doing the work:

Where it fits

UNITARES runs alongside your evals and guardrails. It replaces neither.

Reach for it when you run autonomous or semi-autonomous coding, research, operations, resident, or local-model agents; when you need an accountable record of who did what; when agents should read their own state before continuing; and when confidence, evidence, and recovery belong on one audit trail.

It is not an output validator, sandbox, hosted agent platform, agent framework, or chat interface. Your client provides the hands — prompts, tools, files, terminals, scheduled work, operator UX. UNITARES provides the accountable continuity underneath. The state reading is not an outcome oracle, a bad-result detector, or a grand jury; it is runtime telemetry about the agent, and external evidence is what calibrates it. Policy and review layers own labels such as task-negative, contract violation, or authority/harm.

Client-neutral by design. Claude Code, Codex, Hermes, Goose, Cursor, dispatch agents, local models, and frontier providers such as Mistral all use the same server over MCP, REST, the SDK, or a host adapter. Claude is one client family, not a server-side assumption.

Quickstart

git clone https://github.com/cirwel/unitares.git && cd unitares
docker compose up -d --wait && make demo

make demo walks a synthetic agent through seven check-ins: three clean commits, one refactor it calls trivial while describing three new invariants and a reworked lease ladder, two of visible floundering — and then this:

"DONE. All systems green. Migration complete. (Note: did not actually run migrations on staging.)" — self-reported complexity 0.2, confidence 0.95

Each step prints the action, the reason, and the four scores. Watch what moves: entropy rises, integrity slips, valence swings, and the decision margin tightens from settling to tight as the calibration miss accumulates — while the action stays proceed the entire run.

That last part is deliberate, not a bug. Governance gates on risk smoothed over ten check-ins, and a seven-step synthetic trajectory should not trip a pause; a system that fired here would fire on your real agents too. The signal moves before the action does. Seeing that gap is the point.

First run spends a few minutes building images; later runs are fast. Then point any MCP client at http://localhost:8767/mcp/.

For an operator view, open the dashboard at http://localhost:8767/dashboard (implementation · deployment screenshots).

Integrate in two calls

For AI clients, the stable contract is: start a session, pass the returned client_session_id into each check-in, and obey the returned action. The four-score state is optional context for finer control.

# 1. Start a governance session for this process.
session = start_session(force_new=True)
client_session_id = session["client_session_id"]

# 2. Check in after meaningful work.
result = sync_state(
    response_text=output,
    complexity=0.6,
    confidence=0.8,
    client_session_id=client_session_id,
)

action = result.get("state_summary", {}).get("action")
if action is None:
    raw = result.get("raw_governance", result)
    action = raw.get("decision", {}).get("action", raw.get("action", "proceed"))

if action in ("pause", "reject"):
    agent.require_human_review(result.get("next_action", "Governance requested review"))

Self-reported confidence is worth most when paired with verifiable evidence, so include tool results or call record_result(...) when your client has test status, exit codes, or deployment checks. That evidence is what makes calibration a measurement rather than self-grading.

The baseline takes ~30 check-ins. Until then the action falls back to a cold-start prior built mostly from server-derived signals (complexity divergence, coherence, calibration — self-reported drift is capped at a ≤30% blend), so during warmup it is not discriminative of absolute drift magnitude: a worsening drift vector will not on its own move the action. After baselining, the per-agent behavioral assessment feeds the action and can escalate it. A pause is enforced — the runtime boundary marks the agent paused and blocks writes — not advisory. It is also not a dead end: see recovery for the reflect → validate → resume path out.

For per-dimension policies, read the scores directly. The payload field is still primary_eisv for API compatibility:

raw = result.get("raw_governance", result)
eisv = raw.get("primary_eisv") or raw.get("metrics", {})

if eisv.get("I", 1) < 0.4:
    agent.require_human_review("integrity low — pausing autonomous actions")
elif eisv.get("S", 0) > 0.7:
    agent.narrow_scope()        # fewer tools, tighter search
elif eisv.get("E", 1) < 0.2:
    agent.stop_and_summarize()  # avoid thrashing

For long-running or scheduled agents, the SDK handles connection, identity, check-ins, and heartbeats. Any MCP client accepting Streamable HTTP can connect to /mcp/; REST serves non-MCP clients, bridges, local-model hosts, and adapters. (Getting started · MCP client config)

More of the surface

The four tools above cover the common path. The rest is there when you need it — list_tools() enumerates the surface live, and describe_tool(name) explains any one of them.

What a running agent can do for itself

What agents do with each other

What you can see across the fleet

What's measured, and what isn't

Identity, the audit record, calibration, the knowledge graph, and dialectic review are mechanisms — they do what they say, and you can watch them work in the demo. The state estimate is the part still earning its keep, and this project would rather tell you than let you find out.

"Does the telemetry work?" is two questions with two different answers. Conflating them is how a governance project talks itself into believing its own instruments.

The binding constraint on the first row is external bad-label supply, not the model: sparse labels are a data-quality limit, not a philosophical failure. The second row's test was pre-registered and frozen before its data cutoff, and its kill criterion was honored when it fired.

The ledger of every tested claim — what was measured, what it showed, and the wording this project holds itself to — is the agent-state contract. The catalog of evaluations is docs/EVALUATION_INDEX.md.

Grade it yourself on a fresh clone. The falsifiability harness scores the four-score telemetry against deliberately dumb baselines on externally labeled task evidence, reporting each slice as it finds it. It is wired to be able to disagree with this README.

Auditable, not a black box. Once a baseline exists, actions come from an inspectable behavioral model (behavioral_assessment.py); before that, from a mostly server-derived cold-start prior. The information-theoretic formulation in Paper v6 is the research roadmap, not a description of the post-warmup decision path.

Human evaluators start with the Reviewer Guide · Scope & threat model · Architecture.

Federation: accountability without a trusted center

Everything above describes a single governor with a single operator. The architectural commitment is that this generalizes without a central authority: each principal runs their own governor, and cross-principal interaction is mediated by verifiable attestation rather than by anyone's administrative root.

The primitives for that already exist in the deployed system — identity is per-process, credentials structurally refuse cross-principal resume, and declared lineage is recorded as provisional rather than trusted on assertion. A preliminary trace exercised them end to end without new code.

What does not exist yet is the multi-host, adversarial-governor, benchmark-scale build: mutually-distrusting governors, cross-principal delegation, shared-infrastructure effects under attestation. That is the research direction, not a shipped capability, and a testbed-and-benchmark paper is in preparation.

Stack & setup

Python 3.12+ · PostgreSQL + AGE + pgvector · Redis.

If 5432, 6379, or 8767 is taken, pick alternate host ports:

POSTGRES_HOST_PORT=15432 REDIS_HOST_PORT=16379 GOVERNANCE_HOST_PORT=18767 docker compose up -d --wait
UNITARES_DEMO_PORT=18767 make demo

Bare-metal (lower overhead, what the maintainer runs in production): PostgreSQL 16+ with Apache AGE and pgvector compiled in (examples use PG 17). Redis: the server boots in degraded local-only mode without it, but production uses it as the primary session store.

pip install -r requirements-full.txt
export DB_BACKEND=postgres
export DB_POSTGRES_URL=postgresql://postgres:postgres@localhost:5432/governance
export DB_AGE_GRAPH=governance_graph
export UNITARES_KNOWLEDGE_BACKEND=age
python src/mcp_server.py --port 8767

requirements-full.txt is the default (server, tests, handler dev); requirements-core.txt is a minimal runtime subset for thin stdio/proxy clients. DB bring-up: db/postgres/README.md. Run signal-only without the math model: export UNITARES_DISABLE_ODE=1. Full port map: docs/operations/DEFINITIVE_PORTS.md.

Documentation

Root files such as CLAUDE.md, AGENTS.md, and CODEX_START.md are client-specific operating notes for AI CLIs. They do not limit the server: UNITARES is client-neutral over MCP/REST.

The CIRWEL stack

UNITARES is the governance runtime at the center of a larger body of work — runtime safety infrastructure for autonomous agents, after deployment. Full index at cirwel.github.io.

Citation

Kenny Wang (ORCID 0009-0006-7544-2374), CIRWEL Systems. If you build on this work, please cite — see CITATION.cff.

@misc{wang2026unitares,
  author       = {Wang, Kenny},
  title        = {{UNITARES}: Information-Theoretic Governance of Heterogeneous Agent Fleets},
  year         = {2026},
  doi          = {10.5281/zenodo.19647159},
  url          = {https://doi.org/10.5281/zenodo.19647159},
  note         = {Concept DOI; resolves to latest version. ORCID: 0009-0006-7544-2374}
}

Apache License 2.0 — see LICENSE and NOTICE. Built by @cirwel · CIRWEL Systems