{ "markdown": "

\n \"Procheiron\n

\n\n

Procheiron

\n\n

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

\n\n\n\n\n\n

\n \"CI\"\n \"PyPI\"\n \"Python\n \"Zero\n \"MIT\n

\n\n

\n \"Marcus\n

\n\nProcheiron is a small, dependency-free trust layer for AI agent memory. Memory tools are good at\nstoring and recalling; trust is the part nobody owns. Give several agents a shared memory and any\none of them can write a \"fact\" the others will happily build on — nobody reviewed it, nobody\napproved it, and when it turns out to be wrong there's no clean way to trace it or retire it.\n\nProcheiron adds that discipline, and enforces it with a validator rather than a convention. It\nadds no memory engine of its own — no embeddings, no ranking, no recall. Bring whatever memory\nyou already use — a vector database, a knowledge graph, a folder of markdown files. It governs\nthe records; your engine keeps doing the remembering.\n\n## Caught in the act\n\nA deployment validates clean. Then someone with write access quietly rewrites history — a past\npromotion suddenly claims a different actor:\n\n```console\n$ procheiron validate ./team-memory\nProcheiron validation (full tier): PASS\n\n$ # edit team-memory/memory/index/audit.jsonl: \"actor\": \"vera_curator\" → \"rogue_agent\"\n\n$ procheiron validate ./team-memory\nProcheiron validation (full tier): FAIL\n ERROR: audit chain: audit event 0: entry_hash mismatch — content was altered\n after it was written\n ERROR: memories.jsonl:1: active record has no corroborating promotion audit\n event — forged/hand-flipped record\n```\n\nReal output (ids shortened). You can reproduce this exact catch on your own machine in the\nnext two sections — no clone required.\n\n## Install\n\n```bash\npip install procheiron # or: pipx install procheiron — see the note below\npip install \"procheiron[crypto]\" # optional: ed25519 signing (the chain itself needs nothing)\n```\n\npipx users: pipx puts the procheiron command on your PATH but does not make\nthe package importable by your system python3. The scaffolded helpers\n(memory_propose.py, memory_promote.py, validate_minimal.py) need\nthe package, so run them with the interpreter procheiron init prints on completion\nrather than a bare python3. Everything below assumes a plain pip install in\nan active environment.\n\nUsing a coding agent? Hand it one instruction and it installs Procheiron, wires itself in over\nMCP, and runs the tamper check end to end:\n\n> Retrieve and follow the instructions at:\n> https://raw.githubusercontent.com/logotheusneuro-cpu/procheiron-core/master/INSTALL_FOR_AGENTS.md\n\nOr prove the spec from a bare checkout, no install at all: `python3 conformance/run_conformance.py`.\n\n## Break it yourself (60 seconds)\n\nThe demo above, on your own machine: scaffold a commons, write one governed memory, then rewrite\nhistory and watch the chain snap.\n\n```bash\nprocheiron init ./commons && cd commons\n\n# 1. propose a memory as alice\npython3 memory_propose.py --created-by alice --type decision --scope project \\\n --subject \"retry policy\" --statement \"Retries use exponential backoff.\" \\\n --source-path docs/decisions.md --confidence 0.9\n\n# 2. promote it — reviewed by someone who is NOT alice (self-review is refused)\npython3 memory_promote.py --memory-id --new-status active \\\n --reviewer bob --authorized-by casey --reason \"verified against the source\" \\\n --allow-unverified-reviewer\n\nprocheiron validate . # PASS\n\n# 3. rewrite history — swap the reviewer on the promotion event\nsed -i.bak 's/bob/rogue/g' memory/index/audit.jsonl\n\nprocheiron validate . # FAIL: entry_hash mismatch — content was altered\nmv memory/index/audit.jsonl.bak memory/index/audit.jsonl # put history back → PASS again\n```\n\n## Works with your agent\n\nProcheiron ships an MCP server, so any MCP-speaking agent — Claude Code, Claude Desktop, Cursor,\nCodex, and the rest — reads and writes the commons under the same rules a human faces. Four\ntools: `memory.search`, `memory.get`, `memory.propose`, `memory.promote`.\n\nClaude Code:\n\n```bash\nclaude mcp add procheiron -- procheiron mcp --root ./commons\n```\n\nAnything with an `mcpServers` config (Cursor, Claude Desktop, …) — merge, don't replace:\n\n```json\n{ \"mcpServers\": { \"procheiron\": { \"command\": \"procheiron\", \"args\": [\"mcp\", \"--root\", \"./commons\"] } } }\n```\n\nWrites are dry-run until you pass `--allow-writes`, and promotion over MCP hits the same gate as\neverywhere else: the agent that wrote a memory cannot approve it.\n\nThe server is **dual-era**: it speaks the current `2026-07-28` revision (stateless, per-request\n`_meta`, `server/discover`) *and* the older `initialize` handshake, so it works whether your\nclient has migrated yet or not. That is not just reach — with no handshake to anchor it, a\nmodern request used to be answered under legacy rules, and a memory tool replying \"nothing\nfound\" when it means \"I don't speak your protocol\" is the one answer you can't tell from a\nreal one.\n\n## How it works\n\n

\n \"Three\n

\n\n1. Every memory moves through a lifecycle: `draft → candidate → validated → active → superseded`.\n2. A memory only becomes `active` — trusted — after review by someone who did not write it.\n Self-review is refused, not discouraged:\n\n ```console\n $ python3 memory_promote.py --memory-id mem_20260709_retry_policy… --new-status active \\\n --reviewer alice --reason \"looks right to me\"\n memory_promote: REFUSED — self-review: 'alice' created this record (invalid transition §8.7)\n ```\n\n3. Every step lands in an append-only audit log whose entries are hash-chained (BLAKE2b, pure\n standard library). Editing or reordering any past event breaks the chain. Deleting from the\n end (tail truncation) is the one edit the chain alone can't see — pin the head externally\n with `--expect-head` and that's caught too (see below).\n4. Want authorship you can verify cryptographically? Install the crypto extra and sign entries\n with ed25519. A signature check that cannot run is a hard error, never a silent pass.\n\n## How it compares\n\nWhat you'd otherwise do for trust in agent memory:\n\n| | Enforced independent review | Tamper-evident history | Works with any store | Setup |\n|---|---|---|---|---|\n| Convention docs (\"agents should…\") | no — honor system | no | — | none |\n| Git history on the memory files | no | yes — unless the history itself is rewritten | the files, not your store | none |\n| Your memory engine's metadata | no — self-asserted | no | that engine only | none |\n| Full provenance stack (W3C PROV + signing infra) | possible | yes | yes | build-it-yourself |\n| **Procheiron** | **yes — validator-refused** † | **yes — plus a hash chain; a full rewrite needs an external anchor** | **yes — governs records for any store you bring** | **`pip install`; anchor + key custody for the strongest guarantee** |\n\n† Enforced against self-review and edit/reorder tampering. An insider with filesystem write\naccess can still *append* a forged promotion — closing that needs the optional signing extra with\nkeys held out of their reach. The honest line between tamper-evidence and authenticated provenance\nis spelled out in [CLAIMS.md](https://github.com/logotheusneuro-cpu/procheiron-core/blob/master/CLAIMS.md).\n\nGit already gives you tamper-evidence on the same assumption Procheiron makes (nobody rewrites the\nanchor) — the difference is the **enforced review gate** and record-level structure git has no\nnotion of. And memory engines aren't the competition: Procheiron governs the records they hold and\nwill never grow retrieval of its own.\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `procheiron init ./my-commons` | Scaffold a governed memory commons. |\n| `procheiron validate ` | Validate a deployment. Add `--expect-head ` and `--expect-lint ` to pin the chain head and the enforcement profile against external anchors; `--json` reports both current values. |\n| `procheiron scorecard ` | Trust-loop numbers: records, independent promotions, blocks caught. |\n| `procheiron keygen --actor ` | Mint an ed25519 keypair for signed authorship (needs `procheiron[crypto]`). Private key → `0600` file; public key → stdout for `known_actor_keys`. |\n| `procheiron mcp --root ` | Serve the commons to agents over MCP (stdio JSON-RPC). |\n| `procheiron conformance` | Run the conformance suite (needs a repo checkout). |\n| `procheiron version` | What it says. |\n\n## What the audit log can and can't do\n\nA candid word before you rely on it.\n\nThe hash chain makes the log **tamper-evident**: nobody can quietly edit history without breaking\nthe chain. But the chain only proves the log is internally consistent — someone with write access\nto the file can rebuild the whole thing from scratch and it will verify. The fix is to anchor the\nnewest entry hash somewhere that person can't touch (a git commit works fine) and hand it back at\ncheck time: `procheiron validate --expect-head `. Now a full rewrite is caught too.\n\nThe enforcement profile has the same problem — it lives in the same directory as everything it\ngoverns, so it can be downgraded from inside. Anchor it the same way with\n`--expect-lint `. Both anchors are checked unconditionally, and deleting what they\nanchor fails the check rather than skipping it; `procheiron validate --json` prints the current\n`audit_head` and `lint_fingerprint` so you have something to pin.\n\n
\nThe full threat model — signing, keys, and the determined insider\n\nSigning raises the bar further. With the crypto extra and a key registry (`known_actor_keys`),\nevery event from a registered actor must carry that actor's valid signature. Stripping a\nsignature fails validation; it does not slip through.\n\nAnd the honest residual: if one OS user owns the log, the keys, *and* the key registry, a\ndetermined insider can still rewrite and re-sign everything. On a single shared machine you get\ntamper-*evidence* (detectable through the external anchor), not tamper-*prevention*. To stop that\ninsider outright you need the head anchored externally and the keys held out of the writer's\nreach — a separate user, an HSM, or keyless signing.\n\n
\n\nOne more line worth drawing: all of this is **provenance, not correctness**. The gate proves who\nwrote and reviewed a record and that nobody rewrote history — it cannot make the content true. A\nreviewer can approve a wrong fact and it becomes trusted; what you get then is a clean trail to\ntrace it and a supersession path to retire it, not prevention.\n\nWe keep a running ledger of what's proven versus merely claimed in **[CLAIMS.md](https://github.com/logotheusneuro-cpu/procheiron-core/blob/master/CLAIMS.md)**,\nwith evidence cited per claim. If anything in this README ever disagrees with that file, the\nfile is right.\n\n## What's in the repo\n\n| Path | What it is |\n|---|---|\n| `spec/` | The v0.1 specification: governance, memory commons, control plane, the normative conformance MUST-list, and the Core/Profile boundary. |\n| `conformance/` | The test of record. `generic-vault/` is a complete fictional deployment (\"Meridian Atelier\"); `minimal-vault/` is the minimal adopter; plus negative fixtures that must fail. |\n| `src/procheiron/data/adopter/` | The adopter templates — the exact bytes `procheiron init` writes into a new commons, and the ones conformance runs. One copy, no mirrors. |\n| `init/` | `PORTING_GUIDE.md` for bringing Procheiron to an existing project (`procheiron init` is the scaffolder). |\n\n## Design choices\n\n- **Zero runtime dependencies.** Everything a live deployment runs is standard-library Python.\n The one optional extra is `procheiron[crypto]` for ed25519 signing; the hash chain itself needs\n nothing. (`jsonschema` and `opa` appear only as dev/CI cross-checks.)\n- **Tamper-evident by default, signed by choice.** See `chain.py` and `signing.py`.\n- **Portable core, specific profile.** The spec stays generic; deployment-specific bindings\n (identities, paths, authority ladders) live in a profile. See `spec/boundary.md`.\n- **No recall, ever.** Embeddings and retrieval are the memory engine's job. Procheiron will not\n grow a competing one.\n\n## Roadmap\n\n1. **A second, independent real deployment** passing conformance — the point where\n \"works for its authors\" becomes \"works\".\n2. **A reference adapter** showing Procheiron governing a popular third-party memory engine end\n to end.\n3. **Key-custody guidance for production** — separate-user, HSM, and keyless-signing patterns, so\n signing holds up even on a single machine.\n\nShipped so far: v0.1 brought the spec, conformance suite, CLI, and scaffolder; v0.2 brought the\ntamper-evident chain and optional signing.\n\nRunning Procheiron somewhere? Open a\n[deployment report](https://github.com/logotheusneuro-cpu/procheiron-core/issues/new?template=deployment_report.yml)\n— an independent deployment is literally roadmap item one.\n\n## FAQ\n\n**Is this a memory engine?** No. No embeddings, no ranking, no recall benchmarks, and never will.\nThe `memory.search`/`memory.get` tools are a governance filter over records (by status and scope,\nreturning only reviewed records by default) — not content retrieval. It governs the records your\nengine holds.\n\n**Can it stop a malicious insider?** Detection, yes; prevention only if you do two things — anchor\nthe chain head outside the insider's reach and keep signing keys out of their write scope. The\nsection above spells out exactly where the line is.\n\n**Why zero dependencies?** A trust layer shouldn't ask you to trust a dependency tree. Everything\na live deployment runs is standard-library Python; even the hash chain is stdlib.\n\n**How do I know if it fits my setup?** Two questions decide it. Are your writers *independently\ncontrolled* — different people, teams, or processes — or does one operator run every agent? And\ncan you operate an external head anchor plus key custody outside the writer's reach? Two yeses\nand the guarantees bind fully. Two noes and the review gate is closer to convention than\nenforcement for you — you still get a tamper-evident audit trail and a hard anti-self-review\ncheck, but the deeper promise doesn't apply to your architecture.\n\n**Is it production-ready?** Not by our own rule. Conformance passes at fixture level, but the\n\"production-replicable\" claim is reserved until a second *real* deployment — run by someone who\nisn't us — passes the suite. That's roadmap item one. What it is already good for today: a\ntamper-evident audit trail and enforced independent review on a single-team memory commons —\nexactly what the 60-second demo above shows.\n\n**What if I stop using it?** `pipx uninstall procheiron`, and keep everything: the commons is\nplain JSONL and Markdown — every record and every audit event stays readable with `cat`. No\nexport step, no lock-in.\n\n**What does the name mean?** *Procheiron* (πρόχειρον) is Greek for \"ready at hand\" — historically,\na short practical handbook of law. A fitting name for a small set of rules you keep within reach.\n\n## License\n\nMIT — see [LICENSE](https://github.com/logotheusneuro-cpu/procheiron-core/blob/master/LICENSE).\n", "bytes": 17286, "sha": "9d421214d6d4a5a8e5ad970c2aee7c0b065268ba9875185fa975208488dae354", "repo_slug": "logotheusneuro-cpu/procheiron-core", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_logotheusneuro_cpu_procheiron_5388b164/readme" }