AgentSystems Notary

Cryptographically verifiable audit trails for Kern applications.

Overview

AgentSystems Notary creates tamper-evident audit trails for AI agent interactions.

Why

When AI behavior is questioned by customers, auditors, regulators, insurers, etc., you need to prove what actually happened. Traditional logs don't work: you control them, so third parties have to trust you didn't modify them.

Tamper-evident logging removes that trust requirement.

How It Works

Raw LLM interactions stay in your storage. No third party sees them during normal operation. But cryptographic hashes of each interaction are written to independent, tamper-evident storage (Arweave or the AgentSystems custodied service) at the same time.

If there's ever an audit or dispute, you provide the raw logs. The auditor re-hashes them and compares against the stored hashes. A match indicates the logs are unaltered. A mismatch indicates tampering or corruption.

You control your data, but can't alter it without detection.

What gets logged:

To your storage: full raw LLM payload (prompts, responses, metadata, timestamps)
To hash storage: SHA-256 hash + metadata (e.g. namespace, session ID, timestamps)

Hash Storage Options

Hashes (not raw data) can be written to either storage option:

Storage	Best For	Features
Decentralized (Arweave)	No vendor lock-in	Public append-only ledger, open-source verification, no account needed
Custodied	Managed compliance	Write-once storage, verification UI, signed attestations for audits

Info

Custodied plans offer WORM-compliant hash storage, managed signing, and signed attestations.

Prerequisites

1pip install agentsystems-notary kern-ai anthropic python-dotenv

Example (Decentralized)

Generate signing key

1openssl genrsa -out arweave-key.pem 4096

Warning

Retain this key. It is required to prove ownership of on-chain hashes during verification.

For production, use a cloud key management service.

Create .env file

Create a .env file in your project root:

1# AWS S3 for raw payload storage
2ORG_AWS_S3_BUCKET_NAME=your-bucket
3ORG_AWS_S3_ACCESS_KEY_ID=AKIA...
4ORG_AWS_S3_SECRET_ACCESS_KEY=...
5ORG_AWS_S3_REGION=us-east-1
6
7# Path to signing key
8ARWEAVE_PRIVATE_KEY_PATH=./arweave-key.pem
9
10# Anthropic
11ANTHROPIC_API_KEY=sk-ant-...

Run the example

1import os
2
3from agentsystems_notary import (
4    AgnoNotary,
5    ArweaveHashStorage,
6    AwsS3StorageConfig,
7    LocalKeySignerConfig,
8    RawPayloadStorage,
9)
10from kern.agent import Agent
11from kern.models.anthropic import Claude
12from dotenv import load_dotenv
13
14load_dotenv()
15
16# Your S3 bucket for raw LLM payloads
17s3_config = AwsS3StorageConfig(
18    bucket_name=os.environ["ORG_AWS_S3_BUCKET_NAME"],
19    aws_access_key_id=os.environ["ORG_AWS_S3_ACCESS_KEY_ID"],
20    aws_secret_access_key=os.environ["ORG_AWS_S3_SECRET_ACCESS_KEY"],
21    aws_region=os.environ["ORG_AWS_S3_REGION"],
22)
23raw_payload_storage = RawPayloadStorage(storage=s3_config)
24
25# Local RSA key for signing
26signer = LocalKeySignerConfig(
27    private_key_path=os.environ["ARWEAVE_PRIVATE_KEY_PATH"],
28)
29
30# Arweave for decentralized hash storage
31# Namespace is public — written to the ledger and used to segment stored data
32# Namespace should be one anonymous ID per customer, agent, or environment
33# Retain a record of your namespace mappings
34arweave_storage = ArweaveHashStorage(
35    namespace="tenant_a1b2c3d4",  # See namespace comments above
36    signer=signer,
37)
38
39# Assemble notary
40notary = AgnoNotary(
41    raw_payload_storage=raw_payload_storage,
42    hash_storage=[arweave_storage],
43    debug=True,
44)
45
46# Attach hooks to agent
47agent = Agent(
48    model=Claude(
49        id="claude-sonnet-4-5-20250929",
50        api_key=os.environ["ANTHROPIC_API_KEY"],
51    ),
52    instructions="You are a helpful assistant.",
53    **notary.get_hooks(),
54)
55
56agent.print_response("What is the capital of France?")

Verification

Decentralized (Arweave): Download raw payloads from your storage bucket, zip them, and verify with the open-source CLI:

1aws s3 sync s3://your-bucket/arweave/tenant_a1b2c3d4/ ./logs
2zip -r logs.zip logs
3npm install -g agentsystems-verify
4agentsystems-verify --logs logs.zip

The CLI re-hashes each payload and compares against the hashes stored on Arweave. See the full verification guide for details.

Alternatively, the Verify UI supports both decentralized and custodied verification.