Metadata-Version: 2.4
Name: procheiron
Version: 0.1.0
Summary: Governance and provenance layer for agent memory.
License: MIT License
        
        Copyright (c) 2026 Procheiron contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Procheiron

**A governance and provenance layer for agent memory.** Not a memory engine — the trust layer that
sits on top of one.

Memory engines (supermemory, mempalace, agentmemory, a vector DB, or plain files) answer *"what does my
agent remember?"* Procheiron answers a different question: **"can a *different* agent trust this memory,
and prove who wrote it, who reviewed it, and who authorized it?"** It is built for the case a single-agent
memory store ignores — **multiple agents sharing one governed source of truth.**

Status: **v0.1 draft, pre-release.** Conformance passes at fixture level (a second, fully fictional
deployment validates against the same Core). Honest scope discipline: nothing here claims more than the
conformance suite proves.

## Why this exists

Give an agent keys and it will use them. Give several agents a shared memory and, without governance, any
one of them can write a "fact" the others will trust — no record of who, no independent review, no way to
supersede it cleanly. Procheiron makes the trustworthy path the easy one:

- **Provenance-first lifecycle** — every memory is `draft → candidate → validated → active → superseded`.
  An `active` (trusted) record requires independent review by an actor that is *not* its author.
- **Authority, not vibes** — who may promote, review, or authorize is policy, checked by a validator and a
  policy engine, not a prompt asking nicely.
- **Provable, replayable** — a conformance suite checks that a deployment obeys the spec; a fictional
  reference deployment (`conformance/generic-vault/`) proves the same Core governs a vault it has never
  seen.

## What's in this repo

| Path | What it is |
|---|---|
| `spec/` | The v0.1 specification: `governance.md`, `memory-commons.md`, `control-plane.md`, the normative `conformance.md` MUST-list, and the Core/Profile `boundary.md`. |
| `conformance/` | `run_conformance.py` + fixtures. `generic-vault/` is a complete fictional deployment ("Meridian Atelier"); `minimal-vault/` is the 5-file minimal adopter. Run it to prove conformance. |
| `examples/minimal-adopter/` | The smallest compliant deployment — a memory commons with provenance + independent review, no heavyweight governance ladder. |
| `init/` | `procheiron_init.py` scaffolds a new deployment; `PORTING_GUIDE.md` is the step-by-step. |

## Quick start

```bash
# Install (zero runtime dependencies — stdlib-only Python):
pipx install procheiron          # or: pip install procheiron

# Scaffold a governed memory commons and validate it:
procheiron init ./my-commons
procheiron validate ./my-commons
```

From a source checkout (no install required):

```bash
# Prove the spec holds against the bundled fixtures:
python3 conformance/run_conformance.py

# Scaffold via the init script directly:
python3 init/procheiron_init.py --root ./my-commons
```

## Design choices worth knowing

- **Zero runtime dependencies.** Every tool a live deployment runs is standard-library Python. (`jsonschema`,
  `opa` etc. are used only for development/CI cross-checks, never required at runtime.) Adopt it without
  taking on a dependency tree.
- **Bring your own memory engine.** Procheiron governs records and their lifecycle; it does **not** do
  embeddings or retrieval and never will (that is the engine's job). Point it at any store.
- **Core vs Profile.** The spec is portable Core. Deployment-specific bindings (identities, paths, a git
  preservation executor, a full L0–L9 authority ladder) live in a *profile* — see `boundary.md`.

## Not in scope (by design)

No vector/retrieval engine. No recall benchmarks — that is the memory engine's axis, not ours. No claim of
"production-replicable" until a second *real* deployment passes conformance (fixture-level proof is what
exists today, and the README says exactly that).

## Roadmap (next, post first-deployment feedback)

1. **Standalone MCP server** — `memory.search/get/propose/promote` + `boot_context`, the "any agent has the
   context on hand" integration. (A working version exists but is currently coupled to its origin
   deployment's layout; the port to a `--root`-relative standalone server is the top item.)
2. ~~PyPI / `pipx` packaging and a one-command `procheiron init`.~~ **Shipped in v0.1** — `pip install procheiron`, `procheiron init`, `procheiron validate`.
3. A reference integration: Procheiron governing a third-party memory engine end to end.

## License

MIT — see `LICENSE`.
