AgentStateGraph is the state substrate underneath any agent or LLM application — content-addressed, branchable, and governable. Every feature native agent interactions require, in one primitive: provenance, memory, observability, policy, and audit.
state · intent · provenance · policy · taint · reminders · epochs · sessions
The case for a substrate
Every serious agent project rebuilds the same plumbing — where state lives, how to branch and compare speculative work, who changed what and why, how agents share memory and plans without clobbering each other. AgentStateGraph is that substrate, built once: the durable, queryable, tamper-evident record of what every agent did, why, on whose authority, and what it expected versus observed.
One authoritative, content-addressed record of every state change your agents make — not scattered across logs, traces, and chat transcripts.
Branch, speculate, delegate, and merge — the moves agents actually make. Intent, reasoning, and confidence are first-class, not afterthoughts.
Policy, signing, taint, and quarantine gate what agents can do. Accountability is enforced by construction — not by trusting a fleet to behave.
73 MCP tools, an HTTP API, eight language bindings, and four storage backends — from an in-browser tab to a multi-tenant Postgres cluster.
The complete feature set
Not a helper library and not a wrapper around old tools — a purpose-built substrate. Here is every capability ASG ships, grouped by what it does for your agents.
Every value is stored in an immutable, BLAKE3-hashed Merkle DAG. Identical state deduplicates automatically, and any tampering is detectable because the hash no longer matches. This is the same integrity model as Git — built for structured agent state, not text.
A commit is never just "what changed." Each carries an intent (why), reasoning (how the agent decided), confidence (0.0–1.0), agent_id, authority, and a resolution report — all queryable, none of it buried in a log line.
Explore, Refine, Fix, Rollback, Checkpoint, Merge, Migrate, Plan, and the taint/policy verbs give every change a machine-filterable classification — plus an open Custom variant for domain-specific semantics.
Ask blame /any/path and get the full chain: which agent set this value, when, under what intent and confidence, on whose authority, and what it superseded. The answer to "who did this and why" is one call, not a two-hour reconstruction.
Compose filters across the entire history — by agent, intent category, tag, authority principal, confidence range, free-text reasoning match, date window, or whether a change deviated from plan. Provenance becomes a database query.
When an agent finishes an intent it files a structured resolution: what was accomplished, which commits and branches it produced, the outcome, and every deviation from the original plan with its reason and impact. Expectation versus reality, recorded.
Agents don't run linear scripts — they explore state spaces. Create a branch to try an approach in isolation, compare it against the baseline, and keep or discard it. Programmatic-speed branching, designed for machines making dozens of attempts.
Spin up O(1) in-memory speculations that cost nothing to create and nothing to throw away. Run three approaches side by side, diff their outcomes, commit the winner with full reasoning, and discard the rest — all before anything touches durable storage.
Merges understand structure, not text. CRDT-inspired hints — sum, max, union-by-id — auto-resolve most concurrent edits, and genuine conflicts surface as machine-readable objects an agent can reason about instead of a diff full of <<<< markers.
Comparing two refs yields typed diff operations — set-value, add-key, remove-key — over the object tree, not a line-based text diff. Agents get a precise, programmatic view of exactly what changed between any two points.
Subscribe to a path pattern and receive reactive notifications as matching commits land. Agents and dashboards can respond to state changes the moment they happen instead of polling.
Materialize the commit DAG for visualization, or the intent-decomposition tree that shows how one high-level goal fanned out into sub-intents across a fleet of agents. The whole execution shape, reconstructable after the fact.
A durable session records a sub-agent's context: its working branch, the intent it was delegated, who it reports to, and its path or namespace scope. When an orchestrator spiders one goal into dozens of agent sessions, the entire tree persists instead of evaporating with the conversation.
Every change records who authorized it, with the full delegation lineage back to the originating principal. "The agent did it" is never the end of the trail — you can always follow the chain to the human or policy that permitted the action.
A shared plan/task primitive with a strict state machine (pending → in_progress → done), agent assignment, blockers, and priorities. Completion requires an attached Proof — a commit, file, test, or URL — so "done" means verifiable, not merely claimed.
A ref-layer isolation boundary that keeps projects and tenants fully separate within one store. Branches in different namespaces never collide, cross-namespace merges are denied by default, and any operation can override its namespace per call for multi-tenant deployments.
Group a bounded segment of work, then seal it into a tamper-evident bundle with a Merkle root hash. Sealed epochs export as self-contained, independently verifiable audit packages — hand one to a regulator and they can confirm nothing was altered.
Author rules that gate changes on authorization and cost-of-change. A proposed change is evaluated into an Allow, Deny, or RequireApproval decision, with fallback actions (continue, queue, defer, reject) for the approval path. Soft enforcement plus a complete audit trail of every decision.
Policies move through propose → ratify → supersede, each step a first-class commit. Ratified policies can be signed with Ed25519 over canonical JSON, so the rules governing your fleet are themselves tamper-evident and attributable.
The built-in selector DSL covers most rules, but you can plug in mature policy languages: an OPA/Rego evaluator ships today, with Cedar and sandboxed WASM runners on the same external-evaluator interface.
Mark a path as degraded, sensitive, or under review. Effects range from advisory Warn to hard Block, a Review gate that demands ≥0.9 confidence, or Isolate to hide a path from queries. Enforced by a pre-commit sweep that walks the path's ancestors.
Every taint, quarantine, and watch is itself a commit with full intent metadata — so the act of restricting access, and every rejected write attempt, is as blameable and queryable as any other change.
System metadata under /_meta/* is protected: writes require a migration intent, and a /_meta/_secret/* sub-prefix is gated on read and filtered out of listings and search — a built-in place to keep sensitive keys away from ordinary agent traffic.
A pull-based scheduler built for agents: nothing is pushed, agents call remind_me at natural checkpoints and receive what's due, ordered by priority. Supports one-off, interval, daily, and weekly schedules, with soft references to branches, plans, and tasks.
Reminders can be autonomous or require sign-off. A non-autonomous reminder parks in AwaitingPermission until a human approves it — a clean pattern for "wake me up to do X, but only if you say it's okay."
Your store carries a schema version in-band at /_meta/schema_version. The migrate framework offers a migration registry, startup introspection (up-to-date, upgrade-available, downgrade, corrupt), and dry-run/apply runners — with migrations recorded as ordinary commits, visible in log and blame.
Speak the Model Context Protocol over stdio and any MCP-capable agent — Claude, Cursor, custom orchestrators — gets the full surface immediately: state, branching, speculation, epochs, sessions, plans, policy, taint, and reminders as native tools.
Run with --http to expose the same operations as a CORS-enabled REST API. Health, stats, state, blame, query, diff, merge, epochs — reachable from a browser, a script, or any language without an MCP client.
The HTTP surface ships API-key authentication with per-key namespace scoping, key rotation and revocation endpoints, and built-in rate limiting — the essentials for exposing ASG to a fleet safely.
Rust is the reference implementation; Python, TypeScript, Go, .NET/C#, and Swift (macOS & iOS) ride the same core over a stable C ABI, plus a WASM build for the browser. A Python agent and a Go agent can write to the same repository and read each other's intent annotations.
One trait, four implementations: in-memory for tests and speculation, SQLite for single-node durability, Postgres for multi-tenant SaaS, and IndexedDB for agents running entirely in the browser. The schema is portable across all of them.
A WASM-powered interactive viewer for walking a state DAG, inspecting commits, and reading blame right in a browser tab — no backend required. Ideal for demos, debugging, and client-side prototypes.
Anatomy of a commit
A Git commit answers one: what changed. An AgentStateGraph commit — with its structured intent — records everything an accountable substrate has to capture when the actor is an agent.
Why it matters
Features are the how. These are the why — the properties an agent application has to guarantee before anyone will trust it in production, and the reason each one is non-negotiable.
You cannot operate what you cannot see. When an agent fleet is making thousands of decisions an hour, the difference between a controlled system and a runaway one is whether you can answer "what is happening right now, and what just happened?" in seconds rather than after a post-mortem.
In ASG: every change is a queryable commit; live watch subscriptions, stats, commit graphs, and intent trees turn agent activity into something you can actually inspect.
An agent that can't explain itself can't be trusted with anything that matters. Transparency means the reasoning behind a decision — the alternatives weighed, the confidence held, the plan followed — is a durable, inspectable record, not something trapped in an ephemeral context window that vanishes when the session ends.
In ASG: reasoning, confidence, considered alternatives, and deviation reports are captured on every commit — the decision, not just the outcome.
Agents that forget repeat their mistakes and lose the thread across sessions. Durable memory — persistent state, the branches explored, the plans in flight, and scheduled future work — is what lets an agent pick up where it (or another agent) left off, rather than starting cold every time.
In ASG: state persists in a durable store; sessions preserve delegated context; reminders carry future intent forward; and soft references link memories, plans, and branches together.
Trust in an autonomous system requires knowing where every change came from. Without provenance, "the AI did it" is where the investigation ends. With it, every value carries its full causal chain — who set it, from what prior state, under what authority, and why — so nothing in production is unexplained.
In ASG: content-addressing plus agent_id, authority, delegation chains, and blame give every value an unbroken, tamper-evident lineage.
Human systems are governed socially — code review, PRs, someone to ask in a Slack thread. A fleet of agents making low-confidence decisions at machine scale can't be. Accountability has to be mechanical: enforced by the substrate itself, so a change that lacks intent, authority, or approval simply cannot be recorded as legitimate.
In ASG: policy gating, required fields, Ed25519-signed rules, and taint enforcement make accountability a property of the system, not a matter of good behavior.
When a regulator, a customer, or your own security team asks "show me every agent change to billing last quarter, who authorized it, and prove nothing was altered," the answer has to be a report you can generate on demand — not a two-week forensics project against logs that may have already rotated away.
In ASG: sealable epochs produce tamper-evident, independently verifiable audit bundles; unified query turns any compliance question into a single filter.
Debugging a non-deterministic system is impossible if you can't reconstruct the state it acted on. Reproducibility means you can return to the exact point an agent made a decision, see precisely what it saw, and replay the branch — the foundation for root-causing incidents and validating fixes.
In ASG: immutable content-addressed history means every commit is an exact, restorable snapshot; branches and speculations let you replay any decision path.
Autonomy without limits is a liability. Governance is the ability to draw hard lines — this agent may touch these paths, this class of change needs approval, this tenant is isolated from that one — and have those lines hold at machine speed, across every actor, without a human in the loop for each decision.
In ASG: namespaces isolate tenants, policies bound what changes are permissible, taint quarantines sensitive paths, and sessions scope each agent to exactly the surface it needs.
Use it from anywhere
The Rust core is the single source of truth for behavior. Every binding rides the same engine and the same commit format — write from one language, read from another. Registry packages aren't published yet — clone the repo and build from source (each guide has the full steps).
cargo add --git https://github.com/agentstatelabs/AgentStateGraph agentstategraphcd bindings/python && maturin develop --releasecd bindings/typescript && npm install && npm run buildgo get github.com/agentstatelabs/AgentStateGraph/bindings/godotnet build bindings/dotnet/AgentStateGraph.package(url: "…/AgentStateGraph.git", from: "1.0.0")wasm-pack build crates/agentstategraph-wasm --target webcargo build -p agentstategraph-ffi --releaseStore it anywhere
Pick a backend by deployment shape, not by rewriting your app — every implementation sits behind the same storage trait and shares a portable schema.
Get started
One binary is the MCP server, the HTTP API, and the migration CLI. Point an agent at it and start recording.
Clear on scope
AgentStateGraph is a state primitive: the layer a next-generation IaC tool, GitOps tool, or agent-native ops platform is built on. That means it is deliberately not a few things.
StateGraph is an in-process dict inside one agent's run. ASG is a persistent, content-addressed substrate used between and above agents.License
A substrate has to be trustable infrastructure. AgentStateGraph is dual-licensed under MIT OR Apache-2.0 — genuinely open, with no usage restrictions, no conversion clock, and no fine print. Build on it in anything.
Because nobody builds their agent's state layer on infrastructure with a licensing asterisk. An open core removes that risk entirely — you can depend on ASG, fork it, ship it, and never revisit the license. That trust is what lets a primitive become infrastructure.
The open core is the whole engine — free, forever. For teams that want more, managed hosting, enterprise features, and commercial support are available on top of it. Talk to us about a plan that fits. That's how the project is funded — by adding value above the core, never by restricting it.
See it in action
ASG is the substrate; a growing family of applications and services are built on it. Each is a working example of what native agent state looks like in practice.
The substrate itself — content-addressed, branchable, governable agent state, with 73 MCP tools and eight language bindings.
An agentic context engine and memory layer for AI agents — durable memory, plans, branches, and provenance across every tool — built on AgentStateGraph.
A code-level context and audit overlay for agent-authored code — a decision ledger, effect declarations, and a call graph for every function, queryable by the agents writing the code and checked into git.
AI chat with branchable conversations, multimodal input, tool calling, and MCP — using ASG to branch, blame, and persist every thread.