AgentStateGraph

The canonical state-and-memory substrate for AI agents — the surface any agentic app should be built on.

Website: agentstategraph.dev Disambiguation: AgentStateGraph vs. Stategraph vs. LangGraph's StateGraph

The agent-building surface

Every serious agentic application re-invents the same plumbing: where does agent state live, how do you branch and compare speculative work, how do you know who changed what and why, how do multiple agents share plans and memory without clobbering each other, and how do you govern low-confidence decisions at scale. AgentStateGraph is that layer, built once, done right — a content-addressed, branchable, blameable state primitive with AI agents as the primary actor. If you're building an agent, a multi-agent system, or an agent-native tool, this is the substrate you should be standing on instead of rebuilding.

It is deliberately not an application and not a framework you have to adopt wholesale. It's a primitive — the layer a next-generation IaC tool, a GitOps tool, an agent memory system (see CTXone), or your own product can all be built on. Every change it records carries why, who authorized it, what alternatives existed, and what the agent expected vs. observed — across every branch, forever.

Why build on it

• Git-like semantics for state, not text — content-addressed Merkle DAG, O(1) speculative branching, schema-aware (CRDT-inspired) merge, instant discard. Agents explore state spaces; this is the primitive that lets them.
• Every commit is accountable — structured intent, reasoning, confidence, agent id, authority/delegation chain, and expected-vs-observed resolution. Governance is mechanical, not social.
• Batteries for real agent systems — shared plans & tasks (state machine + proofs + assignment), pull-based reminders, policy + taint/quarantine gating, epochs (tamper-evident audit bundles), and blame/query across all of it.
• Connect anything — MCP tools work with any MCP agent, plus an HTTP REST API and a browser explorer.
• Embed anywhere — language bindings for Rust, Python, TypeScript, Go, Swift, .NET/C#, WASM, and C FFI, over pluggable storage backends (Memory, SQLite, Postgres, IndexedDB) — with more of both on the way.
• Multi-agent by design — scoped sessions, delegation, and intent trees, with namespaces giving each project its own branches in a shared store.

This is what the substrate has to look like when the primary actor touching production systems is no longer a human who can be governed socially (via PRs, code review, Slack threads) but a fleet of agents that must be governed mechanically.

Quick Start

One-line install (Mac / Linux)

curl -sSL https://agentstategraph.dev/install.sh | sh

Detects your platform, downloads the prebuilt binary, installs to ~/.local/bin. Then:

agentstategraph-mcp --http --port 3001
curl http://localhost:3001/api/health

Docker

docker run -p 127.0.0.1:3001:3001 ghcr.io/agentstatelabs/agentstategraph --http
# Or with persistent storage:
docker compose up -d
curl http://localhost:3001/api/health

These publish the port on 127.0.0.1, so only your machine can reach it. Anything that can reach the port can read and write the store. To serve other machines, publish it on all interfaces and turn on auth:

export ASG_ADMIN_KEY=asg_$(openssl rand -hex 32)   # keep this; it's the admin key
docker run -p 3001:3001 -v asg-data:/data -e ASG_INITIAL_ADMIN_KEY="$ASG_ADMIN_KEY" \
  ghcr.io/agentstatelabs/agentstategraph \
  --http --auth --keys-file /data/keys.json --path /data/agentstategraph.db
curl -H "Authorization: Bearer $ASG_ADMIN_KEY" http://localhost:3001/api/stats/main

As an MCP Server (connect to Claude Code, GPT, any MCP agent)

# If installed via the install script:
agentstategraph-mcp

# Or build from source:
git clone https://github.com/agentstatelabs/agentstategraph.git
cd AgentStateGraph
cargo build --release -p agentstategraph-mcp
cargo run --release -p agentstategraph-mcp

Add to your Claude Code MCP config:

{
  "mcpServers": {
    "agentstategraph": {
      "command": "/path/to/AgentStateGraph/target/release/agentstategraph-mcp"
    }
  }
}

As an HTTP REST API

cargo run --release -p agentstategraph-mcp -- --http --port 3001

curl http://localhost:3001/api/health
curl http://localhost:3001/api/stats/main
curl http://localhost:3001/api/state/main?path=/
curl "http://localhost:3001/api/blame/main?path=/cluster/name"

A REST API for scripts and any HTTP client. Browser pages served from localhost can call it too; allow another origin with --cors-origin. See --help for the full endpoint list.

As a Rust Library

use agentstategraph::{Repository, CommitOptions};
use agentstategraph_storage::SqliteStorage;
use agentstategraph_core::{IntentCategory, Object};

let storage = SqliteStorage::open("./state.db").unwrap();
let repo = Repository::new(Box::new(storage));
repo.init().unwrap();

// Every write is an atomic commit with intent
repo.set("main", "/cluster/name", &Object::string("prod"),
    CommitOptions::new("agent/setup", IntentCategory::Checkpoint, "init")
        .with_reasoning("Production cluster for ML training")
        .with_confidence(0.95));

// Branch, explore, merge
repo.branch("explore/new-network", "main").unwrap();
repo.diff("main", "explore/new-network").unwrap();
repo.merge("explore/new-network", "main",
    CommitOptions::new("agent/planner", IntentCategory::Merge, "Adopt new layout")).unwrap();

// Full audit trail
repo.log("main", 10).unwrap();
repo.blame("main", "/cluster/name").unwrap();

From Python

Install as agentstategraph (PyPI); the import module is agentstategraph_py.

from agentstategraph_py import AgentStateGraph

asg = AgentStateGraph("state.db")
asg.set("/name", "prod", "init", category="Checkpoint")
asg.branch("feature")
asg.merge("feature", description="Adopt feature")
asg.blame("/name")  # who changed it and why

From Swift

Add the repository directly with SwiftPM (available from v0.9.17):

.package(
    url: "https://github.com/agentstatelabs/agentstategraph.git",
    from: "0.9.17"
)

The checksum-pinned XCFramework includes macOS arm64/x86_64, iOS device arm64, and iOS Simulator arm64/x86_64 slices.

From TypeScript, Go, .NET / C#, or WASM — all supported.

Features

• 77 MCP tools — any agent can connect immediately
• HTTP REST API — --http mode for scripts, and for browser pages on localhost or origins you allow
• Browser explorer — interactive data viewer at agentstategraph.dev/explorer/
• 8 language bindings — Rust, Python, TypeScript, Go, Swift, .NET / C#, WASM, C FFI
• 4 storage backends — Memory, SQLite, Postgres (tenants partitioned in a shared database, with TLS), IndexedDB (browser)
• 15 crates — modular core, storage, MCP, policy (+ pluggable Rego / Cedar / WASM evaluators), taint, tasks, reminders, migrate, FFI, and WASM
• Namespaces — a separate set of branches per project in one store. They partition branches but aren't a security boundary; an API key bound to a namespace confines a client to it
• Reminders — pull-based scheduling with priority, recurrence, and approval gating
• Taint & quarantine — agentstategraph-taint mark-and-sweep enforced at commit time
• Content-addressed Merkle DAG — immutable, deduplicated history
• Structured intent metadata — category, description, tags, reasoning, confidence
• 19 intent categories — Explore, Refine, Fix, Rollback, Checkpoint, Merge, Migrate, Plan, Taint, Untaint, Quarantine, Unquarantine, Watch, Unwatch, PolicyPropose, PolicyRatify, PolicySupersede, PolicySign, plus Custom
• Authority & delegation chains — who authorized what, with full chain
• Schema-aware merge — CRDT-inspired conflict resolution (sum, max, union-by-id)
• Speculative execution — O(1) branching, instant discard
• Multi-agent orchestration — scoped sessions, delegation, intent trees
• Plans & tasks — shared agentstategraph-tasks primitive with state machine, proofs, blockers, agent assignment
• Policy — agentstategraph-policy primitive for authorization + cost-of-change gating with fallback actions. Advisory: you evaluate a change and act on the decision; MCP commit_spec gates speculation promotion on it, refusing by default a flagged change (a deletion, say) that no policy covers
• Schema-evolution framework — guard + crate + CLI

What Makes Every Commit Different from Git

Field	Question it answers
state_root	What changed?
intent	Why? (structured, queryable)
reasoning	How did the agent decide?
confidence	How sure was it? (0.0–1.0)
agent_id	Who did it?
authority	Who authorized it? (with delegation chain)
resolution	What was accomplished? Any deviations?
notification	Who was informed?
tool_calls	What actions produced this?

Architecture Eras

AgentStateGraph sits at the bottom of a new architecture era. Prior eras had their own primitives; this one needs its own too.

Era	Unit of Work	Key Primitives
Monolithic	Function call	OS, filesystem, local DB
Batch / Request-Response	Request → Response	HTTP, REST, SQL, queues
Streaming	Event	Kafka, Flink, event stores, CQRS
Intent-based	Intent → Outcome	AgentStateGraph

Agents don't execute linear scripts — they explore state spaces. They need a primitive that supports speculative branching, comparison, and merge with full reasoning history. Git is text-oriented. Databases lack branching. Event sourcing is append-only. AgentStateGraph fills the gap.

Architecture

AgentStateGraph/
├── crates/
│   ├── agentstategraph-core/     # Types, diff, merge, schema — zero I/O
│   ├── agentstategraph-storage/  # Pluggable backends (memory, SQLite, Postgres, IndexedDB)
│   ├── agentstategraph/          # High-level Repository API
│   ├── agentstategraph-mcp/      # MCP server (77 tools over stdio) + HTTP + migrate CLI
│   ├── agentstategraph-tasks/    # Shared Plan/Task store — state machine, proofs, assignment
│   ├── agentstategraph-reminders/# Pull-based reminder scheduling with approval gating
│   ├── agentstategraph-policy/   # Authorization + cost-of-change gating with fallback actions
│   ├── agentstategraph-policy-sign/ # Ed25519 signing for policy ratification (Rust + MCP server; not yet exposed through the C ABI)
│   ├── agentstategraph-policy-rego/ # OPA/Rego external evaluator
│   ├── agentstategraph-policy-cedar/# Cedar external evaluator (shells to the `cedar` CLI)
│   ├── agentstategraph-policy-wasm/ # WASM host runner for policy evaluation (wasmtime)
│   ├── agentstategraph-taint/    # Taint/quarantine/watch mark-and-sweep primitive
│   ├── agentstategraph-migrate/  # Schema-evolution framework + migration registry
│   ├── agentstategraph-ffi/      # C ABI for language bindings
│   └── agentstategraph-wasm/     # Browser/Deno WASM build
├── bindings/
│   ├── python/                   # PyO3 + maturin
│   ├── typescript/               # napi-rs
│   ├── go/                       # CGo via FFI
│   ├── swift/                    # SwiftPM + XCFramework for macOS and iOS
│   └── dotnet/                   # .NET / C# via P/Invoke over the C ABI
├── spec/
│   ├── AGENTSTATEGRAPH-RFC.md    # Full specification (~2300 lines)
│   ├── UPGRADE-PATH.md           # Schema versioning + migration design
│   ├── PERSISTENCE_SPEC.md       # Storage-backend design
│   └── TAINT_SPEC.md             # Taint/quarantine/watch design
├── examples/                     # reference implementations + feature walkthroughs
└── site/                         # agentstategraph.dev (Astro Starlight)

Plans & Tasks

agentstategraph-tasks is an opinionated sibling crate that layers a shared plan / task model on top of the raw state graph so multiple consumers don't each reimplement Task independently.

• Plan → Task[] with a strict state machine: pending → in_progress → done.
• Task::assigned_to for agent assignment, plus TaskStore::assign_task, unassign_task, next_task_for(agent).
• list_plans_by_status(status) for native status filtering.
• Proof and Verifier trait — completion of a task must produce verifiable evidence before it can transition to done.
• Repository::spec_set_json on the high-level API supports atomic multi-path plan/task commits.
• Plan-related writes are natively filterable via IntentCategory::Plan in log and blame queries.

The crate is optional — ignore it if your agents don't need a shared plan primitive. If they do, use agentstategraph_tasks::*; and you inherit the state machine.

Upgrade path

ASG databases have a schema version that lives in-band at /_meta/schema_version. Migrations are regular commits on main with IntentCategory::Migrate, so upgrade history shows up in log and blame for free.

• Guarded reserved path: /_meta/* writes require IntentCategory::Migrate — accidental overwrites from app code fail with RepoError::ReservedPath.
• /_meta/_secret/* sub-prefix is additionally gated on reads via Repository::get_with_intent, and silently filtered out of list_paths / search_values.
• Repository::init() stamps the current schema version on a new database. An older database missing the key is treated as implicit "version 0" and upgraded by the first migration that runs.
• agentstategraph-migrate crate provides a Migration trait, a Registry, a check() function for startup introspection (UpToDate / UpgradeAvailable / Downgrade / Unversioned / Corrupt), and a Runner with DryRun and Apply modes.
• agentstategraph-mcp migrate CLI is a one-shot maintenance command that refuses to start the MCP/HTTP surface — run it, let it report DryRun output, then run it again with --yes. Exit codes follow the sysexits.h spirit (64 / 65 / 70 / 75) so ops tooling can react programmatically.

# Dry-run against a production database
agentstategraph-mcp migrate --db ./prod.db --dry-run

# Apply
agentstategraph-mcp migrate --db ./prod.db --yes

# Check a specific ref or target version
agentstategraph-mcp migrate --db ./prod.db --ref main --to 0.4.0 --dry-run

Full design discussion: spec/UPGRADE-PATH.md — versioning model, migration registry, consumer-side upgrade flow, downgrade / rollback semantics, and the first shipped migration (a legacy plan_assignments sidecar → native Task.assigned_to) as a worked example.

Reference Implementations

cargo run --example getting_started -p agentstategraph    # Basic ops
cargo run --example agent_workflow -p agentstategraph     # Speculate, compare, pick winner
cargo run --example multi_agent -p agentstategraph        # Orchestrator + sub-agents
cargo run --example schema_merge -p agentstategraph       # Schema validation + merge
cargo run --example epochs_audit -p agentstategraph       # Epochs, blame, query
cargo run --example namespaces -p agentstategraph         # Namespaces: per-project branches
python3 examples/python_agent.py                          # Python workflow (after `maturin develop` in bindings/python)
(cd bindings/typescript && npm install && npm run build && node ../../examples/typescript_agent.ts)  # TypeScript workflow

MCP tool-call walkthroughs for the newer capabilities (work with any MCP-connected agent):

• examples/namespaces-multitenant.md — per-project branches in one store, and what namespaces don't separate
• examples/governance-policy-taint.md — policy + taint gating a sensitive change
• examples/reminders-and-tasks.md — pull-based reminders driving a task plan

Specification

See spec/AGENTSTATEGRAPH-RFC.md for the complete RFC covering core data model, intent lifecycle, authority/delegation, resolution reporting, sub-agent orchestration, schema system, epochs/registry, MCP interface, and architecture.

Links

• Website: agentstategraph.dev
• Explorer: agentstategraph.dev/explorer/ — interactive data viewer
• Disambiguation: AgentStateGraph vs. Stategraph vs. LangGraph's StateGraph
• RFC Spec: AGENTSTATEGRAPH-RFC.md

License — MIT OR Apache-2.0

AgentStateGraph is dual-licensed under either of:

• MIT License (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option — the standard permissive dual-license used across the Rust ecosystem.

What this means in practice:

• Use it anywhere — internal tools, production systems, commercial and closed-source products, and hosted or managed services — with no fee and no separate commercial license.
• Pick either license. MIT for simplicity, or Apache-2.0 for its explicit patent grant. You satisfy whichever you prefer, not both.
• Permanent. No usage restriction, no conversion clock, no relicensing clause. What's open stays open.

The project earlier shipped under BSL 1.1 (v0.3.5-beta.2 through v0.9.6); it has since returned to MIT OR Apache-2.0, and that grant also covers those prior releases. See LICENSING.md for the full terms and license history.