@agent-custody/state 0.1.5 → 0.1.7

package/README.md

@@ -22,7 +22,7 @@ ledger.retract({ factId: a.fact.factId, actor: "user:admin", reason: "poisoned b
 ledger.asOf({ validAt: "2026-09-01T00:00:00Z", txAt: "2026-09-01T00:00:00Z" });
 ```
 
-Five runnable examples, all executed by the test suite. [05-blast-radius.ts](examples/05-blast-radius.ts) walks from a retracted belief to everything that relied on it. [04-evals.ts](examples/04-evals.ts) scores the ledger and a naive store on the same memory incidents. [03-memory-behind-the-gateway.ts](examples/03-memory-behind-the-gateway.ts) runs the memory server as the gateway's upstream. [01-ledger.ts](examples/01-ledger.ts) walks through a wrong write and its undo. [02-receipt-to-belief.ts](examples/02-receipt-to-belief.ts) runs the whole loop with the receipts package: a tool call gets a signed receipt, the receipt is verified, the belief taken from it is recorded citing the receipt, and later retracted. Run them with `node examples/<file>` from this directory, after `bun run build` at the repository root.
+Six runnable examples, all executed by the test suite. [06-actions-on-beliefs.ts](examples/06-actions-on-beliefs.ts) puts memory and a payments API behind one gateway and finds the refund in a belief's blast radius. [05-blast-radius.ts](examples/05-blast-radius.ts) walks from a retracted belief to everything that relied on it. [04-evals.ts](examples/04-evals.ts) scores the ledger and a naive store on the same memory incidents. [03-memory-behind-the-gateway.ts](examples/03-memory-behind-the-gateway.ts) runs the memory server as the gateway's upstream. [01-ledger.ts](examples/01-ledger.ts) walks through a wrong write and its undo. [02-receipt-to-belief.ts](examples/02-receipt-to-belief.ts) runs the whole loop with the receipts package: a tool call gets a signed receipt, the receipt is verified, the belief taken from it is recorded citing the receipt, and later retracted. Run them with `node examples/<file>` from this directory, after `bun run build` at the repository root.
 
 ## The memory server
 
@@ -45,10 +45,14 @@ In the gateway's config, the memory server is the upstream, and the grant names
 | `memory.confirm` | lifts a quarantined fact to attested; accepted only through the gateway | `factId` |
 | `memory.retract` | undoes a belief, keeping it visible to questions about the past | `factId`, `reason` |
 | `memory.forget` | erases the value from the ledger and every store, keeping the digest; the receipt is the certificate | `factId`, `reason` |
+| `memory.hold`, `memory.release` | legal hold: while it stands the fact cannot be forgotten by request or sweep | `factId`, `reason` |
+| `memory.sweep` | retention: forget what was learned before an instant, in a space or all, skipping held facts, reaching every store | `before`, `space`, `reason` |
 | `memory.get` | one fact by id in any state, for the gateway's policy lookups | `factId` |
 | `memory.history` | every event that touched a fact | `factId` |
 
-**Quarantine.** Every fact carries a provenance. A write that came through the gateway is `attested`: its actor is the agent named in a human-signed grant and its receipt exists. A write that arrived any other way is `claimed`, and claimed facts are quarantined: `memory.read` leaves them out unless the caller asks for `includeClaimed`, and the policy can refuse that. `memory.confirm`, accepted only through the gateway, lifts a claimed fact to attested with its own receipt and transaction time, so "was this fact still in quarantine on Tuesday" is answerable. A tool result an SDK-only agent wrote down cannot become something the rest of the fleet believes until an attested party says so. Over stdio the server has one client; shared over HTTP, below, gateways and direct writers feed one ledger and quarantine does its job.
+**Quarantine.** Every fact carries a provenance: `claimed`, `attested`, or `verified`. A write that came through the gateway is `attested`: its actor is the agent named in a human-signed grant and its receipt exists. A write that arrived any other way is `claimed`, and claimed facts are quarantined: `memory.read` leaves them out unless the caller asks for `includeClaimed`, and the policy can refuse that. `memory.confirm`, accepted only through the gateway, lifts a claimed fact to attested with its own receipt and transaction time, so "was this fact still in quarantine on Tuesday" is answerable. A tool result an SDK-only agent wrote down cannot become something the rest of the fleet believes until an attested party says so. Over stdio the server has one client; shared over HTTP, below, gateways and direct writers feed one ledger and quarantine does its job.
+
+**Value-level quarantine.** An attested write still carries whatever value the agent chose to write. When the agent can say where a value came from, the gateway's own observation decides. A `memory.write` may name `evidence: { fact, path }`, a fact the gateway fetched itself for this call through its fact-lookup mechanism (a CRM record, say) and optionally a field in it. The memory server compares the value with the observation: equal, and the fact is written as `verified`, the third provenance level, where both the actor and the value are vouched for by something other than the agent; different, and the write is refused. A policy can require evidence for a space (`context.args has evidence`), and `memory.read` with `requireVerified` returns only verified facts. The test suite runs this with a CRM lookup behind the same gateway as the memory server.
 
 **Policy over the fact being changed.** The gateway can look up the fact a write supersedes or a retraction targets before deciding, through its fact-lookup mechanism and the `memory.get` tool, and the policy then sees that fact's space, actor, and provenance as observed facts. This is the second half of trust tiers: a self-reported note in the org space can be superseded by anyone the grant allows, while an attested org fact cannot be displaced or retracted except by whoever the policy names. In the gateway config:
 
@@ -70,17 +74,19 @@ The lookup for writes is optional, so a write that supersedes nothing needs no l
 
 **Shared over HTTP.** `agent-custody-memory serve --ledger ./ledger.jsonl --http --port 8790 --token-env MEMORY_TOKEN` serves the same tools over Streamable HTTP, so several gateways, one per agent host, and, with `--allow-direct`, SDK-only agents share one ledger. That is the deployment quarantine was built for: writes arriving through a gateway are attested, writes arriving directly are claimed and hidden until a gateway confirms them, and the ledger tells them apart. A gateway reaches it with `"upstream": { "url": "http://127.0.0.1:8790/mcp", "tokenEnv": "MEMORY_TOKEN" }` in its config. Bind wider than loopback only behind the token. The test suite runs exactly this: one gateway writer, one direct writer, one ledger.
 
-Trust tiers are Cedar policies over the space and, through `includeClaimed`, over quarantine: `permit(principal, action == Action::"memory.write", resource) when { context.args.space == "team:support" };` lets this agent write team memory and nothing else. A read's receipt carries, as `observed`, the exact facts returned, so the ids the agent relied on are already on the record.
+[Writing policies](../receipts/docs/policies.md#policies-for-memory) in the receipts guide has six tested policies for the memory tools, from confining an agent to its team's space to a complete support-agent policy. Trust tiers are Cedar policies over the space and, through `includeClaimed`, over quarantine: `permit(principal, action == Action::"memory.write", resource) when { context.args.space == "team:support" };` lets this agent write team memory and nothing else. A read's receipt carries, as `observed`, the exact facts returned, so the ids the agent relied on are already on the record.
 
 `--allow-direct` lets the server take calls without a gateway; then `source.receiptId` is null and `actor` is whatever the caller said, recorded as such. [examples/03-memory-behind-the-gateway.ts](examples/03-memory-behind-the-gateway.ts) runs the whole loop, including a denied write and a retraction that cites its own receipt.
 
 ## Certified forget
 
-A deletion demand is different from a correction. Retract keeps the record; forget erases the value. `memory.forget` removes the fact's value from the ledger file itself, replacing it with the value's digest so the ledger can still prove what it held without holding it, stops believing the fact, and removes it from every store behind the server. The result says exactly what happened: erased from the ledger, removed from which stores, still held by which, with the digest, the actor, and the reason.
+A deletion demand is different from a correction. Retract keeps the record; forget erases the value. `memory.forget` removes the fact's value from the ledger file itself, stops believing the fact, and removes it from every store behind the server. What it keeps in place of the value is a choice, recorded on the event as `digestKind`: a plain `sha256` of the value, which lets the ledger prove what it erased but is guessable for short values such as an email by anyone holding the file; an `hmac-sha256` under a forget key the server holds outside the file (`serve --forget-key-env NAME`), which proves the same to anyone shown the key and nothing to anyone else; or `none`, with `keepDigest: false`, for the case where counsel wants nothing derived from the value retained. Use the keyed form unless you have a reason not to. The result says exactly what happened: erased from the ledger, removed from which stores, still held by which, with the digest, the actor, and the reason.
+
+**Retention and legal hold.** `memory.sweep` forgets every fact the ledger learned of before an instant, in one space or all, and removes each from every store; it is retention as a receipted call, with the receipt as the record of what was erased. Retention windows live in the server: `serve --retention 'org=P365D,team:*=P90D,user:*=P30D'`, ISO 8601 durations by space pattern, and a sweep with no `before` uses them per space. To run it on a schedule without a daemon, `agent-custody-memory sweep --via retention-gateway.json --reason "quarterly retention"` spawns that gateway and calls `memory.sweep` through it, so the sweep runs as the principal named in the gateway's grant, a retention job with the single scope `memory.sweep`, and its receipt records when retention ran, by whom, what it erased, and what a hold kept. Any cron, systemd timer, or CI schedule drives that one command. `memory.hold` puts a legal hold on a fact: while it stands, neither a deletion request nor a sweep can forget it, and `memory.release` lifts it. Holds and releases are events with actor, reason, and receipt, so the history of a fact shows the hold as plainly as the write. `agent-custody-memory sweep --ledger ... --before ... --reason ...` runs retention on the ledger file alone, for ledgers with no stores behind them.
 
 The certificate is the receipt. Through the gateway, `memory.forget` is a receipted call whose result the gateway observed, so the signed, logged receipt records that the erasure happened, who asked for it, and what the stores answered. Hand that receipt to whoever demanded the deletion; anyone with the gateway's public key can verify it.
 
-What forget does not reach, and the docs will not pretend otherwise: receipts. The receipt that recorded the original write carries the value in its request arguments, and the receipts of reads carry it in their results; they are signed and in a Merkle log, so they cannot be edited. Erasure from the receipt log is a retention policy on the log, and selective redaction of receipts is on the receipts roadmap.
+Receipts are the other place a value lives: the receipt that recorded the write carries it in its request arguments, and the receipts of reads carry it in their results, signed and in a Merkle log. The receipts package's `prune` command is retention for the log: it replaces older leaves with their hashes, so every root and every proof still verifies while the content is gone, and removes the pruned receipts' bundle files. Run it on the same schedule as the sweep.
 
 ## Blast radius
 
@@ -101,6 +107,8 @@ retracted at 2026-09-07T10:12:04.118Z by support-agent: CRM sync bug: account is
   acct:42 support_tier = "priority"  fact e77d…  STILL BELIEVED
 ```
 
+With the gateway fronting several upstreams, memory and the tools the agent acts with, the radius reaches the actions too: a refund issued after the agent read a belief carries that belief's id and is listed. [examples/06-actions-on-beliefs.ts](examples/06-actions-on-beliefs.ts) shows it.
+
 It is an upper bound by design: a call made after the agent had seen the fact is in the radius whether or not the agent used it, because no receipt can prove what a model attended to. What it never misses is the thing that matters, a downstream action or belief that did depend on the fact. [examples/05-blast-radius.ts](examples/05-blast-radius.ts) runs the whole loop.
 
 ## Write-through to the stores you already use
@@ -154,7 +162,7 @@ The ledger refuses to supersede a fact that is unknown, already superseded, or r
 src/ledger.ts   the fact record, the two event kinds, as-of queries, supersession, retraction, JSONL persistence
 src/server.ts   the ledger as MCP tools; source and actor taken from the gateway's _meta
 src/http.ts     the memory server over Streamable HTTP with bearer auth, for a shared ledger
-src/cli.ts      agent-custody-memory serve (stdio or --http), blast
+src/cli.ts      agent-custody-memory serve (stdio or --http, with --retention and --forget-key-env), sweep (ledger-only or --via a gateway), blast
 src/blast.ts    blast radius: from receipts' consumed facts and the ledger's source receipts, forward
 src/stores.ts   write-through adapters: Mem0 and Zep, and the Store interface for others
 src/evals.ts    the memory-mutation harness: scenarios, scoring, report
@@ -171,6 +179,10 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 
 - Bitemporal fact ledger with supersession, retraction, as-of and history queries, persisted as JSONL.
 - The memory server: the ledger as MCP tools behind the receipts gateway, with the source receipt id and the attested actor supplied by the gateway, policy over spaces, and a denial receipt for every refused write.
+- Forget digests are keyed under a server-held secret, or absent on request, so an erased value cannot be guessed back from the file.
+- Retention windows per space in the server, sweeps that default to them, and a `sweep --via` trigger that runs retention through a gateway as a named principal, on any timer.
+- Retention and legal hold: a receipted sweep forgets what was learned before an instant and reaches the stores; a hold refuses forget and sweep until released, as events on the fact's history.
+- Value-level quarantine: a write may cite a fact the gateway fetched itself; the value must match it and the fact is then `verified`, the provenance level above attested, or the write is refused.
 - Attested executions: with a key, the memory server signs its results for the gateway's receipt, so a verifier holding its public key sees memory calls as attested.
 - The memory server over HTTP: one ledger shared by several gateways and direct writers, bearer-token auth, quarantine live.
 - Certified forget: `memory.forget` erases a value from the ledger file keeping its digest, stops believing it, removes it from every store, and reports exactly what happened; the gateway's receipt of that call is the certificate.
@@ -182,8 +194,8 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 
 **Next, in the order it pays off**
 
-1. Value-level quarantine: a value that came from untrusted tool output stays quarantined even when the actor is attested, until a second source or a human agrees.
-2. Retention windows and legal hold on the ledger: forget on a schedule, and a hold that refuses forget for named facts until lifted.
-3. A gateway with several upstreams under one grant, so memory and the tools an agent acts with share a session and blast radius reaches the emails sent, not only the beliefs written.
-4. The memory tools from Python, through the sidecar, so SDK-only Python agents can write claimed facts to a shared ledger.
+1. A storage interface for the ledger with SQLite as the first alternative to JSONL, for durability, concurrent readers, and indexed queries at scale; JSONL stays the default and the auditable export. [Issue #1](https://github.com/ch4r10t33r/agent-custody/issues/1).
+2. Write-through adapters for Letta, LangMem, and Cognee, one per user who asks. [Issue #4](https://github.com/ch4r10t33r/agent-custody/issues/4).
+3. The eval harness as a CLI with customer scenario files and a signed report. [Issue #5](https://github.com/ch4r10t33r/agent-custody/issues/5).
+4. The hosted plane, behind early access: tenanted log, then memory, then reports and a control plane. [Issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 

package/dist/cli.js

@@ -5,14 +5,43 @@ import { createMemoryServer, serveStdio } from "./server.js";
 import { blastRadius, formatBlastRadius, loadReceipts } from "./blast.js";
 import { serveMemoryHttp } from "./http.js";
 import { loadPrivateKey } from "@agent-custody/receipts";
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+/** The forget key from an environment variable, when named; a named but unset variable is an error at startup. */
+function forgetKeyFrom(envName) {
+    if (!envName)
+        return {};
+    const v = process.env[envName];
+    if (!v)
+        throw new Error(`forget key: environment variable ${envName} is not set`);
+    return { forgetKey: v };
+}
+/** "org=P365D,team:*=P90D" into retention windows. */
+function parseRetention(spec) {
+    const out = {};
+    for (const part of spec.split(",")) {
+        const [pattern, duration] = part.split("=").map((x) => x.trim());
+        if (!pattern || !duration)
+            throw new Error(`retention: expected space=duration, got "${part}"`);
+        out[pattern] = duration;
+    }
+    return out;
+}
 const USAGE = `agent-custody-memory <command>
 
-  serve --ledger <ledger.jsonl> [--allow-direct] [--key <memory.key>]
+  serve --ledger <ledger.jsonl> [--allow-direct] [--key <memory.key>] [--forget-key-env NAME] [--retention 'org=P365D,team:*=P90D']
+                                                   --forget-key-env names a secret kept outside the ledger; forgotten values then leave an HMAC, not a guessable hash.
                                                    the memory server over stdio; run it as the receipts gateway's upstream.
                                                    --key signs every result for its receipt, so executions verify as attested by this server.
                                                    By default it refuses calls that did not come through the gateway.
   serve --ledger <ledger.jsonl> --http [--port 8790] [--host 127.0.0.1] [--token-env NAME] [--allow-direct]
                                                    the same server shared over HTTP: several gateways, one ledger
+  sweep --via <gateway.json> --reason <text> [--before <ISO instant>] [--space <space>] [--no-digest]
+                                                   retention as a receipted call: runs memory.sweep through that gateway, as the principal in its grant.
+                                                   Without --before, the memory server's --retention windows decide. Put this on a timer.
+  sweep --ledger <ledger.jsonl> --before <ISO instant> [--space <space>] --reason <text> [--actor <id>] [--forget-key-env NAME] [--no-digest]
+                                                   retention on the ledger file alone, for ledgers with no gateway or stores in front of them.
   blast --ledger <ledger.jsonl> --receipts <dir> --fact <factId> [--json]
                                                    everything that relied on a fact: later calls, derived beliefs, and whether it was retracted
 `;
@@ -20,23 +49,53 @@ async function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
         case "serve": {
-            const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, "allow-direct": { type: "boolean", default: false }, http: { type: "boolean", default: false }, port: { type: "string", default: "8790" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, key: { type: "string" } } });
+            const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, "allow-direct": { type: "boolean", default: false }, http: { type: "boolean", default: false }, port: { type: "string", default: "8790" }, host: { type: "string", default: "127.0.0.1" }, "token-env": { type: "string" }, key: { type: "string" }, "forget-key-env": { type: "string" }, retention: { type: "string" } } });
             if (!values.ledger)
                 throw new Error("serve needs --ledger");
-            const ledger = new Ledger(values.ledger);
+            const ledger = new Ledger(values.ledger, forgetKeyFrom(values["forget-key-env"]));
             const identity = values.key ? loadPrivateKey(values.key) : undefined;
+            const retention = values.retention ? parseRetention(values.retention) : undefined;
+            const common = { requireGateway: !values["allow-direct"], ...(identity ? { identity } : {}), ...(retention ? { retention } : {}) };
             if (values.http) {
                 const token = values["token-env"] ? process.env[values["token-env"]] : undefined;
                 if (values["token-env"] && !token)
                     throw new Error(`serve: environment variable ${values["token-env"]} is not set`);
-                const running = await serveMemoryHttp(ledger, { port: Number(values.port), host: values.host, requireGateway: !values["allow-direct"], ...(token ? { tokens: [token] } : {}), ...(identity ? { identity } : {}) });
+                const running = await serveMemoryHttp(ledger, { port: Number(values.port), host: values.host, ...common, ...(token ? { tokens: [token] } : {}) });
                 console.error(`agent-custody-memory: ${running.url} ledger=${values.ledger} events=${ledger.size} ${token ? "bearer token required" : "open"} ${values["allow-direct"] ? "direct calls allowed" : "gateway calls only"}`);
                 await new Promise((resolve) => process.once("SIGINT", resolve));
                 await running.close();
                 return 0;
             }
             console.error(`agent-custody-memory: ledger=${values.ledger} events=${ledger.size} ${values["allow-direct"] ? "direct calls allowed" : "gateway calls only"}`);
-            await serveStdio(createMemoryServer(ledger, { requireGateway: !values["allow-direct"], ...(identity ? { identity } : {}) }));
+            await serveStdio(createMemoryServer(ledger, common));
+            return 0;
+        }
+        case "sweep": {
+            const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, via: { type: "string" }, before: { type: "string" }, space: { type: "string" }, reason: { type: "string" }, actor: { type: "string", default: "cli" }, "forget-key-env": { type: "string" }, "no-digest": { type: "boolean", default: false } } });
+            if (values.via) {
+                // Retention as a receipted call: spawn the gateway from its config and call memory.sweep through it, so the
+                // sweep runs as the principal named in that gateway's grant and its receipt is the record.
+                if (!values.reason)
+                    throw new Error("sweep --via needs --reason");
+                const gatewayCli = fileURLToPath(import.meta.resolve("@agent-custody/receipts/cli"));
+                const client = new Client({ name: "agent-custody-memory-sweep", version: "0" });
+                await client.connect(new StdioClientTransport({ command: process.execPath, args: [gatewayCli, "gateway", "--config", values.via], stderr: "inherit" }));
+                try {
+                    const r = await client.callTool({ name: "memory.sweep", arguments: { reason: values.reason, ...(values.before ? { before: new Date(values.before).toISOString() } : {}), ...(values.space ? { space: values.space } : {}), ...(values["no-digest"] ? { keepDigest: false } : {}) } });
+                    const text = (r.content.find((c) => c.type === "text")?.text) ?? "";
+                    console.log(text);
+                    return r.isError ? 1 : 0;
+                }
+                finally {
+                    await client.close();
+                }
+            }
+            if (!values.ledger || !values.before || !values.reason)
+                throw new Error("sweep needs --ledger, --before, and --reason, or --via <gateway.json> --reason");
+            const r = new Ledger(values.ledger, forgetKeyFrom(values["forget-key-env"])).sweep({ before: new Date(values.before).toISOString(), ...(values.space ? { space: values.space } : {}), actor: values.actor, reason: values.reason, ...(values["no-digest"] ? { keepDigest: false } : {}) });
+            console.log(`forgot ${r.forgotten.length} fact(s); ${r.held.length} on hold, kept`);
+            for (const f of r.forgotten)
+                console.log(`  ${f.factId}  ${f.digestKind}${f.valueDigest ? ` ${f.valueDigest.slice(0, 12)}` : ""}`);
             return 0;
         }
         case "blast": {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Ledger } from "./ledger.ts";
-export type { AsOf, AssertEvent, AssertInput, ConfirmEvent, ConfirmInput, Fact, FactProvenance, ForgetEvent, ForgetInput, LedgerEvent, RetractEvent, RetractInput, Source } from "./ledger.ts";
-export { AGENT_META_KEY, FACTS_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, serveStdio } from "./server.ts";
+export type { AsOf, AssertEvent, AssertInput, ConfirmEvent, ConfirmInput, Fact, FactProvenance, DigestKind, ForgetEvent, ForgetInput, HoldEvent, HoldInput, LedgerEvent, SweepInput, RetractEvent, RetractInput, Source } from "./ledger.ts";
+export { AGENT_META_KEY, FACTS_META_KEY, OBSERVED_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, durationMs, retentionCutoff, serveStdio } from "./server.ts";
 export type { MemoryServerOptions } from "./server.ts";
 export { SCENARIOS, formatReport, runAll, runScenario } from "./evals.ts";
 export type { MemoryUnderTest, Op, Report, Scenario, ScenarioScore } from "./evals.ts";

package/dist/index.js

@@ -1,6 +1,6 @@
 // Public surface of @agent-custody/state.
 export { Ledger } from "./ledger.js";
-export { AGENT_META_KEY, FACTS_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, serveStdio } from "./server.js";
+export { AGENT_META_KEY, FACTS_META_KEY, OBSERVED_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, durationMs, retentionCutoff, serveStdio } from "./server.js";
 export { SCENARIOS, formatReport, runAll, runScenario } from "./evals.js";
 export { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.js";
 export { factMetadata, factText, mem0Store, zepStore } from "./stores.js";

package/dist/ledger.d.ts

@@ -3,11 +3,14 @@ export interface Source {
     receiptId: string | null;
 }
 /**
- * How far the write can be trusted. attested: it came through the receipts gateway, so the actor is the agent named in
- * a human-signed grant and the receipt exists. claimed: it came from somewhere that only says who it is. A claimed
- * fact is quarantined: the memory server does not return it by default until an attested party confirms it.
+ * How far the write can be trusted.
+ *  - claimed:  it came from somewhere that only says who it is. Quarantined: not returned by default until confirmed.
+ *  - attested: it came through the receipts gateway, so the actor is the agent named in a human-signed grant and the
+ *              receipt exists. The value is still what the agent said.
+ *  - verified: attested, and the value equals what the gateway itself fetched from the source system for this call.
+ *              The actor and the value are both vouched for by something other than the agent.
  */
-export type FactProvenance = "attested" | "claimed";
+export type FactProvenance = "claimed" | "attested" | "verified";
 export interface Fact {
     factId: string;
     subject: string;
@@ -19,9 +22,10 @@ export interface Fact {
     actor: string;
     source: Source;
     provenance: FactProvenance;
-    /** present once the value has been erased: the value field is null and this is the digest of what it was */
+    /** present once the value has been erased: the value field is null and this is the digest of what it was, or null when none was kept */
     forgotten?: {
-        valueDigest: string;
+        valueDigest: string | null;
+        digestKind: DigestKind;
         at: string;
     };
     /** ids of this fact in the retrieval stores it was written through to, by store name; absent when there are none */
@@ -58,6 +62,11 @@ export interface ConfirmEvent {
     actor: string;
     source: Source;
 }
+/**
+ * How a forgotten value's digest was made. sha256 is guessable for short values by anyone holding the file;
+ * hmac-sha256 needs the ledger's forget key, kept outside the file; none keeps nothing derived from the value.
+ */
+export type DigestKind = "sha256" | "hmac-sha256" | "none";
 /**
  * A forget is erasure, not correction. The fact's value is removed from the ledger file itself and replaced by its
  * digest, so the ledger can still prove which value it held without holding it. The fact stops being believed.
@@ -70,10 +79,21 @@ export interface ForgetEvent {
     actor: string;
     reason: string;
     source: Source;
-    /** sha256 of the canonical JSON of the erased value */
-    valueDigest: string;
+    /** digest of the canonical JSON of the erased value, per digestKind; null when none was kept */
+    valueDigest: string | null;
+    digestKind: DigestKind;
+}
+/** A legal hold: while it stands, the fact cannot be forgotten, by request or by retention sweep. Release lifts it. */
+export interface HoldEvent {
+    eventId: string;
+    kind: "hold" | "release";
+    txTime: string;
+    factId: string;
+    actor: string;
+    reason: string;
+    source: Source;
 }
-export type LedgerEvent = AssertEvent | RetractEvent | ConfirmEvent | ForgetEvent;
+export type LedgerEvent = AssertEvent | RetractEvent | ConfirmEvent | ForgetEvent | HoldEvent;
 export interface AssertInput {
     subject: string;
     predicate: string;
@@ -98,6 +118,23 @@ export interface ForgetInput {
     actor: string;
     reason: string;
     source?: Source;
+    /** false keeps no digest at all; default true */
+    keepDigest?: boolean;
+}
+export interface HoldInput {
+    factId: string;
+    actor: string;
+    reason: string;
+    source?: Source;
+}
+export interface SweepInput {
+    /** every fact the ledger learned of before this instant is forgotten, unless held or already forgotten */
+    before: string;
+    space?: string;
+    actor: string;
+    reason: string;
+    source?: Source;
+    keepDigest?: boolean;
 }
 export interface RetractInput {
     factId: string;
@@ -113,15 +150,18 @@ export interface AsOf {
     space?: string;
     subject?: string;
     predicate?: string;
-    /** "attested" returns only facts that were attested at txAt; default "all" */
-    include?: "attested" | "all";
+    /** the least provenance to return: "attested" leaves out quarantined facts, "verified" leaves out everything the agent only asserted; default "all" */
+    include?: "attested" | "verified" | "all";
 }
 export declare class Ledger {
     private readonly events;
     private readonly file;
     private readonly now;
+    private readonly forgetKey;
+    /** forgetKey: a secret kept outside the file; with it, forgotten values leave an HMAC rather than a plain hash. */
     constructor(file: string, opts?: {
         now?: () => Date;
+        forgetKey?: string | Buffer;
     });
     get size(): number;
     /** The checks assert makes, without appending. For callers that must do something irreversible before the append. */
@@ -134,6 +174,15 @@ export declare class Ledger {
      * place, which is the one thing an append-only ledger must do for a deletion demand. Everything else about the fact
      * stays: who wrote it, when, from which receipt, and now who erased it and why.
      */
+    /** Whether a legal hold currently stands on the fact. */
+    held(factId: string): boolean;
+    hold(input: HoldInput): HoldEvent;
+    release(input: HoldInput): HoldEvent;
+    /** Retention: forgets every fact the ledger learned of before the cutoff, in one space or all, skipping held and already-forgotten facts. Returns what it forgot and what it skipped. */
+    sweep(input: SweepInput): {
+        forgotten: ForgetEvent[];
+        held: string[];
+    };
     forget(input: ForgetInput): ForgetEvent;
     /** The facts believed at a moment. Valid time answers "was it true then"; transaction time answers "did the ledger know it then". */
     asOf(q?: AsOf): Fact[];

package/dist/ledger.js

@@ -2,16 +2,20 @@
 // Bitemporal. Valid time is when a fact was true in the world; transaction time is when the ledger learned of it.
 // Nothing is ever edited in place. Correcting a belief is a new event, so "what did the agent believe at T" is always answerable.
 import { randomUUID } from "node:crypto";
-import { createHash } from "node:crypto";
+import { createHash, createHmac } from "node:crypto";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+const RANK = { claimed: 0, attested: 1, verified: 2 };
 export class Ledger {
     events = [];
     file;
     now;
+    forgetKey;
+    /** forgetKey: a secret kept outside the file; with it, forgotten values leave an HMAC rather than a plain hash. */
     constructor(file, opts = {}) {
         this.file = file;
         this.now = opts.now ?? (() => new Date());
+        this.forgetKey = opts.forgetKey ? Buffer.from(opts.forgetKey) : null;
         if (existsSync(file)) {
             for (const line of readFileSync(file, "utf8").split("\n")) {
                 if (line.trim())
@@ -90,7 +94,7 @@ export class Ledger {
             throw new Error(`cannot confirm unknown fact ${input.factId}`);
         if (this.retractedAt(input.factId))
             throw new Error(`fact ${input.factId} is retracted`);
-        if (prior.fact.provenance === "attested" || this.confirmedAt(input.factId))
+        if (prior.fact.provenance !== "claimed" || this.confirmedAt(input.factId))
             throw new Error(`fact ${input.factId} is already attested`);
         const event = { eventId: randomUUID(), kind: "confirm", txTime: this.now().toISOString(), factId: input.factId, actor: input.actor, source: input.source ?? { receiptId: null } };
         this.append(event);
@@ -101,21 +105,66 @@ export class Ledger {
      * place, which is the one thing an append-only ledger must do for a deletion demand. Everything else about the fact
      * stays: who wrote it, when, from which receipt, and now who erased it and why.
      */
+    /** Whether a legal hold currently stands on the fact. */
+    held(factId) {
+        let held = false;
+        for (const e of this.events)
+            if ((e.kind === "hold" || e.kind === "release") && e.factId === factId)
+                held = e.kind === "hold";
+        return held;
+    }
+    hold(input) {
+        const prior = this.factById(input.factId);
+        if (!prior)
+            throw new Error(`cannot hold unknown fact ${input.factId}`);
+        if (prior.fact.forgotten)
+            throw new Error(`fact ${input.factId} is already forgotten`);
+        if (this.held(input.factId))
+            throw new Error(`fact ${input.factId} is already on hold`);
+        const event = { eventId: randomUUID(), kind: "hold", txTime: this.now().toISOString(), factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null } };
+        this.append(event);
+        return event;
+    }
+    release(input) {
+        if (!this.held(input.factId))
+            throw new Error(`fact ${input.factId} is not on hold`);
+        const event = { eventId: randomUUID(), kind: "release", txTime: this.now().toISOString(), factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null } };
+        this.append(event);
+        return event;
+    }
+    /** Retention: forgets every fact the ledger learned of before the cutoff, in one space or all, skipping held and already-forgotten facts. Returns what it forgot and what it skipped. */
+    sweep(input) {
+        const forgotten = [];
+        const held = [];
+        const targets = this.events.filter((e) => e.kind === "assert" && e.txTime < input.before && (input.space === undefined || e.fact.space === input.space) && !e.fact.forgotten);
+        for (const e of targets) {
+            if (this.held(e.fact.factId)) {
+                held.push(e.fact.factId);
+                continue;
+            }
+            forgotten.push(this.forget({ factId: e.fact.factId, actor: input.actor, reason: input.reason, ...(input.source ? { source: input.source } : {}), ...(input.keepDigest === undefined ? {} : { keepDigest: input.keepDigest }) }));
+        }
+        return { forgotten, held };
+    }
     forget(input) {
         const prior = this.factById(input.factId);
         if (!prior)
             throw new Error(`cannot forget unknown fact ${input.factId}`);
         if (prior.fact.forgotten)
             throw new Error(`fact ${input.factId} is already forgotten`);
+        if (this.held(input.factId))
+            throw new Error(`fact ${input.factId} is on legal hold; release it first`);
         const txTime = this.now().toISOString();
-        const valueDigest = createHash("sha256").update(canonical(prior.fact.value)).digest("hex");
+        const text = canonical(prior.fact.value);
+        const digestKind = input.keepDigest === false ? "none" : this.forgetKey ? "hmac-sha256" : "sha256";
+        const valueDigest = digestKind === "none" ? null : digestKind === "hmac-sha256" ? createHmac("sha256", this.forgetKey).update(text).digest("hex") : createHash("sha256").update(text).digest("hex");
         for (const e of this.events) {
             if (e.kind === "assert" && e.fact.factId === input.factId) {
                 e.fact.value = null;
-                e.fact.forgotten = { valueDigest, at: txTime };
+                e.fact.forgotten = { valueDigest, digestKind, at: txTime };
             }
         }
-        const event = { eventId: randomUUID(), kind: "forget", txTime, factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null }, valueDigest };
+        const event = { eventId: randomUUID(), kind: "forget", txTime, factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null }, valueDigest, digestKind };
         this.events.push(event);
         const tmp = `${this.file}.tmp`;
         writeFileSync(tmp, this.events.map((e) => JSON.stringify(e)).join("\n") + "\n");
@@ -144,7 +193,7 @@ export class Ledger {
             (q.space === undefined || f.space === q.space) &&
             (q.subject === undefined || f.subject === q.subject) &&
             (q.predicate === undefined || f.predicate === q.predicate) &&
-            (q.include !== "attested" || f.provenance === "attested"));
+            (q.include === undefined || q.include === "all" || RANK[f.provenance] >= RANK[q.include]));
     }
     /** Every fact ever asserted, with supersession applied and retracted ones included, for audits that must see everything. */
     facts() {

package/dist/server.d.ts

@@ -9,6 +9,8 @@ export declare const RECEIPT_META_KEY = "agent-custody/receipt";
 export declare const AGENT_META_KEY = "agent-custody/agent";
 /** Set on read results: the ids of the facts served, so the gateway can record what the agent was shown. */
 export declare const FACTS_META_KEY = "agent-custody/facts";
+/** Set by the gateway on the forwarded call: the values it fetched itself for this call, by fact name. */
+export declare const OBSERVED_META_KEY = "agent-custody/observed";
 export declare const TOOLS: Tool[];
 export interface MemoryServerOptions {
     /** Refuse calls that did not come through the gateway, i.e. carry no receipt id. On by default when served from the CLI. */
@@ -17,7 +19,13 @@ export interface MemoryServerOptions {
     stores?: Store[];
     /** With a key, every result to a gateway call is signed for that receipt, so a verifier holding the public key sees the execution as attested by this server. */
     identity?: KeyPair;
+    /** Retention windows by space pattern, ISO 8601 durations: { "org": "P365D", "team:*": "P90D" }. memory.sweep without `before` uses them. */
+    retention?: Record<string, string>;
 }
+/** Parses the ISO 8601 duration subset retention needs: P<n>W, P<n>D, PT<n>H, and combinations of D and H. */
+export declare function durationMs(iso: string): number;
+/** The retention cutoff for a space, from the first pattern that matches it; null when none does. */
+export declare function retentionCutoff(retention: Record<string, string>, space: string, now: Date): string | null;
 export declare function createMemoryServer(ledger: Ledger, opts?: MemoryServerOptions): Server;
 /** Serves over stdio, the way the gateway spawns it. Diagnostics must go to stderr. */
 export declare function serveStdio(server: Server): Promise<void>;

package/dist/server.js

@@ -14,6 +14,8 @@ export const RECEIPT_META_KEY = "agent-custody/receipt";
 export const AGENT_META_KEY = "agent-custody/agent";
 /** Set on read results: the ids of the facts served, so the gateway can record what the agent was shown. */
 export const FACTS_META_KEY = "agent-custody/facts";
+/** Set by the gateway on the forwarded call: the values it fetched itself for this call, by fact name. */
+export const OBSERVED_META_KEY = "agent-custody/observed";
 const iso = z.string().datetime({ offset: true });
 const Write = z.object({
     subject: z.string().min(1),
@@ -25,24 +27,28 @@ const Write = z.object({
     validFrom: iso.optional(),
     confidence: z.number().min(0).max(1).optional(),
     supersedes: z.string().min(1).optional(),
+    /** names a fact the gateway fetched for this call, and optionally a dot path into it, that the value must equal; the write is then verified, or refused */
+    evidence: z.object({ fact: z.string().min(1), path: z.string().optional() }).optional(),
 });
-const Read = z.object({ subject: z.string().min(1).optional(), predicate: z.string().min(1).optional(), space: z.string().min(1).optional(), validAt: iso.optional(), txAt: iso.optional(), includeClaimed: z.boolean().optional() });
+const Read = z.object({ subject: z.string().min(1).optional(), predicate: z.string().min(1).optional(), space: z.string().min(1).optional(), validAt: iso.optional(), txAt: iso.optional(), includeClaimed: z.boolean().optional(), requireVerified: z.boolean().optional() });
 const Confirm = z.object({ factId: z.string().min(1) });
 const Retract = z.object({ factId: z.string().min(1), reason: z.string().min(1), actor: z.string().min(1).optional() });
 const History = z.object({ factId: z.string().min(1) });
 const Get = z.object({ factId: z.string().min(1) });
-const Forget = z.object({ factId: z.string().min(1), reason: z.string().min(1) });
+const Forget = z.object({ factId: z.string().min(1), reason: z.string().min(1), keepDigest: z.boolean().optional() });
+const Hold = z.object({ factId: z.string().min(1), reason: z.string().min(1) });
+const Sweep = z.object({ before: iso.optional(), space: z.string().min(1).optional(), reason: z.string().min(1), keepDigest: z.boolean().optional() });
 const str = { type: "string" };
 export const TOOLS = [
     {
         name: "memory.write",
-        description: "Record a belief: subject, predicate, value, in a space. Optionally supersede an earlier fact. Returns the new fact with its id, transaction time, actor, and source receipt.",
-        inputSchema: { type: "object", properties: { subject: str, predicate: str, value: {}, space: str, actor: str, validFrom: str, confidence: { type: "number" }, supersedes: str }, required: ["subject", "predicate", "value", "space"] },
+        description: "Record a belief: subject, predicate, value, in a space. Optionally supersede an earlier fact. With evidence naming a fact the gateway fetched for this call, the value must equal it (or the field at path) and the write is verified; otherwise it is refused. Returns the new fact with its id, transaction time, actor, provenance, and source receipt.",
+        inputSchema: { type: "object", properties: { subject: str, predicate: str, value: {}, space: str, actor: str, validFrom: str, confidence: { type: "number" }, supersedes: str, evidence: { type: "object", properties: { fact: str, path: str }, required: ["fact"] } }, required: ["subject", "predicate", "value", "space"] },
     },
     {
         name: "memory.read",
-        description: "The facts believed at a moment. validAt asks whether a fact was true then; txAt asks whether the ledger knew it then. Both default to now. Filter by space, subject, predicate. Quarantined (claimed, unconfirmed) facts are left out unless includeClaimed is true.",
-        inputSchema: { type: "object", properties: { subject: str, predicate: str, space: str, validAt: str, txAt: str, includeClaimed: { type: "boolean" } } },
+        description: "The facts believed at a moment. validAt asks whether a fact was true then; txAt asks whether the ledger knew it then. Both default to now. Filter by space, subject, predicate. Quarantined (claimed, unconfirmed) facts are left out unless includeClaimed is true; requireVerified returns only facts whose value the gateway checked against its source.",
+        inputSchema: { type: "object", properties: { subject: str, predicate: str, space: str, validAt: str, txAt: str, includeClaimed: { type: "boolean" }, requireVerified: { type: "boolean" } } },
     },
     {
         name: "memory.confirm",
@@ -56,9 +62,24 @@ export const TOOLS = [
     },
     {
         name: "memory.forget",
-        description: "Erase a fact's value: from the ledger file, keeping only its digest, and from every store behind the server. The fact stops being believed. The receipt for this call, with the result the gateway observed, is the certificate that the erasure happened.",
+        description: "Erase a fact's value: from the ledger file, keeping only its digest (keyed when the server has a forget key; none when keepDigest is false), and from every store behind the server. The fact stops being believed. The receipt for this call, with the result the gateway observed, is the certificate that the erasure happened.",
+        inputSchema: { type: "object", properties: { factId: str, reason: str, keepDigest: { type: "boolean" } }, required: ["factId", "reason"] },
+    },
+    {
+        name: "memory.hold",
+        description: "Legal hold: while it stands the fact cannot be forgotten, by request or by retention sweep.",
+        inputSchema: { type: "object", properties: { factId: str, reason: str }, required: ["factId", "reason"] },
+    },
+    {
+        name: "memory.release",
+        description: "Lift a legal hold.",
         inputSchema: { type: "object", properties: { factId: str, reason: str }, required: ["factId", "reason"] },
     },
+    {
+        name: "memory.sweep",
+        description: "Retention: forget every fact the ledger learned of before an instant, in one space or all, skipping held facts, and remove each from every store. Without `before`, the server's configured retention windows decide per space. The receipt is the record of the sweep.",
+        inputSchema: { type: "object", properties: { before: str, space: str, reason: str, keepDigest: { type: "boolean" } }, required: ["reason"] },
+    },
     {
         name: "memory.get",
         description: "One fact by id, whatever its state: its space, actor, provenance, source receipt, validity. Meant for the gateway's fact lookups, so policy can decide on the fact a write supersedes or a retraction targets.",
@@ -70,6 +91,23 @@ export const TOOLS = [
         inputSchema: { type: "object", properties: { factId: str }, required: ["factId"] },
     },
 ];
+/** Parses the ISO 8601 duration subset retention needs: P<n>W, P<n>D, PT<n>H, and combinations of D and H. */
+export function durationMs(iso) {
+    const m = /^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?)?$/.exec(iso);
+    if (!m || iso === "P" || iso === "PT")
+        throw new Error(`retention: cannot parse duration ${iso}; use forms like P90D, P2W, PT12H`);
+    const [, w = "0", d = "0", h = "0", min = "0"] = m;
+    return ((Number(w) * 7 + Number(d)) * 24 + Number(h)) * 3_600_000 + Number(min) * 60_000;
+}
+/** The retention cutoff for a space, from the first pattern that matches it; null when none does. */
+export function retentionCutoff(retention, space, now) {
+    for (const [pattern, duration] of Object.entries(retention)) {
+        const matches = pattern.endsWith("*") ? space.startsWith(pattern.slice(0, -1)) : space === pattern;
+        if (matches)
+            return new Date(now.getTime() - durationMs(duration)).toISOString();
+    }
+    return null;
+}
 const json = (v) => ({ content: [{ type: "text", text: JSON.stringify(v) }] });
 const fail = (msg) => ({ isError: true, content: [{ type: "text", text: msg }] });
 export function createMemoryServer(ledger, opts = {}) {
@@ -81,6 +119,27 @@ export function createMemoryServer(ledger, opts = {}) {
         const result = await handle(req.params.name, req.params.arguments ?? {}, meta, receiptId);
         return opts.identity && receiptId ? signResult(result, opts.identity, receiptId, req.params.name) : result;
     });
+    async function forgetOne(factId, reason, keepDigest) {
+        const fact = ledger.facts().find((f) => f.factId === factId);
+        const ev = ledger.forget({ factId, actor: currentActor, reason, source: { receiptId: currentReceipt }, ...(keepDigest === undefined ? {} : { keepDigest }) });
+        const removedFrom = [];
+        const stillHeld = [];
+        for (const store of opts.stores ?? []) {
+            const id = fact?.external?.[store.name];
+            if (!id)
+                continue;
+            try {
+                await store.remove(id, fact);
+                removedFrom.push(store.name);
+            }
+            catch (e) {
+                stillHeld.push(`${store.name}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        return { factId: ev.factId, valueDigest: ev.valueDigest, digestKind: ev.digestKind, txTime: ev.txTime, actor: ev.actor, reason: ev.reason, source: ev.source, erasedFromLedger: true, removedFrom, stillHeld };
+    }
+    let currentActor = "anonymous";
+    let currentReceipt = null;
     async function handle(name, args, meta, receiptId) {
         const gatewayAgent = typeof meta[AGENT_META_KEY] === "string" ? meta[AGENT_META_KEY] : null;
         if (opts.requireGateway && !receiptId)
@@ -88,11 +147,26 @@ export function createMemoryServer(ledger, opts = {}) {
         const actorFor = (claimed) => gatewayAgent ?? claimed ?? "anonymous";
         // A write is attested when it came through the gateway: the actor is from a signed grant and the receipt exists.
         const provenance = receiptId && gatewayAgent ? "attested" : "claimed";
+        const observed = (meta[OBSERVED_META_KEY] ?? {});
+        currentActor = actorFor(undefined);
+        currentReceipt = receiptId;
         try {
             switch (name) {
                 case "memory.write": {
                     const a = Write.parse(args);
-                    const input = { subject: a.subject, predicate: a.predicate, value: a.value ?? null, space: a.space, actor: actorFor(a.actor), source: { receiptId }, provenance, ...(a.validFrom ? { validFrom: a.validFrom } : {}), ...(a.confidence !== undefined ? { confidence: a.confidence } : {}), ...(a.supersedes ? { supersedes: a.supersedes } : {}) };
+                    let writeProvenance = provenance;
+                    if (a.evidence) {
+                        // Value-level quarantine: the agent may say where the value came from, and the gateway's own observation decides.
+                        if (provenance !== "attested")
+                            return fail("evidence needs the gateway: only a fact the gateway fetched itself can verify a value");
+                        if (!(a.evidence.fact in observed))
+                            return fail(`no fact named "${a.evidence.fact}" was fetched by the gateway for this call; configure a fact lookup for memory.write`);
+                        const expected = a.evidence.path ? a.evidence.path.split(".").reduce((v, k) => (v && typeof v === "object" ? v[k] : undefined), observed[a.evidence.fact]) : observed[a.evidence.fact];
+                        if (JSON.stringify(sortKeys(expected)) !== JSON.stringify(sortKeys(a.value ?? null)))
+                            return fail(`value differs from what the gateway observed in "${a.evidence.fact}${a.evidence.path ? "." + a.evidence.path : ""}"; write refused`);
+                        writeProvenance = "verified";
+                    }
+                    const input = { subject: a.subject, predicate: a.predicate, value: a.value ?? null, space: a.space, actor: actorFor(a.actor), source: { receiptId }, provenance: writeProvenance, ...(a.validFrom ? { validFrom: a.validFrom } : {}), ...(a.confidence !== undefined ? { confidence: a.confidence } : {}), ...(a.supersedes ? { supersedes: a.supersedes } : {}) };
                     // The stores are written first, so their ids can be recorded on the fact; the ledger's checks run beforehand
                     // so a write the ledger would refuse never reaches a store.
                     ledger.validateAssert(input);
@@ -104,8 +178,8 @@ export function createMemoryServer(ledger, opts = {}) {
                     return json({ fact: ev.fact, eventId: ev.eventId, txTime: ev.txTime, supersedes: ev.supersedes });
                 }
                 case "memory.read": {
-                    const { includeClaimed, ...q } = Read.parse(args);
-                    const facts = ledger.asOf({ ...q, include: includeClaimed ? "all" : "attested" });
+                    const { includeClaimed, requireVerified, ...q } = Read.parse(args);
+                    const facts = ledger.asOf({ ...q, include: requireVerified ? "verified" : includeClaimed ? "all" : "attested" });
                     return { ...json({ facts }), _meta: { [FACTS_META_KEY]: facts.map((f) => f.factId) } };
                 }
                 case "memory.retract": {
@@ -140,25 +214,45 @@ export function createMemoryServer(ledger, opts = {}) {
                 }
                 case "memory.forget": {
                     const a = Forget.parse(args);
-                    const fact = ledger.facts().find((f) => f.factId === a.factId);
-                    const ev = ledger.forget({ factId: a.factId, actor: actorFor(undefined), reason: a.reason, source: { receiptId } });
-                    const removedFrom = [];
-                    const stillHeld = [];
-                    for (const store of opts.stores ?? []) {
-                        const id = fact?.external?.[store.name];
-                        if (!id)
+                    const out = await forgetOne(a.factId, a.reason, a.keepDigest);
+                    if (out.stillHeld.length > 0)
+                        return { isError: true, content: [{ type: "text", text: `erased from the ledger, but still held by ${out.stillHeld.join("; ")}` }, { type: "text", text: JSON.stringify(out) }] };
+                    return json(out);
+                }
+                case "memory.hold": {
+                    const a = Hold.parse(args);
+                    return json(ledger.hold({ factId: a.factId, actor: actorFor(undefined), reason: a.reason, source: { receiptId } }));
+                }
+                case "memory.release": {
+                    const a = Hold.parse(args);
+                    return json(ledger.release({ factId: a.factId, actor: actorFor(undefined), reason: a.reason, source: { receiptId } }));
+                }
+                case "memory.sweep": {
+                    const a = Sweep.parse(args);
+                    if (!a.before && !opts.retention)
+                        return fail("sweep needs `before`, or a server started with retention windows");
+                    const now = new Date();
+                    const cutoffFor = (space) => a.before ?? retentionCutoff(opts.retention ?? {}, space, now);
+                    const targets = ledger.facts().filter((f) => !f.forgotten && (a.space === undefined || f.space === a.space));
+                    const learnedBefore = new Set(ledger.facts().filter((f) => {
+                        const cutoff = cutoffFor(f.space);
+                        return cutoff !== null && ledger.history(f.factId).find((e) => e.kind === "assert" && e.fact.factId === f.factId).txTime < cutoff;
+                    }).map((f) => f.factId));
+                    const forgotten = [];
+                    const held = [];
+                    for (const f of targets) {
+                        if (!learnedBefore.has(f.factId))
+                            continue;
+                        if (ledger.held(f.factId)) {
+                            held.push(f.factId);
                             continue;
-                        try {
-                            await store.remove(id, fact);
-                            removedFrom.push(store.name);
-                        }
-                        catch (e) {
-                            stillHeld.push(`${store.name}: ${e instanceof Error ? e.message : String(e)}`);
                         }
+                        forgotten.push(await forgetOne(f.factId, a.reason, a.keepDigest));
                     }
-                    const out = { factId: ev.factId, valueDigest: ev.valueDigest, txTime: ev.txTime, actor: ev.actor, reason: ev.reason, source: ev.source, erasedFromLedger: true, removedFrom, stillHeld };
+                    const stillHeld = forgotten.flatMap((o) => o.stillHeld);
+                    const out = { before: a.before ?? null, retention: a.before ? null : (opts.retention ?? null), space: a.space ?? null, forgotten: forgotten.map((o) => ({ factId: o.factId, valueDigest: o.valueDigest, digestKind: o.digestKind, removedFrom: o.removedFrom })), held, stillHeld };
                     if (stillHeld.length > 0)
-                        return { isError: true, content: [{ type: "text", text: `erased from the ledger, but still held by ${stillHeld.join("; ")}` }, { type: "text", text: JSON.stringify(out) }] };
+                        return { isError: true, content: [{ type: "text", text: `swept the ledger, but some values are still held by stores: ${stillHeld.join("; ")}` }, { type: "text", text: JSON.stringify(out) }] };
                     return json(out);
                 }
                 case "memory.get": {
@@ -190,3 +284,14 @@ export async function serveStdio(server) {
         server.onclose = resolve;
     });
 }
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v && typeof v === "object") {
+        const o = {};
+        for (const k of Object.keys(v).sort())
+            o[k] = sortKeys(v[k]);
+        return o;
+    }
+    return v;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/state",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Governed memory for AI agents: a fact ledger with provenance, valid time, rollback, and lineage, built on @agent-custody/receipts",
   "license": "Apache-2.0",
   "repository": {
@@ -33,7 +33,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@agent-custody/receipts": "0.1.5",
+    "@agent-custody/receipts": "0.1.7",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.5.4"
   },