activegraph 1.0.0rc2

An event-sourced reactive graph runtime for long-running, auditable, agentic systems.

Active Graph

The graph is the world. Behaviors are physics. The trace is the proof.

An event-sourced reactive graph runtime for long-running, auditable, agentic systems. Behaviors react to a shared graph instead of talking to each other. Every change is traceable. Every run is resumable, forkable, and diff-able from its event log.

If chat-based agents are a group conversation, Active Graph is a shared workspace where everyone can see what changed, who changed it, and why.

Try it in 30 seconds

pip install activegraph
activegraph quickstart

The bundled Diligence pack runs against recorded fixtures: no API key, no configuration, byte-deterministic output. You see what the framework does before you read about how it does it.

Then walk the 10-minute tutorial:

activegraph quickstart --interactive

It scaffolds a behavior, runs it against the same fixtures, and ends with the fork-and-diff workflow — the framework's most differentiated capability.

Install

pip install activegraph                    # core runtime + SQLite store + Diligence pack
pip install "activegraph[llm]"             # Anthropic provider
pip install "activegraph[postgres]"        # Postgres-backed event store
pip install "activegraph[prometheus]"      # Prometheus metrics
pip install "activegraph[all]"             # everything

Python 3.11+. Two hard dependencies (click for the CLI, pydantic for the pack format); persistence backends and provider integrations are opt-in extras.

What you get

• Event-sourced graph runtime. Objects + typed relations + an append-only event log. Every mutation is an event; the trace is the audit trail.
• Reactive behaviors as first-class. Function, class, LLM-backed, or attached to typed edges (the relation-behavior primitive — edges with logic). Subscriptions are event type + predicate + a Cypher subset for graph-shape patterns.
• Fork-and-diff. Branch any run at any event into an independent fork, configure it differently, and structurally diff the result against the parent. Cache replay means the shared prefix doesn't re-execute (no new LLM calls). Most agent frameworks can't do this.
• Packs. A pack bundles object types, behaviors, tools, prompts, and policies for a specific domain. The bundled Diligence pack is the reference: 8 object types, 7 behaviors, 3 tools, recorded fixtures.
• Per-error reference pages. Every error message ends with a More: link to a page that explains when it fires, why, and how to fix it. Catalog at docs.activegraph.dev/reference/errors.

A small example

The relation-behavior primitive — coordination logic on the edge, not on either endpoint:

from activegraph import Graph, Runtime, behavior, relation_behavior

graph = Graph()
runtime = Runtime(graph, budget={"max_events": 200, "max_seconds": 60})

@behavior(name="planner", on=["goal.created"])
def planner(event, graph, ctx):
    research = graph.add_object("task", {"title": "Research", "status": "open"})
    memo = graph.add_object("task", {"title": "Draft memo", "status": "blocked"})
    graph.add_relation(research.id, memo.id, "depends_on")

@behavior(name="researcher", on=["object.created"], where={"object.type": "task"})
def researcher(event, graph, ctx):
    task = event.payload["object"]
    if task["data"]["status"] != "open" or "Research" not in task["data"]["title"]:
        return
    graph.add_object("claim", {"text": "Market early but growing.", "confidence": 0.7})
    graph.emit("task.completed", {"task_id": task["id"]})

@relation_behavior(name="unblock", relation_type="depends_on", on=["task.completed"])
def unblock(relation, event, graph, ctx):
    if event.payload["task_id"] == relation.source:
        graph.patch_object(relation.target, {"status": "open"})

runtime.run_goal("Evaluate this startup idea")
runtime.print_trace()

The unblock relation behavior fires only for events touching one of its edge endpoints. The conceptual deep-dive on edges-with-logic is in docs/concepts/relations.md.

Documentation

• docs.activegraph.dev — full doc site: concepts, guides, cookbook, CLI reference, API reference, the per-error catalog.
• 10-minute tutorial — install to a working custom behavior, including fork-and-diff.
• CHANGELOG.md — every release, with per-version migration notes.
• CONTRACT.md — locked design decisions, version by version. Useful when you want to know why something is the way it is.
• examples/ — runnable end-to-end demos: diligence_real_run.py, resume_and_fork.py, llm_claim_extraction.py, diligence_with_tools.py, operate_a_run.py.

What this is not

• Not a chat framework. If your problem fits in one conversation, use a chat framework.
• Not a workflow engine. Workflows model control flow. This models world state.
• Not a rules engine, exactly. Rules engines forward-chain over facts. This event-sources over a graph and supports LLM behaviors as first-class.
• Not a production graph database. The default store is SQLite, optionally Postgres. For a high-throughput graph backend, plug one in behind the EventStore protocol.
• Not magic. Bad behaviors produce bad graphs. The runtime makes the badness inspectable, not absent.

Status

v1.0-rc1 (2026-05). v1.0 final ships after the first-time-user gate per CONTRACT v1.0 #C4. See CHANGELOG.md for the full v0 → v1.0 history and per-version migration notes.

Major shipped milestones:

• v1.0 (rc1) — error hierarchy rewrite with per-error reference pages, doc site at docs.activegraph.dev, activegraph quickstart command, mypy --strict and docstring coverage CI gates.
• v0.9 — pack format and the Diligence reference pack (8 object types, 7 behaviors, 3 tools, recorded fixtures).
• v0.8 — operator surface: structured logging, Prometheus metrics, runtime.status(), full activegraph CLI, PostgresEventStore.
• v0.7 — @tool decorator, Cypher-subset pattern subscriptions, temporal predicates.
• v0.6 — @llm_behavior with structured output, frame-aware prompt construction, cost accounting.
• v0.5 — full event-log persistence, save/load across processes, fork from any historical event, structural diff between runs.
• v0 — core runtime: graph, behaviors, relation behaviors, patches with optimistic concurrency, views, frames, policies, budgets, the trace.

Roadmap items planned for v1.1 are tracked in CONTRACT.md § v1.1.

License

MIT.

Contributing

The core runtime stays small and sharp. Contributions to packs, backends, and LLM integrations are especially welcome. Open an issue before large changes — the abstractions are still settling.

Test discipline: tests must remain deterministic. No live network calls in CI. LLM and tool tests use recorded fixtures (RecordedLLMProvider, RecordedToolProvider). If a contribution adds a test that would only pass with a live API key or live HTTP, it cannot land.

---

The graph is the world. Behaviors are physics. The trace is the proof.