Arcaeon

arcaeon

A record of what an agent did that the agent cannot quietly rewrite, and a way for anyone who doubts it to check.

Every row your agent writes is hash-chained to the row before it. Change a row, delete one, or swap two, and the check names the line where the chain breaks. Hand the file to someone else and they can run the same check without asking you for anything.

One package. One command: arcaeon <verb>.

Install

pip install arcaeon

Python 3.10 or newer. The base install has zero dependencies. That means pip pulls in arcaeon and nothing else: no protocol SDK, no crypto library, no parser. Everything in the Record, Prove and Save lists below runs on the Python standard library. It also means no network on import. The hosted verbs open a connection when you run them, and so do a few options that say so: proxy --pin-witness, and receipt cite, which looks each citation up online. Everything else works offline.

The heavy parts are extras. Add only what you use:

pip install "arcaeon[mcp]"

Other ways in, same package:

pipx install "arcaeon[mcp]"

pipx keeps arcaeon in a space of its own, apart from your other Python packages, and still puts arcaeon on your path.

uvx arcaeon demo

uvx (from uv) runs it once without keeping an install: the demo logs two rows, changes one word and shows the BROKEN line.

py -m pip install --user arcaeon

On Windows, when pip is not found, the py launcher that comes with Python installs it for your user alone, no administrator needed.

A 60-second first run

Log two rows, check them, change one word of history, check again. The lines run as typed in PowerShell, cmd and a POSIX shell. --field KEY=VALUE builds the row for you, so there is no JSON to quote; that matters on Windows, where PowerShell 5.1 strips the inner double quotes from a JSON argument like '{"tool": "search"}' before arcaeon ever sees it.

$ arcaeon log agent.jsonl --field tool=search --field query=weather
<the new row's chain value>
$ arcaeon log agent.jsonl --field tool=send_email --field to=ops
<the new row's chain value>
$ arcaeon verify agent.jsonl
{
 "verdict": "VERIFIED",
 "ok": true,
 "rows": 2,
...
(exit 0)
$ python -c "import pathlib; p = pathlib.Path('agent.jsonl'); p.write_text(p.read_text().replace('weather', 'sunshine'))"
$ arcaeon verify agent.jsonl
{
 "verdict": "BROKEN",
 "ok": false,
...
 "first_break": "line 1: chain mismatch",
...
(exit 1)

That is the whole idea. The edit was one word in the first row, and the check found it and named the line. Exit 0 means VERIFIED. Exit 1 means BROKEN. A CI gate can use the exit code alone.

What it did not catch: someone deleting the last rows. See Limits below, and arcaeon pin, which is the fix.

The verbs

Three families. The full reference, with usage lines and examples, is docs/VERBS.md.

Record: write down what happened

• log: add one JSON row to a ledger.
• verify: check a ledger's chain. VERIFIED, BROKEN or COULD NOT LOOK.
• receipt: issue or check a portable receipt someone else can verify.
• once: prove a side effect (a refund, an email) ran once, not twice.
• proxy: sit in front of an MCP server and record every tool call.
• pin: hand a ledger's current head to a witness, a local file or the hosted one.
• deal: a purchase recorded on both sides, step by step.

Prove: check what was written

• reconcile: line up two tapes of the same calls. MATCHED, MISSING, ALTERED or COULD NOT LOOK.
• audit: check a log, pin its head, or export it as one bundle.
• vet: read an MCP server's source and grade it. No code runs.
• badge: a free Markdown badge and JSON report for an MCP server.
• seal: the same badge, sealed by the hosted witness. Paid.
• baseline: score a fixed probe set before a change and again after.
• compact: check a receipt that says what a context compaction dropped.

Save: spend fewer tokens

• distill: cut a tool's output to a token budget and record what was cut.
• dedup: drop near-copies from a list of texts.
• meter: per-key usage counts and monthly caps for your own tools.

And

• stamp, credits, buy: the hosted door (below).
• mcp: the MCP server (below).
• selftest: run every bundled self-check.
• version: print the version of the package and each part.

The hosted door

stamp, pin --remote, seal and credits talk to the hosted witness at witness.arcaeon.io, over HTTPS, and only when you run them. buy reads the offers file bundled with the package and makes no request.

• arcaeon stamp FILE: sends the file's sha256 and size, never its bytes. Works without a key, inside a free daily allowance.
• arcaeon pin LEDGER --ns NAME --remote: records your ledger's head with the hosted witness. Needs ARCAEON_KEY.
• arcaeon seal PATH: grades an MCP server, then seals the report. Needs ARCAEON_KEY and nothing else, and uses one credit. The witness's pin is the seal: it records your ledger's head and checks no signature from your machine. With the arcaeon[sign] extra and a signing key in MCP_VET_RECEIPT_KEY the report is also signed and the seal says SIGNED; on the base install it says UNSIGNED and is sealed all the same. Without ARCAEON_KEY nothing is sent, you still get the free badge, and it exits 3. A key pins only under its own namespace prefix; you do not need to know yours. If the default namespace is refused, seal reads your prefix from the refusal (no credit spent) and pins under <prefix>-sealed-scans. --ns still picks one yourself.
• arcaeon credits: shows your balance. Needs ARCAEON_KEY. Looking is free.
• arcaeon buy: prints a checkout link. It opens nothing and takes no card. Payment happens on Stripe's page.

ARCAEON_KEY is the one setting. Treat it like a password: a leaked key can pin in your name. For plans and prices, see arcaeon.io/pricing.

The AI door

pip install "arcaeon[mcp]"
arcaeon mcp

arcaeon mcp starts the MCP server on stdio. It gives an agent the ledger, vet and witness tools. arcaeon mcp --tools lists them without starting anything; it needs the [mcp] extra too (on the base install it prints the pip install 'arcaeon[mcp]' hint and exits 2).

A note for MCP registry listings: before 0.9, uvx arcaeon started this server. It still does for 30 days after this release, when there is no verb and stdin is not a terminal. Point your client at arcaeon mcp now. The fallback is removed in 1.0.0.

Exit codes

One table for every verb. What each word means, in two sentences apiece, is in docs/WORDS.md.

3 is never a pass. A gate that treats only 0 as green fails on it, which is the point.

Many logs, one summary: keep the three counts side by side. Any summary arcaeon prints over many logs shows how many were VERIFIED, how many BROKEN and how many COULD NOT LOOK, never one rate. "98% verified" hides whether the other 2% were broken or simply never read, and those call for very different Monday mornings. If you build your own dashboard on the exit codes, keep the three columns too.

Before 0.9 some old tools used other codes for the same words (reconcile used 2 for COULD NOT LOOK, for example). For the 0.9.x releases, --legacy-exit on a verb returns the old tool's own code, so a gate wired to it keeps working while you rewire it. The flag goes away in 1.0.0. MIGRATION.md lists every code that moved.

Limits

The short version, before the detail:

• Tamper-evident, not tamper-proof. Anyone who can write the file can still change it. What they cannot do is change it without the check noticing and naming the line.
• One witness, and we operate it. The hosted witness at witness.arcaeon.io is run by us, the people who make this package. A pin there shows your head as it stood when we recorded it; it is not a second, unrelated party vouching for you.
• The daily anchor is a clock, not a party. The witness anchors its pin store to a public timestamp once a day. That fixes when the pins existed. It says nothing about whether they were right, and nobody behind it checked them.
• Who ran the witness at the time of a pin is unknown to an outside reader. Today you take our word for who operated it when a given pin was made. That stays true until we publish a custody record, and we have not yet.
• Reproducible by us, not yet by you. Re-running the session behind a ledger takes the model, the tool server and their state at the time, which whoever ran it has and an outside reader does not. Until there is a way to hand that over, the substitute is the proxy's request and response digests: every call row arcaeon proxy writes carries args_digest for the request and result_digest for the response. Given the bytes, you can check they are the ones that crossed the seam; you cannot re-run the call to get them.

What a hash chain proves: the rows were not changed in place after they were written. An edit, a deletion or a reorder in the middle breaks every later link, and verify names the first broken line.

What it does not prove:

• Truncation. Cut the most recent rows off and what is left still checks out. No chain catches that alone. A pin does: once a witness holds your head (row count and chain), a shorter or rewritten log no longer matches it.
• Truth. The chain records whatever was written, true or not. To tie a row to a fact someone can fetch again, store the fact's digest in the row.
• Authorship. Who wrote a row is data in the row, not a signature. Someone who rewrites the whole log from the first row can rewrite that too. A pin held outside your control is what they cannot move.

What a pin proves: the log was not cut short or rewritten relative to what the witness saw, and only as of the last pin. The longest gap between pins is your real exposure. A pin file you keep yourself shows the mechanism works; it is not an outside party. The hosted witness uses a bearer key, not a signature.

What reconcile proves, in its own words:

• MATCHED means two recorders agree; a colluding agent side and tool side can write two agreeing tapes of a lie.
• A call that crossed neither instrumented seam leaves no row on either tape; an agent that never calls, or calls through an unwrapped channel, is invisible here.
• Digests compare content (canonical JSON), not bytes: a meaning-preserving re-serialization in transit is MATCHED by design.
• Without a witness pin, both tapes truncated or rewritten in agreement still match; a pin bounds that to the rows written after it.

vet and badge report what their own checks found in the bytes they read. They are not a review by a person and not a safety certification.

Writing is not fast. Each log row (Ledger.append) is flushed and synced to disk before the next one starts, which costs about 18 ms a row on an ordinary laptop disk: 102,000 rows took about 22 minutes to write. Reading is fast (the same 50 MB log verifies in about 2.5 seconds).

Deals

arcaeon deal records a purchase made by an agent. The buyer's agent and the seller each write the same steps (mandate, commit, pay, ship, deliver, cancel) on their own ledger. Either side, or anyone they hand both files to, can line them up with arcaeon deal dispute and get one verdict: MATCHED, MISSING, ALTERED or COULD NOT LOOK. The steps and a worked example are in docs/DEAL.md.

If you used the old packages

Before 0.9 this was thirteen packages: arcaeon-ledger, arcaeon-adapter, arcaeon-receipt, arcaeon-audit, arcaeon-mcp-vet, arcaeon-once, arcaeon-compact, arcaeon-continuity, arcaeon-baseline, arcaeon-dedup, arcaeon-distill, arcaeon-meter and arcaeon-all. Each old name gets one last release that installs arcaeon and keeps the old import and the old command working, with a warning that names the new import. Nothing breaks the day you upgrade. MIGRATION.md has the old and new import and command for each name, and which exit codes changed. shims/README.md explains how the old names forward.

License

MIT. See LICENSE.