Agent Context Graph

Note (2026-01-26): This repo has been split. Canonical sources now live in:

Abstract Agent Type System with Context Graphs, DIDs/VCs, Causality, and Provenance

A comprehensive framework for defining agent behavioral contracts (Abstract Agent Types) and managing their runtime interactions through Context Graphs, with full support for decentralized identity, verifiable credentials, causal reasoning, and provenance tracking.

Now with Multi-Agent Orchestration, Federation, and Personal Broker!

Key Features

Core

Abstract Agent Types (AAT) - Formal behavioral contracts in OWL
Context Graphs - Runtime situational awareness with affordances
Hypergraph Semantics - Multi-party affordances modeled as hyperedges
Category-Theoretic Composition - Formal composition of affordance workflows
Usage-Based Semiotics - Meaning emerges from observed usage patterns
Semantic Web Standards - OWL ontology, SHACL validation, Hydra API, JSON-LD
PROV Tracing - W3C-compliant provenance for every action
DIDs & VCs - Decentralized identity and verifiable credentials
Execution Enclaves - Isolated git worktree environments (Gas Town inspired)
Context Checkpoints - Crash recovery with state persistence
AAT-Aware Parallelization - Conflict-aware concurrent execution
Causal Semantics - do-calculus intervention labels for reproducibility
CLI Tooling - Validate, federate, checkpoint, and enclave management

Personal Broker & Federation (NEW)

Personal Broker - Unified conversation, memory, and contact management
Social Federation - Connect brokers, form groups, discover peers
Shared Contexts - CRDT-based collaborative context graphs
ActivityPub Bridge - Fediverse interoperability (Mastodon, etc.)
DIDComm Messaging - Encrypted agent-to-agent communication
DID/VC Authentication - Challenge-response auth with verifiable credentials
Channel Bridge - Slack, Discord, Matrix, and Email integration
Real-time Sync - WebSocket-based live collaboration
SQLite Persistence - Durable storage for all federation data

Key Concepts

Abstract Agent Types (AAT)

Behavioral contracts that define what an agent can perceive, how it may act, and the invariants it must preserve—independent of how the agent is implemented.

Standard agent types included:

Observer: Watch and report; no side effects (maxConcurrent: 10)
Planner: Produce plans, not execute (maxConcurrent: 3)
Executor: Perform actions based on authorized plans (maxConcurrent: 20, requires isolation)
Arbiter: Approve/deny/transform proposed actions (maxConcurrent: 1, singleton)
Archivist: Store and retrieve traces/knowledge (maxConcurrent: 2)

Context Graphs

Runtime situational awareness that provides agents with their available actions (affordances) based on:

Agent identity (DID)
Verified credentials (VCs)
Active policies
Current situation

Hypergraph + Category Semantics

The Context Graph can be rendered as:

Hypergraph: affordances are hyperedges binding agents, targets, credentials, and constraints
Category: objects are state slices; morphisms are affordance traversals; composition is explicit

Semantic Web Standards

Standard	Usage	Endpoint
OWL	Agent types, action taxonomies, class hierarchies	`/ontology`
SHACL	Parameter validation shapes	`/shacl`
Hydra	Hypermedia-driven API documentation	`/hydra`
JSON-LD	Context graphs, PROV traces	All responses

Gas Town-Inspired Features

Inspired by Gas Town, we've added:

Execution Enclaves - DID-bound isolated git worktrees for agents
Context Checkpoints - Immutable snapshots for crash recovery
AAT-Aware Parallelization - Conflict rules, resource limits, cost caps

Cross-Broker Federation

Agents can operate across organizational boundaries through federated trust:

Trust Relationships - Explicit trust with levels: FullTrust, LimitedTrust, VerifyAlways
Credential Bridges - Map credentials across trust domains
Multi-Hop Federation - Chain federation paths (Alpha → Beta → Gamma)
Federation Protocols - ActivityPub, DIDComm, LDN, HTTP

Personal Broker

Each user has a Personal Broker that acts as their unified AI assistant:

Conversations - Multi-channel chat history with context
Memory - Persistent facts, preferences, and learned information
Contacts - Address book with DID-based identity
Presence - Online/offline status and availability
Channels - Bridge to Slack, Discord, Matrix, Email

Social Federation

Brokers can connect and collaborate:

Connections - Friend/follow relationships between brokers
Groups - Shared spaces for team collaboration
Invites - Link-based onboarding with usage limits
Discovery - Find brokers by DID, WebID, or search
Notifications - Real-time alerts for social events

Shared Contexts

Collaborative context graphs with real-time sync:

CRDT-based - Conflict-free replicated data types for consistency
Access Control - Read/write/admin permissions per broker
Vector Clocks - Causal ordering of distributed updates
Presence - See who's viewing/editing in real-time
Conflict Resolution - Auto-merge or manual resolution options

Causal Semantics

Built-in support for causal reasoning and reproducibility:

Intervention Labels - do-calculus notation: do(Action, {params})
Baseline Observations - Capture pre-intervention state
Outcome Constraints - Define expected causal effects
Counterfactual Analysis - Trace back to understand causation

HATEOAS Principle

Agents discover actions at runtime through broker-provided affordances. No global tool lists—agents may only act through what the Context Graph provides.

Provenance (PROV)

Every affordance traversal produces an immutable W3C PROV trace for accountability, auditing, and counterfactual analysis.

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Run the Dashboard with integrated Orchestrator (port 3001)
ANTHROPIC_API_KEY=your-key npm run dashboard

# Or use Claude Code CLI instead of API
USE_CLAUDE_CLI=true npm run dashboard

# Or run the interactive demo
ANTHROPIC_API_KEY=your-key npm run demo "Create a REST API for user management"

Dashboard Features

The web dashboard at http://localhost:3001 includes:

Real-time WebSocket Updates - Live workflow, agent, and task status (ws://localhost:3002)
Context Graph Visualization - D3.js interactive graph of agent affordances
Workflow Graph API - Visual task dependency tracking
Credential Management - View and manage verifiable credentials
Structured Logging - Filterable log viewer with history
Example Loader - Load golden-path examples for testing
PROV Trace Timeline - View all provenance traces

CLI Commands

The acg CLI provides tools for validation, federation management, and infrastructure operations:

# Validate a single context graph against SHACL shapes
npm run cli validate examples/golden-path/planner-context.json

# Validate all golden-path examples
npm run cli validate-all

# Check federation status
npm run cli federate status

# List established trust relationships
npm run cli federate trust

# List all checkpoints
npm run cli checkpoint list

# Create a checkpoint
npm run cli checkpoint create --label "Before migration"

# List active enclaves
npm run cli enclave list

# Create an enclave
npm run cli enclave create --name "feature-work" --repo "https://github.com/org/repo"

Running Multi-Agent Workflows

1. Start the Context Broker

npm start
# Dashboard available at http://localhost:3000

2. Start the Orchestrator

# Standard orchestrator
ANTHROPIC_API_KEY=your-key npm run orchestrator

# Or with parallel execution enabled
ANTHROPIC_API_KEY=your-key ENABLE_PARALLEL=true npm run orchestrator

3. Submit a Goal

curl -X POST http://localhost:3001/goals \
  -H "Content-Type: application/json" \
  -d '{"goal": "Create a REST API for user management with CRUD operations"}'

4. Monitor Progress

# Get workflow status
curl http://localhost:3001/workflows/{workflow-id}

# Get orchestrator stats (includes parallelization status)
curl http://localhost:3001/stats

Architecture

+------------------------------------------------------------------+
|                    CONCURRENT ORCHESTRATOR                        |
|  +----------------+  +----------------+  +-------------------+    |
|  | Task Manager   |  | Agent Pool     |  | Concurrency Policy|    |
|  +----------------+  +----------------+  +-------------------+    |
|  +----------------+  +----------------+                           |
|  | Enclave Svc    |  | Checkpoint Svc |  (Gas Town inspired)      |
|  +----------------+  +----------------+                           |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                       CONTEXT BROKER                              |
|  +----------------+  +----------------+  +-------------------+    |
|  | AAT Registry   |  | SHACL Validator|  | Policy Engine     |    |
|  +----------------+  +----------------+  +-------------------+    |
|  +----------------+  +----------------+  +-------------------+    |
|  | Trace Store    |  | Causal Eval    |  | Enclave/Checkpoint|    |
|  +----------------+  +----------------+  +-------------------+    |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                         AGENT POOL                                |
|  +-----------+  +-----------+  +-----------+  +-----------+      |
|  | Planner   |  | Executor  |  | Observer  |  | Arbiter   |      |
|  | (LLM)     |  | (Enclave) |  | (LLM)     |  | (Singleton)|     |
|  +-----------+  +-----------+  +-----------+  +-----------+      |
+------------------------------------------------------------------+

API Endpoints

Context Broker (port 3000)

Endpoint	Method	Description
`/`	GET	Hydra API entry point
`/context`	POST	Generate a Context Graph for an agent
`/traverse`	POST	Execute an affordance (including infrastructure actions)
`/traces`	GET	Query PROV traces
`/traces/{id}`	GET	Get a specific trace
`/aat`	GET	List registered AATs
`/aat/{id}`	GET	Get a specific AAT
`/ontology`	GET	OWL/RDF ontology (Turtle or JSON-LD)
`/hydra`	GET	Hydra API documentation
`/shacl`	GET	SHACL validation shapes
`/health`	GET	Health check

Dashboard + Orchestrator (port 3001)

Endpoint	Method	Description
`/`	GET	Web dashboard UI
`/goals`	POST	Submit a goal for agents to achieve
`/workflows`	GET	List all workflows
`/workflows/{id}`	GET	Get workflow status
`/workflows/{id}/graph`	GET	Get workflow graph data for visualization
`/workflows/{id}/cancel`	POST	Cancel a running workflow
`/stats`	GET	Get orchestrator statistics
`/credentials`	GET	List all credentials
`/credentials`	POST	Create a new credential
`/credentials/{id}`	GET	Get a specific credential
`/credentials/{id}`	DELETE	Delete a credential
`/logs`	GET	Get structured logs (query: level, component, limit)
`/aat`	GET	List registered AAT types
`/aat/{id}`	GET	Get a specific AAT definition
`/context`	GET/POST	Get context graph from broker
`/traverse`	POST	Execute an affordance
`/health`	GET	Health check

WebSocket: ws://localhost:3002 - Real-time updates for workflows, agents, tasks, and logs

Federation API (port 3000)

Endpoint	Method	Description
`/broker`	GET	Get personal broker info and stats
`/broker/conversations`	GET/POST	List or create conversations
`/broker/memory`	GET/POST	Query or store memories
`/broker/contacts`	GET/POST	List or add contacts
`/broker/presence`	GET/PUT	Get or update presence status
`/social/profile`	GET/PUT	Get or update social profile
`/social/connections`	GET	List social connections
`/social/connections/request`	POST	Request a new connection
`/social/invites`	GET/POST	List or create invite links
`/social/groups`	GET/POST	List or create groups
`/social/discovery`	GET	Discover other brokers
`/contexts`	GET/POST	List or create shared contexts
`/contexts/{id}`	GET/DELETE	Get or delete a shared context
`/contexts/{id}/nodes`	GET/POST	List or add context nodes
`/contexts/{id}/edges`	GET/POST	List or add context edges
`/sparql`	POST	Execute SPARQL queries
`/rdf`	GET	Export traces as Turtle RDF

WebSocket: ws://localhost:3000/ws - Real-time sync for shared contexts and presence

See protocol/API.md for complete API documentation.

Infrastructure Actions (Gas Town Inspired)

The broker supports infrastructure affordances for isolated execution:

Enclave Actions

// CreateEnclave - Create isolated git worktree
await broker.traverse({
  affordanceId: 'aff-createenclave-xxx',
  parameters: {
    repository: 'https://github.com/org/repo',
    baseBranch: 'main',
    enclaveName: 'feature-work',
    ttlSeconds: 3600
  }
});

// SealEnclave - Make read-only, preserve work
await broker.traverse({
  affordanceId: 'aff-sealenclave-xxx',
  parameters: { enclaveId: 'urn:enclave:xxx', reason: 'Task complete' }
});

// DestroyEnclave - Clean up worktree
await broker.traverse({
  affordanceId: 'aff-destroyenclave-xxx',
  parameters: { enclaveId: 'urn:enclave:xxx', archiveFirst: true }
});

Checkpoint Actions

// Checkpoint - Create immutable snapshot
await broker.traverse({
  affordanceId: 'aff-checkpoint-xxx',
  parameters: {
    label: 'Before refactoring',
    agentState: { taskQueue: [...], completedTasks: [...] }
  }
});

// Resume - Restore from checkpoint
await broker.traverse({
  affordanceId: 'aff-resume-xxx',
  parameters: {
    checkpointId: 'urn:checkpoint:xxx',
    verifyIntegrity: true
  }
});

Federation Actions

// Establish trust with another broker
await federationService.establishTrust({
  targetBrokerDID: 'did:web:partner-broker.example.com',
  trustLevel: 'LimitedTrust',
  protocol: 'DIDComm',
  credentialBridges: [{
    localCredential: 'PlannerCapability',
    remoteCredential: 'ExternalPlannerCapability',
    trustLevel: 'LimitedTrust'
  }]
});

// Federate context to partner broker
await federationService.federateContext({
  targetBrokerDID: 'did:web:partner-broker.example.com',
  contextGraphId: 'urn:uuid:ctx-123',
  includeCredentials: false,  // Don't share sensitive creds
  maxHops: 3
});

AAT-Aware Parallelization

The ConcurrentOrchestrator respects AAT parallelization rules:

import { ConcurrentOrchestrator } from './agents/concurrent-orchestrator.js';

const orchestrator = new ConcurrentOrchestrator({
  brokerUrl: 'http://localhost:3000',
  aatRegistry: myAATRegistry,
  repositoryUrl: 'https://github.com/org/repo', // For enclaves
  enableCheckpointing: true,
  checkpointIntervalMs: 60000,
  concurrencyPolicy: {
    maxTotalAgents: 10,
    maxPerType: {
      'aat:ExecutorAgentType': 5,
      'aat:ArbiterAgentType': 1  // Singleton
    },
    conflictMatrix: {
      'aat:ArbiterAgentType': ['aat:ArbiterAgentType']
    },
    resourceLimits: {
      maxTokensPerMinute: 100000,
      maxCostPerHour: 10,  // $10/hr cap
      maxConcurrentAPICalls: 10
    }
  }
});

await orchestrator.start();

// Submit goal with parallel execution
const workflowId = await orchestrator.submitGoal(
  'Implement user authentication',
  { enableParallelExecution: true }
);

// Check parallelization status
const status = orchestrator.getParallelizationStatus();
// { activeAgentsByType: {...}, maxByType: {...}, conflicts: [...] }

Project Structure

agent-context-graph/
├── principles/              # Foundational principles
│   ├── aat.md
│   ├── affordances.md
│   ├── hypermedia-principles.md
│   ├── hypergraph.md
│   ├── category-theory.md
│   ├── prov.md
│   ├── policy.md
│   ├── semiotics.md
│   ├── threat-model.md
│   └── decentralized-identity.md
├── architecture/            # System architecture
│   ├── ARCHITECTURE_INDEX.md
│   ├── ARCHITECTURE.md
│   ├── interfaces.md
│   └── gas-town-inspirations.md
├── protocol/                # Protocol-level documentation
│   └── API.md               # Complete API reference
├── guides/                  # Build and usage guides
│   ├── GETTING_STARTED.md
│   └── 00-HOW-TO-BUILD.md
├── implementations/         # Reference implementations + demos (index)
│   └── README.md
├── spec/                    # Specifications
│   ├── aat/                 # AAT JSON definitions
│   ├── ontology/            # OWL ontologies (Turtle)
│   │   ├── acg-core.ttl     # Core ontology (ExecutionEnclave, Checkpoint)
│   │   ├── aat-types.ttl    # Agent type hierarchy + parallelization
│   │   ├── actions.ttl      # Action taxonomy (incl. Federation, Causal)
│   │   ├── federation.ttl   # Federation ontology
│   │   ├── personal-broker.ttl   # Personal broker ontology
│   │   ├── social-federation.ttl # Social connections ontology
│   │   ├── shared-context.ttl    # Shared context ontology
│   │   └── channel-bridge.ttl    # Channel bridge ontology
│   ├── shacl/               # SHACL validation shapes
│   │   └── params.ttl       # Parameter shapes (enclave, checkpoint, federation)
│   └── hydra/               # Hydra API documentation
│   ├── context-graph.schema.json # Context Graph JSON Schema
│   ├── prov-trace.schema.json    # PROV Trace JSON Schema
│   ├── HYPERGRAPH.md        # Hypergraph spec
│   ├── CATEGORY-THEORY.md   # Category theory spec
│   ├── cgp.md               # Context Graph Profile
│   ├── causal-affordance.md # Causal affordance spec
│   └── telemetry.md         # Telemetry spec
├── examples/                # Example files
│   ├── federation-workflow.ts  # Multi-agent collaboration demo
│   └── golden-path/
│       ├── planner-context.json      # Basic planner scenario
│       ├── executor-context.json     # Executor with tool access
│       ├── observer-context.json     # Observer with watch affordances
│       ├── arbiter-context.json      # Arbiter approval workflows
│       ├── archivist-context.json    # Archive and retrieval
│       ├── infrastructure-context.json   # Enclaves and checkpoints
│       ├── delegated-planning-context.json  # Hierarchical delegation
│       ├── multi-hop-federation-context.json  # Cross-broker federation
│       ├── causal-intervention-context.json   # Causal semantics
│       ├── error-scenario-context.json        # Error handling/recovery
│       └── prov-trace.json           # PROV activity trace
├── src/
│   ├── agents/              # Agent orchestration layer
│   │   ├── agent-runtime.ts # Agent execution loop
│   │   ├── llm-client.ts    # Claude API integration
│   │   ├── orchestrator.ts  # Standard orchestrator
│   │   ├── concurrent-orchestrator.ts  # AAT-aware parallel orchestrator
│   │   └── task-manager.ts  # Task queue & lifecycle
│   ├── broker/              # Context Broker
│   │   └── context-broker.ts # Includes enclave/checkpoint handling
│   ├── services/            # Service implementations
│   │   ├── aat-registry.ts  # AAT management + parallelization rules
│   │   ├── policy-engine.ts # Policy + concurrency evaluation
│   │   ├── enclave-service.ts   # Git worktree isolation
│   │   ├── checkpoint-store.ts  # State persistence
│   │   ├── shacl-validator.ts   # SHACL validation
│   │   ├── federation-service.ts    # Cross-broker federation
│   │   ├── personal-broker.ts       # Conversations, memory, contacts
│   │   ├── social-federation.ts     # Connections, groups, discovery
│   │   ├── shared-context.ts        # CRDT-based shared contexts
│   │   ├── channel-bridge.ts        # Slack/Discord/Matrix/Email
│   │   ├── realtime-sync.ts         # WebSocket sync service
│   │   ├── activitypub-bridge.ts    # ActivityPub protocol
│   │   ├── didcomm-messaging.ts     # DIDComm encrypted messaging
│   │   ├── did-auth.ts              # DID/VC authentication
│   │   └── federation-persistence.ts # SQLite persistence
│   ├── cli/                 # CLI tooling
│   │   ├── index.ts         # acg CLI commands
│   │   ├── chat.ts          # Interactive chat CLI
│   │   └── ws-client.ts     # WebSocket test client
│   ├── interfaces/          # TypeScript interfaces
│   ├── dashboard/           # Web dashboard
│   ├── demo/                # Demo scripts
│   └── index.ts             # Broker server
├── tests/
│   ├── agents/              # Agent tests
│   ├── services/            # Service unit tests
│   │   ├── federation-service.test.ts
│   │   └── shacl-validator.test.ts
│   ├── negative/            # Security tests
│   └── integration/         # Integration tests
│       └── federation.test.ts  # Federation flow tests
├── AGENTS.md                # Rules for coding agents
└── package.json

Reasoning Backend Options

1. Anthropic API (Default)

Uses the Claude API directly via @anthropic-ai/sdk:

ANTHROPIC_API_KEY=your-key npm run orchestrator

2. Claude Code CLI

Uses Claude Code CLI instances for agent reasoning:

USE_CLAUDE_CLI=true npm run orchestrator

const orchestrator = new Orchestrator({
  brokerUrl: 'http://localhost:3000',
  useClaudeCodeCLI: true,
  cliConfig: {
    cliPath: 'claude',
    workingDirectory: '/project',
    model: 'opus'  // Default: Claude Opus 4.5
  }
});

Safety Guarantees

No forbidden actions - AAT-forbidden actions never appear as affordances
Credential gating - Affordances require verified credentials
Every action traced - All traversals emit W3C PROV records
Context bound - Actions only valid within fresh, non-expired contexts
Policy evaluated - All actions go through policy engine
SHACL validated - All parameters validated against shapes
Conflict prevention - Concurrent agents respect AAT conflict rules
Cost limits - Resource limits prevent runaway costs ($10/hr default cap)
Isolation - Executors run in DID-bound enclaves when required

Environment Variables

Variable	Description	Required
`ANTHROPIC_API_KEY`	Claude API key for agent reasoning	Yes (for API backend)
`USE_CLAUDE_CLI`	Use Claude Code CLI instead of API	No (default: false)
`CLAUDE_CLI_PATH`	Path to Claude CLI executable	No (default: 'claude')
`BROKER_URL`	Context Broker URL	No (default: http://localhost:3000)
`PORT`	Broker server port	No (default: 3000)
`ORCHESTRATOR_PORT`	Orchestrator server port	No (default: 3001)
`ENABLE_PARALLEL`	Enable parallel workflow execution	No (default: false)
`MAX_COST_PER_HOUR`	Cost limit in dollars	No (default: 10)

Related Projects

Gas Town - Inspiration for enclaves, checkpoints, and parallelization patterns

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
.github/workflows		.github/workflows
architecture		architecture
docs		docs
examples		examples
guides		guides
implementations		implementations
principles		principles
protocol		protocol
spec		spec
src		src
tests		tests
.dockerignore		.dockerignore
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
MIGRATION.md		MIGRATION.md
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation