@origintrail/context-graph

Privacy-first context graph engine that transforms event logs into temporal PROV-O provenance graphs with hash chain integrity, policy-driven redaction, and pluggable reasoning.

What it does

Every action an agent (or any system) takes is logged as a normalized event. Events form a tamper-evident hash chain. At session end, the engine derives claims (e.g. "CanFixBuild", "CanRunTests") from observed outcomes, computes aggregate metrics, and produces a public graph that contains only hashes, aggregates, and claims — never raw code, secrets, or file contents.

The public graph can then be submitted to external systems (like ClawTrail) for reputation building, verification, and discovery.

Agent session
  → Normalized events (JSONL, hash-chained)
  → PROV-O graph (private, local)
  → Summarize: metrics + claims + Merkle root
  → Public graph (redacted, policy-driven)
  → Signed submission → ClawTrail API (or file)

Install

npm install @origintrail/context-graph

Or link locally during development:

cd context-graph
npm install
npm run build

Quick start

Programmatic (library)

import { ContextGraph } from '@origintrail/context-graph';

const cg = new ContextGraph({ root: '.context-graph' });
await cg.init();

// Start a session
const session = await cg.startSession({ task: 'Fix failing tests' });

// Log events
await session.logEvent({
  type: 'FILE_WRITE',
  status: 'SUCCEEDED',
  data: { path_hash: 'sha256:...', path_extension: '.ts', bytes_written: 200 },
});

await session.logEvent({
  type: 'TEST_RUN',
  status: 'SUCCEEDED',
  data: { framework: 'jest', passed: 12, failed: 0, skipped: 0, duration_ms: 5200 },
});

// End session
await session.end();

// Summarize — produces metrics, claims, and public graph
const summary = await cg.summarize(session.meta.session_id);
console.log(summary.claims);   // [{ claimType: 'cg:CanRunTests', confidence: 0.8, ... }]
console.log(summary.metrics);  // { tests_pass_rate: 1.0, ... }

// Verify hash chain integrity
const result = await cg.verify(session.meta.session_id);
console.log(result.valid); // true

// Export
const jsonld = await cg.export(session.meta.session_id, 'jsonld');
const turtle = await cg.export(session.meta.session_id, 'ttl');

CLI

# Initialize
cg init

# Create a session
SESSION_ID=$(cg start-session --task "Fix auth module")

# Log events
cg log-event --session $SESSION_ID --type SHELL_COMMAND --cmd "npm test" --exit-code 0
cg log-event --session $SESSION_ID --type NOTE --text "Fixed the token validation bug"

# End session
cg end-session --session $SESSION_ID

# Summarize (generates metrics, claims, public graph)
cg summarize --session $SESSION_ID

# Verify integrity
cg verify --session $SESSION_ID

# Export
cg export --session $SESSION_ID --format jsonld
cg export --session $SESSION_ID --format ttl

# Check status
cg status

How it works

Event model

Every event is a normalized JSON object appended to an append-only JSONL log:

{
  "event_id": "uuid",
  "session_id": "uuid",
  "ts": "2026-02-09T14:30:00.000Z",
  "type": "TEST_RUN",
  "status": "SUCCEEDED",
  "actor": { "agent_id": "agent:openclaw:my-coder" },
  "privacy": { "level": "LOCAL_ONLY" },
  "event_hash": "sha256:...",
  "prev_event_hash": "sha256:...",
  "data": { "framework": "jest", "passed": 12, "failed": 0 }
}

Base event types: SESSION_START, SESSION_END, TOOL_CALL, ERROR, NOTE

Standard extension types (registered by adapters): FILE_READ, FILE_WRITE, SHELL_COMMAND, GIT_DIFF, GIT_COMMIT, TEST_RUN, BUILD_RUN

Hash chain

Each event's prev_event_hash points to the preceding event's event_hash. The first event has prev_event_hash: null. This creates a tamper-evident chain — modifying any event breaks the link.

Merkle tree

At session end, a binary Merkle tree is built from all event hashes. The root is the commitment — a single hash that proves the entire session's contents.

Claims

Claims are derived from observed outcomes via a rule registry. The engine ships with two built-in rules:

| Rule | Logic | Confidence | |---|---|---| | cg:CanCompleteSession | Session ended normally with > 5 actions | 0.6 | | cg:IntegrityValid | Hash chain is complete and valid | 1.0 |

Adapters (like @origintrail/context-graph-openclaw) register additional rules:

| Rule | Logic | Confidence | |---|---|---| | cg:CanFixBuild | Build failed then succeeded | 0.9 | | cg:CanFixTests | Tests failed then succeeded | 0.9 | | cg:CanRunTests | 3+ successful test runs | 0.8 | | cg:CanWrite:<lang> | Wrote files in language | 0.3 | | cg:CanUseFramework:<name> | Used test/build framework | 0.5 | | cg:CanUseTool:<name> | Used shell tool | 0.4 |

Privacy & policy

Default: everything is local-only. The public graph contains only:

• Session metadata (task description, time range, agent ID)
• Commitment (Merkle root, event count)
• Derived claims with confidence scores
• Aggregate metrics (pass rates, durations — never raw data)
• Policy hash

A policy.yaml file controls redaction patterns, publish levels, and what appears in the public graph. Secrets matching patterns (AWS keys, GitHub PATs, etc.) are stripped before any processing.

Extending

// Register custom event types
cg.registerEventType('MY_CUSTOM_TYPE', mySchema);

// Register custom reasoning rules
cg.reasoning.registerRule({
  id: 'my:CustomRule',
  name: 'My Rule',
  description: 'Fires when...',
  evaluate(ctx) {
    // Inspect ctx.events and ctx.session
    return [{ claimType: 'my:CustomClaim', confidence: 0.7, evidenceHashes: [...] }];
  },
});

// Replace the publisher
cg.setPublisher(myApiPublisher);

Local storage

.context-graph/
├── config.json
├── policy.yaml
└── sessions/
    └── <session_id>/
        ├── session.meta.json
        ├── events.jsonl
        ├── graph.public.jsonld
        ├── hashes.json
        ├── metrics.json
        ├── claims.json
        └── session.lock

Ontology

The cg: namespace (https://origintrail.io/context-graph/v1#) extends W3C PROV-O:

• Sessions are prov:Activity
• Actions are prov:Activity linked by prov:wasInformedBy
• Agents are prov:SoftwareAgent
• Artifacts and outcomes are prov:Entity
• Claims and commitments are prov:Entity with cg: extensions

Development

npm install
npm run build
npm test        # 29 tests
npm run dev     # watch mode

License

MIT