What each piece is for, and when you need it
Each part exists because a specific thing goes wrong without it. Use the table to decide what to turn on.
| piece | the failure it prevents | you need it when |
|---|---|---|
SDK interceptor (@agent-custody/receipts, in the agent's process) | The only record of what an agent did is its own log: mutable, unsigned, written by the thing you are trying to check. | Any agent that calls tools. Turn it on first; it is a hook or a wrapped function. It is honest about being self-reported: every field is labelled claimed. |
Gateway (@agent-custody/receipts, a separate process between agent and tools, MCP servers or REST APIs described as tools) | An in-process hook can be skipped, and a policy that reads the agent's own arguments can be fed lies. | The call moves money, touches production, or handles personal data, or a security owner has to sign off on what agents may do. Denied calls never reach the tool and still produce a receipt. For tools named in precommit, the gateway logs a signed authorization before forwarding and withholds the call if the log will not take it, so the evidence exists before the side effect does. Only calls through the gateway are covered; a credential in the agent's own environment bypasses it. |
| Delegation grant and Cedar policy (used by the gateway) | "The agent was allowed to do that" is a comment in a config file, not something a human signed. | Always with the gateway. The grant is signed by the principal and names agent, tools, and validity window; the policy decides on facts the gateway fetched itself, never on the agent's claims. |
| Transparency log (local file, automatic) | A signed receipt can be deleted or replaced after the fact and nobody would know. | Always; every receipt is a leaf with an inclusion proof. Costs nothing to use. |
Remote log (log in the config, plus the log command or a hosted log) | The operator holds the local log file and can rewrite history in it. | A receipt will be shown to someone who does not trust the operator: an auditor, a counterparty, a customer, a regulator. The log's key, not yours, signs the tree heads. |
Verifier (verify and audit commands, or verifyBundle) | Trust that depends on access to the system that produced the record is not trust. | Whenever a receipt leaves the team that made it: an audit, a CI gate, acceptance by the other side of an agent-to-agent call. It needs public keys and nothing else. |
State ledger (@agent-custody/state) | Agents act on beliefs. A wrong belief spreads to other agents, cannot be traced to its source, and is overwritten rather than corrected, so "what did it believe on Tuesday" has no answer. | The agent remembers across sessions, shares memory with other agents, or takes actions whose justification you may later have to explain or undo. Every belief cites the receipt that produced it, is superseded rather than overwritten, and is retracted rather than deleted. |
| Quarantine and provenance levels (the memory server) | A self-reported write, or a value copied from an untrusted tool result, becomes something the whole fleet believes. | Any agent writes memory without going through the gateway, or writes values it got from tools. Claimed facts stay hidden until an attested party confirms them; a write can cite what the gateway itself fetched and is then verified, or refused. |
Blast radius (blast) | A belief turns out wrong and nobody can say which actions were taken on it or which later beliefs came from it. | Before any cleanup after a bad write. Every receipt records what the agent had been shown; the query walks forward to every call and derived belief, with the retraction status. |
Explain one action (agent-custody-memory explain) | An incident review starts from a refund id and a pile of logs, and the reviewer reconstructs who, why, and what else by hand. | Any time someone asks "what is this action and can I trust the answer". From a receipt id: who acted, who authorized it, what was allowed, what the agent saw, what it did, why, the evidence, whether it verifies, what depended on it, and what needs reversal, as text or as one signed pack with every receipt inside. |
| Certified forget, retention, legal hold (the memory server) | A deletion demand is answered with "we think it's gone". Retention is a policy document, not something that runs. A hold is an email. | Personal data in memory, a regulator or customer with a deletion right, or a matter under litigation. Forget erases the value from the ledger and every store, checks each store's search that it is really gone, and the receipt is the certificate; sweeps run retention as receipted calls; a hold refuses both until released; pack hands counsel the whole story of a fact as one signed artefact. Forget reaches the ledger and the adapted stores and records what each answered; caches, model context, backups, and warehouses are outside it. |
| Write-through to Mem0 and Zep | The team already runs a retrieval store, and governing memory would mean replacing it. | Any existing Mem0 or Zep deployment. The ledger sits under it: writes land in the store with custody metadata, retractions and forgets reach it, and recall stays where it was. |
| Eval harness | "Our memory is governed" is a claim with no number behind it. | Before a design review or a vendor comparison. Scripted incidents score stale reads, contradictions, and blast radius for this ledger and for any store behind the same interface. |
The rule of thumb: record everything with the SDK, enforce the consequential calls with the gateway, log remotely once a receipt has an audience outside the team, put beliefs in the ledger the moment memory outlives a session, and turn on quarantine, forget, and holds the moment that memory holds anything about a person.