Procheiron

[Procheiron mark: an open hand holding a flame, struck as a Roman coin]

Procheiron

An unreviewed memory never reaches your agents.
Who wrote this memory, who checked it — and has anyone touched it since?

[CI] [PyPI] [Python 3.9+] [Zero runtime dependencies] [MIT license]

[Marcus Aurelius — the Stoic emperor who kept his principles procheiron, 'ready at hand']

Procheiron is a small, dependency-free trust layer for AI agent memory. Memory tools are good at storing and recalling; trust is the part nobody owns. Give several agents a shared memory and any one of them can write a "fact" the others will happily build on — nobody reviewed it, nobody approved it, and when it turns out to be wrong there's no clean way to trace it or retire it.

Procheiron adds that discipline, and enforces it with a validator rather than a convention. It adds no memory engine of its own — no embeddings, no ranking, no recall. Bring whatever memory you already use — a vector database, a knowledge graph, a folder of markdown files. It governs the records; your engine keeps doing the remembering.

Caught in the act

A deployment validates clean. Then someone with write access quietly rewrites history — a past promotion suddenly claims a different actor:

$ procheiron validate ./team-memoryProcheiron validation (full tier): PASS
$ # edit team-memory/memory/index/audit.jsonl:  "actor": "vera_curator" → "rogue_agent"
$ procheiron validate ./team-memoryProcheiron validation (full tier): FAIL  ERROR: audit chain: audit event 0: entry_hash mismatch — content was altered         after it was written  ERROR: memories.jsonl:1: active record has no corroborating promotion audit         event — forged/hand-flipped record

_{Real output (ids shortened). You can reproduce this exact catch on your own machine in the next two sections — no clone required.}

Install

pip install procheiron             # or: pipx install procheiron — see the note belowpip install "procheiron[crypto]"   # optional: ed25519 signing (the chain itself needs nothing)

_{pipx users: pipx puts the procheiron command on your PATH but does not make the package importable by your system python3. The scaffolded helpers (memory_propose.py, memory_promote.py, validate_minimal.py) need the package, so run them with the interpreter procheiron init prints on completion rather than a bare python3. Everything below assumes a plain pip install in an active environment.}

Using a coding agent? Hand it one instruction and it installs Procheiron, wires itself in over MCP, and runs the tamper check end to end:

Retrieve and follow the instructions at: https://raw.githubusercontent.com/logotheusneuro-cpu/procheiron-core/master/INSTALL_FOR_AGENTS.md

Or prove the spec from a bare checkout, no install at all: python3 conformance/run_conformance.py.

Break it yourself (60 seconds)

The demo above, on your own machine: scaffold a commons, write one governed memory, then rewrite history and watch the chain snap.

procheiron init ./commons && cd commons
# 1. propose a memory as alicepython3 memory_propose.py --created-by alice --type decision --scope project \    --subject "retry policy" --statement "Retries use exponential backoff." \    --source-path docs/decisions.md --confidence 0.9
# 2. promote it — reviewed by someone who is NOT alice (self-review is refused)python3 memory_promote.py --memory-id <id printed by step 1> --new-status active \    --reviewer bob --authorized-by casey --reason "verified against the source" \    --allow-unverified-reviewer
procheiron validate .        # PASS
# 3. rewrite history — swap the reviewer on the promotion eventsed -i.bak 's/bob/rogue/g' memory/index/audit.jsonl
procheiron validate .        # FAIL: entry_hash mismatch — content was alteredmv memory/index/audit.jsonl.bak memory/index/audit.jsonl    # put history back → PASS again

Works with your agent

Procheiron ships an MCP server, so any MCP-speaking agent — Claude Code, Claude Desktop, Cursor, Codex, and the rest — reads and writes the commons under the same rules a human faces. Four tools: memory.search, memory.get, memory.propose, memory.promote.

Claude Code:

claude mcp add procheiron -- procheiron mcp --root ./commons

Anything with an mcpServers config (Cursor, Claude Desktop, …) — merge, don't replace:

{ "mcpServers": { "procheiron": { "command": "procheiron", "args": ["mcp", "--root", "./commons"] } } }

Writes are dry-run until you pass --allow-writes, and promotion over MCP hits the same gate as everywhere else: the agent that wrote a memory cannot approve it.

The server is dual-era: it speaks the current 2026-07-28 revision (stateless, per-request _meta, server/discover) and the older initialize handshake, so it works whether your client has migrated yet or not. That is not just reach — with no handshake to anchor it, a modern request used to be answered under legacy rules, and a memory tool replying "nothing found" when it means "I don't speak your protocol" is the one answer you can't tell from a real one.

How it works

[Three scenes: one agent writes a record into a shared store; a different agent inspects it and stamps it with a green check; the approved records are joined in a chain — and when an attacker tries to swap one, the chain link snaps and an alarm fires.]

1. Every memory moves through a lifecycle: draft → candidate → validated → active → superseded.

2. A memory only becomes active — trusted — after review by someone who did not write it. Self-review is refused, not discouraged:

   console

   $ python3 memory_promote.py --memory-id mem_20260709_retry_policy… --new-status active \      --reviewer alice --reason "looks right to me"memory_promote: REFUSED — self-review: 'alice' created this record (invalid transition §8.7)

3. Every step lands in an append-only audit log whose entries are hash-chained (BLAKE2b, pure standard library). Editing or reordering any past event breaks the chain. Deleting from the end (tail truncation) is the one edit the chain alone can't see — pin the head externally with --expect-head and that's caught too (see below).

4. Want authorship you can verify cryptographically? Install the crypto extra and sign entries with ed25519. A signature check that cannot run is a hard error, never a silent pass.

How it compares

What you'd otherwise do for trust in agent memory:

_{† Enforced against self-review and edit/reorder tampering. An insider with filesystem write access can still append a forged promotion — closing that needs the optional signing extra with keys held out of their reach. The honest line between tamper-evidence and authenticated provenance is spelled out in CLAIMS.md.}

Git already gives you tamper-evidence on the same assumption Procheiron makes (nobody rewrites the anchor) — the difference is the enforced review gate and record-level structure git has no notion of. And memory engines aren't the competition: Procheiron governs the records they hold and will never grow retrieval of its own.

Commands

What the audit log can and can't do

A candid word before you rely on it.

The hash chain makes the log tamper-evident: nobody can quietly edit history without breaking the chain. But the chain only proves the log is internally consistent — someone with write access to the file can rebuild the whole thing from scratch and it will verify. The fix is to anchor the newest entry hash somewhere that person can't touch (a git commit works fine) and hand it back at check time: procheiron validate --expect-head <hex>. Now a full rewrite is caught too.

The enforcement profile has the same problem — it lives in the same directory as everything it governs, so it can be downgraded from inside. Anchor it the same way with --expect-lint <fingerprint>. Both anchors are checked unconditionally, and deleting what they anchor fails the check rather than skipping it; procheiron validate --json prints the current audit_head and lint_fingerprint so you have something to pin.

One more line worth drawing: all of this is provenance, not correctness. The gate proves who wrote and reviewed a record and that nobody rewrote history — it cannot make the content true. A reviewer can approve a wrong fact and it becomes trusted; what you get then is a clean trail to trace it and a supersession path to retire it, not prevention.

We keep a running ledger of what's proven versus merely claimed in CLAIMS.md, with evidence cited per claim. If anything in this README ever disagrees with that file, the file is right.

What's in the repo

Design choices

• Zero runtime dependencies. Everything a live deployment runs is standard-library Python. The one optional extra is procheiron[crypto] for ed25519 signing; the hash chain itself needs nothing. (jsonschema and opa appear only as dev/CI cross-checks.)
• Tamper-evident by default, signed by choice. See chain.py and signing.py.
• Portable core, specific profile. The spec stays generic; deployment-specific bindings (identities, paths, authority ladders) live in a profile. See spec/boundary.md.
• No recall, ever. Embeddings and retrieval are the memory engine's job. Procheiron will not grow a competing one.

Roadmap

1. A second, independent real deployment passing conformance — the point where "works for its authors" becomes "works".
2. A reference adapter showing Procheiron governing a popular third-party memory engine end to end.
3. Key-custody guidance for production — separate-user, HSM, and keyless-signing patterns, so signing holds up even on a single machine.

Shipped so far: v0.1 brought the spec, conformance suite, CLI, and scaffolder; v0.2 brought the tamper-evident chain and optional signing.

Running Procheiron somewhere? Open a deployment report — an independent deployment is literally roadmap item one.

FAQ

Is this a memory engine? No. No embeddings, no ranking, no recall benchmarks, and never will. The memory.search/memory.get tools are a governance filter over records (by status and scope, returning only reviewed records by default) — not content retrieval. It governs the records your engine holds.

Can it stop a malicious insider? Detection, yes; prevention only if you do two things — anchor the chain head outside the insider's reach and keep signing keys out of their write scope. The section above spells out exactly where the line is.

Why zero dependencies? A trust layer shouldn't ask you to trust a dependency tree. Everything a live deployment runs is standard-library Python; even the hash chain is stdlib.

How do I know if it fits my setup? Two questions decide it. Are your writers independently controlled — different people, teams, or processes — or does one operator run every agent? And can you operate an external head anchor plus key custody outside the writer's reach? Two yeses and the guarantees bind fully. Two noes and the review gate is closer to convention than enforcement for you — you still get a tamper-evident audit trail and a hard anti-self-review check, but the deeper promise doesn't apply to your architecture.

Is it production-ready? Not by our own rule. Conformance passes at fixture level, but the "production-replicable" claim is reserved until a second real deployment — run by someone who isn't us — passes the suite. That's roadmap item one. What it is already good for today: a tamper-evident audit trail and enforced independent review on a single-team memory commons — exactly what the 60-second demo above shows.

What if I stop using it? pipx uninstall procheiron, and keep everything: the commons is plain JSONL and Markdown — every record and every audit event stays readable with cat. No export step, no lock-in.

What does the name mean? Procheiron (πρόχειρον) is Greek for "ready at hand" — historically, a short practical handbook of law. A fitting name for a small set of rules you keep within reach.

License

MIT — see LICENSE.