{
  "markdown": "# Perseus Ledger\n\n<!-- mcp-name: io.github.Perseus-Computing-LLC/ledger -->\n\n> **Perseus resolves. Vault remembers. Ledger proves.**\n\n[![Test Suite](https://img.shields.io/github/actions/workflow/status/Perseus-Computing-LLC/ledger/test.yml)](https://github.com/Perseus-Computing-LLC/ledger/actions/workflows/test.yml)\n[![License: MIT](https://img.shields.io/github/license/Perseus-Computing-LLC/ledger)](./LICENSE)\n[![Release](https://img.shields.io/github/v/release/Perseus-Computing-LLC/ledger)](https://github.com/Perseus-Computing-LLC/ledger/releases)\n[![PyPI version](https://img.shields.io/pypi/v/perseus-ledger)](https://pypi.org/project/perseus-ledger/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/perseus-ledger)](https://pypi.org/project/perseus-ledger/)\n\n**Run it:** `docker pull ghcr.io/perseus-computing-llc/ledger:latest` · [Docs](https://perseus.observer/ledger/)\n\nPerseus Ledger is the verifiable event and provenance layer for autonomous systems. It records **what happened, under what authority and evidence, and whether the history can be independently verified**.\n\nIt is deliberately **not** an AI-spend dashboard. Ledger provides an append-only, hash-chained record that ties activity to its actor, boundary, evidence, configuration, action, result, and optional resource allocation. It works independently with any agent runtime, application, internal tool, or offline deployment.\n\n## What Ledger establishes\n\nFor each recorded event, the stable ledger captures the operational facts already available to the system:\n\n- **Actor and boundary** — organization, workspace, user/agent, and task type\n- **Execution configuration** — provider, model, and event metadata\n- **Action and result** — the event itself plus its immutable record hash\n- **Resource allocation** — optional token and cost attribution\n- **Evidence linkage** — external references and retained checkpoints where supplied\n- **Integrity** — an append-only cryptographic hash chain that can be verified independently\n\nThe current ingestion contract is deliberately stable during the product transition: `ledger_agent`, the `ledger` CLI, `/v1/usage`, existing database paths, and deployed integrations remain supported compatibility surfaces. Stripe is an **optional settlement adapter**, not the product boundary.\n\n## Why it matters\n\nAI systems need more than observability. They need a defensible answer to:\n\n> What did the system know, what did it do, under which model and policy, what did it consume, and can we prove it later?\n\nPerseus Ledger provides the evidentiary layer for that answer. It can work beside any agent framework, application, internal tool, offline environment, or federated deployment.\n\n### DoD and regulated-data relevance\n\n- **AI assurance:** reconstruct a recommendation from the configuration, sources, actions, and evidence available when it was made.\n- **Program and cost-data curation:** preserve source-to-output lineage, validation flags, analyst adjudications, and reproducible audit trails.\n- **Autonomous / distributed operations:** retain a verifiable record of agent state, tool activity, and resource allocation for post-operation review.\n- **Governance:** keep the human approval, correction, and policy context associated with consequential automated activity.\n\nThis is a product and architecture position, not a claim of handling CUI or satisfying a particular compliance regime.\n\n## Perseus Computing product family\n\n| Product | Question it answers |\n|---|---|\n| **Perseus Context Engine** | What verified workspace state should be available before an agent acts? |\n| **Perseus Vault** | What durable, time-valid knowledge did the system have? |\n| **Perseus Ledger** | What happened, under what authority and evidence, and can we prove it? |\n\nEach product is useful on its own and integrates through documented, runtime-neutral contracts. Ledger does not require Perseus, Vault, or any specific agent runtime.\n\n**Explore the system:** [Perseus Context Engine](https://github.com/Perseus-Computing-LLC/perseus) · [Perseus Vault](https://github.com/Perseus-Computing-LLC/perseus-vault) · [Vault MCP API reference](https://perseus.observer/vault/mcp-reference/) · [Perseus benchmarks](https://perseus.observer/benchmarks/)\n\nFor the governance bridge between durable memory decisions, recall posture, and\nhash-only Ledger evidence, see [Memory governance and Ledger provenance](docs/memory-governance-provenance.md).\nFor a copy-pasteable local setup, see [Local Perseus + Vault + Ledger integration](docs/local-perseus-vault-ledger.md).\n\n## Quick start: record a verifiable event\n\n```bash\npip install perseus-ledger\nledger demo\n# → opens the local Ledger console on http://localhost:8420\n```\n\n### Container image\n\nThe canonical GHCR image is `ghcr.io/perseus-computing-llc/ledger`:\n\n```bash\ndocker pull ghcr.io/perseus-computing-llc/ledger:latest\ndocker run --rm -p 8420:8420 ghcr.io/perseus-computing-llc/ledger:latest\n```\n\nThe `perseus-ledger` package, `ledger` CLI, and `LEDGER_*` environment variables\nare the canonical interfaces.\n\n### MCP server\n\n`ledger mcp` serves a curated MCP surface (record / query / verify /\nreceipt / health) over stdio so agents can meter themselves:\n\n```bash\npip install perseus-ledger\nclaude mcp add ledger -- ledger mcp\n```\n\nSee [docs/mcp.md](docs/mcp.md) for the tool table, action-provenance\ncontract, remote mode, and the official-registry listing.\nSee the [Evaluator Guide](docs/EVALUATOR_GUIDE.md) for the three-tier architecture\nand the boundary between context, memory, and provenance.\n\n```python\nfrom ledger_agent import Meter\n\nledger = Meter(org=\"example-organization\")\nledger.track(\n    provider=\"anthropic\",\n    model=\"example-model\",\n    task_type=\"evidence_review\",\n    workspace=\"mission-analysis\",\n    input_tokens=8200,\n    output_tokens=2400,\n)\n```\n\nThis writes an immutable event into the local SQLite-backed hash chain. Existing hosted ingestion continues to use `POST /v1/usage`; refer to [the API reference](docs/api.md) for the compatibility contract.\n\n## Integrity verification\n\nLedger integrity is not a marketing assertion. It is checked from the recorded chain and can be exposed through the existing admin verification endpoint in a controlled deployment.\n\n- [Ledger integrity](docs/ledger-integrity.md)\n- [Continuous attestation](docs/continuous-attestation.md) — admission vs. runtime evidence; attestation blocks; mechanical vs. reasoning provenance\n- [Evidence receipts](docs/evidence-receipts.md) — task-scoped, machine-readable views of hash-chained events\n- [Deterministic OSCAL projection](docs/oscal-projection.md) — bounded Assessment Results and POA&M evidence exports\n- [CUI-safe context release decisions](docs/context-release.md) — separate internal visibility from external publication\n- [API reference](docs/api.md)\n- [Schema](docs/schema.md)\n- [Reconciliation](docs/reconciliation.md) — optional provider-cost and Stripe settlement reconciliation\n\n## Transition principles\n\n1. **Runtime-neutral by design.** Ledger integrates with any agent runtime or application through its SDK and HTTP contracts; no Perseus product is required.\n2. **No broken integrations.** Legacy package names, CLI commands, state paths, `/v1` routes, deployed domains, and keys remain supported until a separately announced migration.\n3. **No billing-first story.** Resource allocation, billing, and Stripe reconciliation remain optional adapters beneath the ledger.\n4. **Evidence before claims.** The product must only claim provenance fields it actually records and can verify.\n\n## License\n\nMIT — see [LICENSE](LICENSE). © Perseus Computing LLC.\n",
  "bytes": 7633,
  "sha": "995832a4eae7190388473f731cec492b70a9abfff98d5e13a35d41661770a4de",
  "repo_slug": "perseus-computing-llc/ledger",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_perseus_computing_llc_ledger_13d32f42/readme"
}