Verifiable agent actions. Every action becomes signed context for the next.
Agent work moves through tools, memory, identity, authorization, observability, evals, handoffs, and payments. Those layers should stay specialized. atrib gives them a common record to verify: signed actions, attached evidence, and graph structure that can cross agents, organizations, and protocols.
Shared memory and context systems decide what an agent should remember or retrieve. atrib signs the agent's action trail, then lets memory systems, auditors, payment rails, and other agents cite that same verifiable record without trusting the runtime that stored it.
The graph is one graph with two reading planes. The chronology plane preserves event history and continuity. The declared-relationship plane preserves signed claims about which records informed, anchored, annotated, or revised other records. The explorer's primary trace path gives readers one first path through that graph without flattening the graph itself.
Everything below depends on one substrate property: an action is signed when it happens and remains verifiable later.
| Surface | What atrib gives you | What it composes with |
|---|---|---|
| Verifiable agent work | A signed trail of the actions, evidence, handoffs, revisions, outputs, and verifier results behind a task. atrib proves the action history; other layers decide whether the work was authorized, correct, payable, or compliant. | Tools, memory, identity, authorization, observability, evals, commerce, governance |
| Provable cognition | An agent can read prior records and re-verify them locally. Its continuity can survive platform, model, and harness changes because the cryptography is independent. | Memory systems, shared context layers, recall tools |
| Privacy-preserving evidence | The public log stores commitments, not private work product. Verifiers can check signatures, hashes, inclusion proofs, and selected evidence without dumping tool arguments, tool results, memory text, authorization material, or workflow context into the public payload. | Local mirrors, sidecars, opt-in archive evidence, private evidence stores |
| Independent audit | A third party can verify what an agent did, in what order, and with what signed structure without trusting the agent operator, platform, or intermediary. | Audit trails, SOC 2 evidence, AI governance tooling, incident review |
| Verifiable evals | A harness can link task setup, tool calls, verifier checks, diagnostic outcomes, and scorer output through informed_by, then publish the result as evidence another team can replay. |
Eval harnesses, benchmark reports, inspection tools |
| Cross-agent provenance | Agents that hand off work to subagents carry session scope, chain tail, and parent dispatch refs together. Receiving agents can verify the handoff before signing follow-up work. | A2A, agent bridges, orchestrators, subagent runtimes |
| Verifiable investigations | Support, incident, billing, and RCA agents can sign the investigation trail: ticket intake, tenant-scoped log queries, code-path reads, hypotheses, diagnostics, revisions, and human handoffs. | Observability tools, logs, traces, support systems |
| Settlement when commerce closes a chain | The same signed record set can feed a deterministic settlement document under an agreed policy. Any merchant or auditor can recompute the §4.6 result. | AP2, Verifiable Intent, x402, ACP, merchant policies |
atrib is the substrate. Consuming it well (surfacing an agent's history at session start, exposing recall tools the agent can call, persisting signed records locally for replay) is the job of an agent harness or runtime. atrib does not prescribe a harness. The substrate is independently useful to any harness (Claude Code, Cursor, custom agent products, in-house agent runtimes) that wants to give its agent the contextual awareness verifiable history makes possible.
Hard boundary: the public Merkle log proves a commitment, but it is not enough context for a future agent to continue the work. A continuation agent needs Tier 2 and Tier 3 material: canonical record bodies or archive references, redacted evidence references, skill pack identities and hashes, the latest chain tail, parent dispatch anchors for subagent work, and provenance anchors. Without those, it can prove a record existed but still has to guess what happened.
One canonical harness pattern is signed diagnostic outcome + trace replay: sign the action, sign the diagnostic outcome that evaluates it with informed_by back to the action, then let the next repair step call atrib-trace from the diagnostic record. This keeps "what happened" and "what it supersedes" in one verifiable path without requiring a whole-session transcript dump.
Derived evidence products sit above the protocol. A harness can build a prior-work packet, suspect report, or eval summary from signed records, body commitments, verifier checks, and inclusion proofs. Those products can decide which records are useful for a task, which stale records to avoid, and which risks remain open. They do not change the record format, the graph derivation rules, or the seven cognitive primitives.
- Each record is signed by the actor's Ed25519 key and JCS-canonicalized
- A Merkle log stores commitments (hashes, not content) with RFC 6962 inclusion proofs and C2SP-canonical signed-note checkpoints
- Nine deterministic edge types connect actions into one graph with two reading
planes: chronology edges (
CHAIN_PRECEDES,SESSION_PRECEDES,SESSION_PARALLEL,CROSS_SESSION,CONVERGES_ON) and declared-relationship edges (INFORMED_BY,PROVENANCE_OF,ANNOTATES,REVISES) - The explorer's primary trace path composes
/v1/traceand/v1/chainfor readability without adding a new graph edge, validity rule, or settlement input (D118) - A pure-function calculation maps graph + policy to value distribution when commerce closes
- A public-key directory (§6) resolves opaque keys to identity claims; rotation and revocation are normative (§1.9); identity claims may declare capability envelopes (§6.7) that verifiers check records against
- Transaction records require cross-attestation: at least 2 distinct verified signer keys (agent + counterparty) per §1.7.6
- Cross-log replication (§2.11) lets consumers submit records to multiple independent logs and detect equivocation
- Privacy is configurable per record (§8 privacy postures): tool_name forms (verbatim, opaque, hashed), commitment schemes (plain, salted-sha256, hmac-sha256), timestamp granularity (ms through day)
- Adversarial threat model (§8.7) enumerates the 10-layer trust assessment stack the substrate provides
No custom cryptography. No content exposure unless the harness opts in. No trust required.
One command, no setup beyond cloning. Generates a fresh key, spins up an in-process Merkle log, fake merchant, and fake agent, runs two tool calls plus one transaction, and prints what landed in the log.
ATRIB_PRIVATE_KEY=$(node -e 'console.log(Buffer.from(crypto.randomBytes(32)).toString("base64url"))') \
pnpm --filter @atrib/integration demoExpected output:
[demo] starting dev log...
[demo] dev log running at http://127.0.0.1:58958
[demo] starting merchant tool server (fake search API)...
[demo] starting agent client...
[demo] agent connected to merchant
[demo] step 1: agent calls 'search' for the first time (genesis)
[log] +tool_call ctx=7f71199d… chain=sha256:064692c27… idx=0
[demo] step 2: agent calls 'search' again (chained from step 1)
[log] +tool_call ctx=7f71199d… chain=sha256:381c22ac6… idx=1
[demo] step 3: agent observes a fake x402 payment receipt
[log] +transaction ctx=7f71199d… chain=sha256:96ac3e962… idx=2
[demo] final state
[demo] 3 records in the log
[demo] 2 tool_call records
[demo] 1 transaction record
[demo] chain length: 3
[demo] done.
The signatures, chain hashes, and transaction detection are production code. Only the surrounding environment (merchant, agent, network) is stubbed.
Now that you've seen the demo, pick the install path that matches what you're doing:
- Sign tool calls your MCP server handles:
@atrib/mcp(below) - Sign tool calls your agent makes:
@atrib/agent(below) - Verify records someone else produced:
@atrib/verify(below)
import { atrib } from '@atrib/mcp'
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
const server = atrib(new McpServer({ name: 'my-tool', version: '1.0.0' }), {
creatorKey: process.env.ATRIB_PRIVATE_KEY,
serverUrl: 'https://my-tool.example.com',
})One line. Every successful tool call emits a signed attribution record, propagates W3C trace context, and submits to the log asynchronously.
@atrib/agent exports one interceptor plus a helper per framework. Some runtime
examples use the host's native callback surface while keeping the same
hash-only record shape. Start with the row matching your stack:
import { AtribVerifier } from '@atrib/verify'
const verifier = new AtribVerifier({
merchantKey: process.env.ATRIB_MERCHANT_KEY,
})
const result = await verifier.verify(recommendationDoc)
// { valid: true, signatureOk: true, calcMatch: true, distribution: {...} }Verification re-runs the §4.6 calculation locally and compares the result. No trust in any intermediary.
atrib certifies five verifiable axes of agent activity: who acted (identity), what they did (event_type), when (timestamp), what came before what in the chronology plane, and what the signer claimed informed, anchored, annotated, or revised the action in the declared-relationship plane.
atrib does NOT certify that the agent's reasoning is truthful, that prior records actually influenced subsequent decisions, or that tool responses were real absent tool-side attestation. The substrate is content-preserving (commitments, not content) and disclosure-configurable: harnesses pick how much each record reveals via the privacy postures in spec §8.
This positioning keeps the claim honest. See spec §3 "What atrib chains, what it does not" for the detailed enumeration and spec §7.6 for the outcome-verification patterns that close the tool-response gap.
| Framework | Adapter | Status |
|---|---|---|
Raw @modelcontextprotocol/sdk |
wrapMcpClient(client, interceptor, { serverUrl? }) |
✅ Shipped |
| Claude Agent SDK (in-process, Case A) | Wrap McpServer with atrib() directly |
✅ Shipped |
| Claude Agent SDK (third-party, Case B) | createAtribProxy({ upstream, interceptor }) |
✅ Shipped |
| Cloudflare Agents | attributeCloudflareAgentMcp(agent, { interceptor, serverUrls }) |
✅ Shipped |
| Vercel AI SDK MCP | attributeVercelAiSdkMcp(mcpClient, { interceptor, serverUrl }) |
✅ Shipped |
| LangChain JS MCP | attributeLangchainMcp(multiClient, { interceptor, serverUrls }) |
✅ Shipped |
| OpenAI Agents SDK | Planned (different transport architecture) | ⏳ |
| Mastra | Receipt proof for @mastra/mcp; adapter planned |
🧪 Proof |
Side-by-side quick-starts for each framework: packages/agent/README.md.
atrib detects transaction events from all six simultaneously. It does not move money or enforce transactions.
| Protocol | Sponsor | Detection signal | Spec ref |
|---|---|---|---|
| ACP | Stripe / OpenAI | status === "completed" + embedded order |
§1.7.1 |
| UCP | Google / Shopify | Same as ACP + ucp.version envelope |
§1.7.2 |
| x402 | Coinbase | PAYMENT-RESPONSE HTTP header |
§1.7.3 |
| MPP | Tempo Labs / Stripe | Payment-Receipt HTTP header |
§1.7.4 |
| AP2 | Successful CheckoutReceipt or PaymentReceipt | §1.7.5 | |
| a2a-x402 | A2A task metadata payment-completed |
§1.7.5 |
| Package | What it does |
|---|---|
@atrib/mcp |
Server middleware. Wraps an MCP server, emits signed records. |
@atrib/agent |
Agent middleware. Interceptor + framework adapters. |
@atrib/verify |
Merchant verification. Re-runs the calculation locally, checks AP2 / VI evidence, verifies authorization evidence such as MCP/OAuth and AAuth, and verifies Pattern 3 handoff claims. |
@atrib/cli |
CLI: keygen, Keychain key management, identity-claim ops, key rotation and revocation. |
@atrib/mcp-wrap |
Generic config-driven MCP wrapper. Multiplies coverage to any MCP server at zero per-server code cost. |
@atrib/directory |
AKD-backed identity-claim directory SDK. Bundles WASM artifacts from the Rust bridge. |
@atrib/openinference |
OpenTelemetry SpanProcessor consuming OpenInference-shaped spans and emitting signed atrib records plus recall-readable local sidecar content. Reference impl of spec §9 Pattern #4; one adapter transitively covers every framework with OpenInference instrumentation. |
@atrib/memory-tool |
Anthropic Memory Tool handler wrapper. Signs memory commands as atrib records while the host keeps its own storage backend. |
@atrib/runtime-log |
Runtime-log proof helpers. Builds and verifies log_window_manifest objects for host-owned agent run windows. |
@atrib/emit |
Cognitive-primitive MCP server: signs observations, annotations, revisions the wrapper doesn't auto-capture. |
@atrib/annotate |
Cognitive-primitive MCP server: marks past records' importance, topics, and summary. |
@atrib/revise |
Cognitive-primitive MCP server: supersedes a prior position with a stated reason. |
@atrib/recall |
Cognitive-primitive MCP server: queries the local mirror for an agent's own past records. |
@atrib/trace |
Cognitive-primitive MCP server: walks informed_by / annotates / revises edges backward to reconstruct declared relationship traces. |
@atrib/summarize |
Cognitive-primitive MCP server: reads N records and synthesizes a narrative via an OpenAI-compatible LLM. |
@atrib/verify-mcp |
Cognitive-primitive MCP server: verifies counterparty handoff evidence before an agent links follow-up work through informed_by. |
@atrib/primitives-runtime |
Private local MCP runtime: exposes all seven primitive packages through one stdio or Streamable HTTP MCP server for dogfood harnesses that would otherwise spawn one process per primitive. |
@atrib/log-dev |
Dev-only in-memory log stub. Not for production. |
@atrib/integration |
Cross-package tests + runnable examples. |
The workspace ships tests across packages, services, apps, and examples. Sixteen designed-public packages are in the npm publish set. Fifteen are live on npm today through Trusted Publishing OIDC: the six core packages (
@atrib/mcp,@atrib/agent,@atrib/verify,@atrib/cli,@atrib/mcp-wrap,@atrib/directory), the seven cognitive-primitive MCP servers (@atrib/emit,@atrib/annotate,@atrib/revise,@atrib/recall,@atrib/trace,@atrib/summarize,@atrib/verify-mcpper D079 and D106), and two proof/intake packages:@atrib/openinference, the reference implementation of §9 Pattern #4 with all 10 OpenInference span kinds mapped (TOOL / LLM / AGENT / EMBEDDING / RETRIEVER / RERANKER / CHAIN / GUARDRAIL / EVALUATOR / PROMPT), and@atrib/memory-tool, the Anthropic Memory Tool wrapper.@atrib/runtime-logis the D121 runtime-log manifest helper package and remains a publish target until its first manual npm publish creates the package and Trusted Publisher is configured. Four services are deployed today:services/log-node/(https://log.atrib.dev/v1),services/graph-node/(https://graph.atrib.dev/v1),services/directory-node/(https://directory.atrib.dev/v6), andservices/archive-node/(https://archive.atrib.dev/v1). Archive-node is the deployed §2.12 reference service for public body and evidence retrieval. A reproducible end-to-end verifier with 13 gate assertions across 8 named categories (tree integrity, format conformance, checkpoint signature, pubkey-publication agreement, signer scope, attribution, record signature replay, chain integrity) ships atservices/log-node/scripts/verify-loop.mjsand runs daily in CI against the deployed log. The public block explorer athttps://explore.atrib.dev/composes the log, graph, directory, and archive evidence APIs into seven views (overview, identity, session, action, demo, trace, anchoring), with Sigma.js-rendered DAGs for session, identity, trace, and demo views. Seven standalone in-process MCP services close the cognitive loop on the agent side:services/atrib-emit/signs observations the wrapper doesn't auto-capture;services/atrib-annotate/marks past records' importance and meaning;services/atrib-revise/supersedes a prior position with a stated reason;services/atrib-recall/queries the local mirror for an agent's own past records;services/atrib-trace/walksinformed_by/annotates/revisesedges backward through the local mirror to reconstruct declared relationship traces;services/atrib-summarize/reads N records and synthesizes a narrative via an OpenAI-compatible LLM;services/atrib-verify/verifies counterparty handoff evidence before linking follow-up work. All seven remain public stdio binaries. The privateservices/atrib-primitives/runtime mounts those packages in one process and exposes their 15 physical MCP tools through stdio or a loopback Streamable HTTP host for local dogfood configs. The read primitives consume local mirror, archive body material, or caller-supplied evidence per spec §5.9, §2.12, and §5.5.5.
Implemented and deployed: Record signing (§1) including INFORMED_BY (D041), PROVENANCE_OF (D044), ANNOTATES (D058), REVISES (D059), and directory_anchor (D056) event types. Parent-child producer threading now has a single same-session subagent env bundle: ATRIB_CONTEXT_ID, ATRIB_CHAIN_TAIL_<context_id>, and ATRIB_PARENT_RECORD_HASH, built by @atrib/mcp buildSubagentProducerEnv() when the parent dispatch hash is known before the child signs (D104, D115). Source-aware producer validation lets @atrib/mcp-wrap keep configured informedByPaths only when refs resolve through the wrapper mirror, local mirrors, or log lookup, while parent env seeds stay producer-owned (D116). Pattern 3 handoff claim acceptance lets a receiving agent verify another agent's record_hash, body commitment, inclusion proof, checkpoint signature, signer trust, context policy, and freshness before signing an informed_by follow-up; @atrib/verify provides the library helper and @atrib/verify-mcp exposes the atrib-verify primitive (§5.5.5, D105, D106). Sandboxed producer key isolation (§1.4.6, D102) keeps signing keys outside sandboxed execution via a tested host signer-proxy example. Transparency log (§2) with persistent storage, C2SP-canonical signed-note checkpoints (D031), and optional SSE / JSON Feed subscription surfaces (§2.5.6, D103). Graph query interface (§3) with full nine-edge §3.2.4, /v1/trace/<record_hash>, /v1/chain/<record_hash>, /v1/creators/<key>/graph, and an explorer primary trace path that composes trace plus chain without changing the protocol APIs (D068, D118). Substrate-wide conformance corpora (D101) pin §1.4 adversarial signing vectors, §3.2.4 full edge derivation, D067 multi-producer race vectors, and D052 creator-signer separation. Calculation algorithm (§4.6) with deterministic distribution and §4.7 settlement document signing. AKD-backed public-key directory (§6, D034) deployed at https://directory.atrib.dev/v6 (unblinded mode for atrib's own use; VRF-blinded mode available for downstream consumers requiring privacy-preserving lookup). Per-operation directory anchoring back into the log (§6.2.4). Key rotation and revocation (§1.9, D033): verifier honors revocations, @atrib/cli exposes publish-claim / revoke commands, conformance corpus generated. Capability declarations (§6.7, D051) surfaced by the verifier as soft signals per §6.7.3. Cross-attestation requirement on transaction records (§1.7.6, D052) flagged by the verifier when fewer than two distinct signer keys verify. AP2 / Verifiable Intent evidence checks (§5.5.4, D089, D090, D091, D092, D093, D094, D096, D097, D098, D107) validate AP2 receipt references, signed receipt JWTs, VI SD-JWT / VC mandate chains, typed AP2 mandate constraints, offline JOSE / JWKS / SD-JWT crypto edge cases, opt-in AP2 reference artifacts, and AP2 transaction-record artifacts off the detector path. AP2 Path 2 transaction emission uses a stable receipt identity ladder when receipt or mandate identity is visible (D095) and carries an agent signers[] entry over the D052 canonical bytes; AP2 counterparties can add their own signer entry with signTransactionAttestation(). verifyRecord() and AtribVerifier.verify() attach supplied evidence as tiered ap2_vi_evidence without counting AP2 receipt JWTs as transaction signers. Privacy postures (§8, D045) with disclosure dials per record. Opt-in autoChain plus a cross-producer chain-tail handoff via ATRIB_CHAIN_TAIL_<context_id> env var for hosts that don't propagate atrib's outbound token.
@atrib/verify also exposes generic tiered authorization evidence blocks (§5.5.6, D109, D110, D111, D119). verifyRecord() can attach MCP/OAuth or AAuth evidence under evidence[] and consume caller-supplied resolvedFacts for capability checks without changing base record validity. @atrib/mcp can capture validated MCP authInfo and AAuth callback evidence into local-only sidecars, including DPoP proof material, HTTP signature facts, and token hashes without storing raw bearer tokens or raw AAuth JWTs by default. Hosts that need live OAuth introspection can use introspectOAuthToken() to produce caller-owned evidence, and AAuth callers supply trusted JWKS, verified claims, or decoded claims under an explicit signature policy.
For the delegation and capability-system boundary, see Delegation and capabilities: atrib verifies external authorization evidence, but the issuing and enforcement layers remain outside the protocol.
Spec-defined but not implemented: Witnessing (§2.9, D032; first implementation deferred until an independent verifier exists). Cross-log replication (§2.11, D050; spec-defined; second log-node deployment + verifier multi-log proof bundles forthcoming). §6.3 verifier consultation steps 1, 3, 4, 5, 7 (anchor + lookup-proof + append-only + emergency-key paths; AKD WASM bridge upstream gating).
Developer CLI for the public log surface: atrib-log-pp-cli is a Printing-Press-generated Go CLI that wraps log.atrib.dev directly (signed checkpoint, recent entries, lookup by hash, by context, by creator, Merkle tile retrieval) with a local SQLite mirror + FTS5 + compound workflow commands. It is complementary to the @atrib/* MCP cognitive primitives, not a replacement: use the MCP primitives for agent cognitive work; use this CLI for human or script interaction with the public log API.
node -e 'console.log(Buffer.from(crypto.randomBytes(32)).toString("base64url"))'Store the output as ATRIB_PRIVATE_KEY. The public key is derived at runtime.
atrib-spec.md covers:
- §0: Foundations
- §1: Attribution record format, signing, propagation, payment protocol hooks
- §1.9: Key rotation and revocation (D033)
- §2: Merkle log protocol (C2SP tlog-tiles, proofs, witnessing)
- §3: Graph query interface (nine edge types)
- §4: Policy format, negotiation, calculation algorithm
- §5: SDK contract, automation, degradation guarantees
- §6: Public-key directory (AKD-based; D034)
- §7: Harness integration patterns (informative)
- §8: Privacy postures (D045; per-record disclosure dials)
- §9: Runtime integration patterns (informative; seven peer patterns per D069 and D102)
- Provenance travels with the artifact. Embedded at creation, not inferred later.
- Accountability without content exposure. The log stores hashes, not content.
- Settlement is separate from attribution. The protocol records what happened. It does not move money.
- No central arbiter of value. Trust from math and open spec, not from trusting atrib.
- The protocol is open. The product is commercial. Spec, signing libraries, calculation algorithm, and log software are open. Anyone can self-host. atrib operates a hosted service as a commercial product built on the open protocol.
DESIGN.md is the source of truth for atrib's public product surfaces: website, explorer, docs, package README patterns, share images, and user-facing reliability states. It records the current state, target direction, tokens, components, writing rules, and remaining design backlog.
- Policy templates and guide
- Product design system
- Architecture and trust model
- Prior art and standards map
- Decision log
- AAuth evidence outreach packet
- Contributing
Apache 2.0