ActiveGraph

Event-sourced reactive graph runtime for auditable, forkable agentic systems.

ActiveGraph turns the execution of an AI agent into a structured, inspectable, replayable record. Every LLM call, tool invocation, and decision flows through an append-only event log that projects into a live graph — with full causal lineage.

Install

npm install activegraph

# Optional peer dependencies (installed as needed):
npm install better-sqlite3        # faster SQLite persistence (JSONL works with zero native deps)
npm install @anthropic-ai/sdk     # Anthropic provider
npm install openai                # OpenAI provider

Requires Node.js >= 20.

Two ways to use it

1. Observability — capture an existing agent (zero code changes)

The LLM API call is the universal chokepoint. Point any agent at the local proxy and every request/response becomes an event:

activegraph wrap --persist ./trace.jsonl -- claude "fix the bug"
# → Captured 12 LLM calls, 5 tool calls, 45000 tokens, ~$0.18
activegraph inspect ./trace.jsonl

Or in code:

import { ActiveGraphProxy } from 'activegraph/adapters';

const proxy = new ActiveGraphProxy({ persistTo: './trace.jsonl' });
const { url } = await proxy.start();
process.env.ANTHROPIC_BASE_URL = url; // the only change
// ...run your agent...
await proxy.stop();
console.log(proxy.costSummary());

2. Framework — build an event-driven agent

import { Graph, Runtime, behavior, clearRegistry } from 'activegraph';

clearRegistry();
behavior({ name: 'planner', on: ['goal.created'] })((event, graph) => {
  graph.addObject('task', { title: 'Research', status: 'open' });
});

const runtime = new Runtime(new Graph(), { budget: { maxEvents: 200 } });
await runtime.runGoal('Evaluate this startup idea');
await runtime.printTrace();

Once captured, everything works

• Trace — human-readable causal event log
• Resume — recover a crashed run from its log (EventLog.resume)
• Fork & Diff — branch at any point, compare outcomes
• Cost tracking — token usage and spend per call

Adoption levels

| Level | Method | Code changes | | --- | --- | --- | | 1 | activegraph wrap CLI | none | | 2 | ActiveGraphProxy + env var | none | | 3 | wrapLLMClient | wrap your client once | | 4 | createCallbacks (LangChain, Vercel AI SDK) | hook callbacks | | 5 | createAgentTracer | explicit spans | | 6 | Runtime + behavior | full framework |

Documentation

Full docs are in docs/ (a fumadocs site). Run locally:

cd docs
npm install
npm run dev

License

Apache-2.0