Procheiron

Procheiron

An unreviewed memory never reaches your agents.

Who wrote this memory, who checked it — and has anyone touched it since?

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-memory

Procheiron validation (full tier): PASS

$ # edit team-memory/memory/index/audit.jsonl: "actor": "vera_curator" → "rogue_agent"

$ procheiron validate ./team-memory Procheiron 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 below

pip 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 alice

python3 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 --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 event

sed -i.bak 's/bob/rogue/g' memory/index/audit.jsonl

procheiron validate . # FAIL: entry_hash mismatch — content was altered mv 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

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:

   $ 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)

1. 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).
2. 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 . 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 . 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.

The full threat model — signing, keys, and the determined insider

Signing raises the bar further. With the crypto extra and a key registry (known_actor_keys), every event from a registered actor must carry that actor's valid signature. Stripping a signature fails validation; it does not slip through.

And the honest residual: if one OS user owns the log, the keys, *and* the key registry, a determined ins