@agent-custody/state 0.1.4 → 0.1.5

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" });
 ```
 
-Four runnable examples, all executed by the test suite. [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.
+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.
 
 ## The memory server
 
@@ -44,14 +44,65 @@ In the gateway's config, the memory server is the upstream, and the grant names
 | `memory.read` | the facts believed at a moment, by space, subject, predicate, valid time, transaction time | the query |
 | `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.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. Today the server has one client, over stdio, so claimed facts reach a gateway-fronted ledger by being there before it was put under the gateway, or by a direct writer sharing the file; a shared memory server over HTTP, on the plan, is what makes mixed attested and self-reported writers a live deployment.
+**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.
+
+**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:
+
+```json
+"facts": [
+  { "name": "target", "tool": "memory.get", "args": { "factId": "$args.supersedes" }, "forTools": ["memory.write"], "optional": true },
+  { "name": "target", "tool": "memory.get", "args": { "factId": "$args.factId" }, "forTools": ["memory.retract"] }
+]
+```
+
+```cedar
+forbid(principal, action in [Action::"memory.write", Action::"memory.retract"], resource)
+when { context.facts has target && context.facts.target.space == "org" && context.facts.target.provenance == "attested" };
+```
+
+The lookup for writes is optional, so a write that supersedes nothing needs no lookup; the one for retractions is required. The denial receipt records the fact the policy saw, observed by the gateway. The test suite runs exactly this configuration.
+
+**Attested executions.** Started with `--key memory.key`, the server signs every result for the receipt the gateway is issuing. A verifier given `memory.pub` then reports the execution of each memory call as attested by the memory server, not only observed by the gateway; the test suite verifies a write this way.
+
+**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.
 
 `--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.
+
+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.
+
+## Blast radius
+
+When a belief turns out wrong, the next question is what relied on it. Two records answer it together. Every gateway receipt carries `consumed`: the fact ids the agent had been shown, through the gateway, before that call, which the memory server declares on each read. Every fact in the ledger carries the receipt that wrote it. Walking forward from a fact through those two links gives every later call and every belief written in those calls, transitively, and whether the root was retracted and which derived beliefs are still believed.
+
+```bash
+agent-custody-memory blast --ledger ./ledger.jsonl --receipts ./receipts --fact <factId>
+```
+
+```
+fact 3f2a…: acct:42 plan = "enterprise" (space team:support, by support-agent, attested)
+retracted at 2026-09-07T10:12:04.118Z by support-agent: CRM sync bug: account is on the free plan
+3 call(s) made after the agent was shown it:
+  2026-09-07T10:12:03.902Z  memory.write       executed  receipt 7c1e…
+  ...
+2 belief(s) written in those calls, 2 still believed:
+  acct:42 discount = "20%"  fact 9b04…  STILL BELIEVED
+  acct:42 support_tier = "priority"  fact e77d…  STILL BELIEVED
+```
+
+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
 
 The ledger is not a retrieval store, and it does not try to be. `src/stores.ts` puts it under the ones teams already run: a fact written through the memory server also lands in every configured store, with its custody metadata (fact id, space, actor, provenance, receipt id), the store's own id is recorded on the fact, and a retraction reaches the store by that id. Certified forget will be built on this: a deletion is only real once it has reached the stores that serve recall.
@@ -102,7 +153,9 @@ 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/cli.ts      agent-custody-memory serve
+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/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
 src/evals-ledger.ts  the ledger and a naive overwrite store behind the harness interface
@@ -118,13 +171,19 @@ 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.
+- 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.
+- Policy over provenance: the gateway looks up the fact a write supersedes or a retraction targets, so policy decides on its space, actor, and provenance; a claimed fact can be displaced, an attested org fact cannot.
+- Consumed facts and blast radius: the memory server declares the facts it serves, the gateway records them on every later receipt, and `blast` walks from a fact to every downstream call and derived belief, transitively, with its retraction status.
 - Write-through adapters for Mem0 and Zep: every write lands in the store with custody metadata, the store id is recorded on the fact, retractions reach the store, and failures are ordered so nothing is half-recorded.
 - The memory-mutation eval harness: stale reads, contradictions, blast radius, and correct reads over scripted incidents, scored the same way for the ledger and for anything behind the same interface.
 - Quarantine: facts carry `attested` or `claimed` provenance; claimed facts are hidden from reads by default and a gateway-only `memory.confirm` lifts them, as a recorded event.
 
 **Next, in the order it pays off**
 
-1. A consumed-facts field on receipts: the gateway records which fact ids a read returned, so later receipts in the session show what the agent relied on.
-2. Blast radius: given a fact id, every downstream receipt and derived fact that cited it, and the retraction that undoes the belief.
-3. Trust tiers, the rest: Cedar policy over provenance so a claimed write cannot supersede an attested org-space fact, and quarantine of values that came from untrusted tool output even when the actor is attested.
-4. Signed forget statements: a retention or deletion request produces a verifiable record of which facts were removed from the ledger and from every store behind it.
+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.
+

package/dist/blast.d.ts

@@ -0,0 +1,25 @@
+import type { Fact, Ledger, RetractEvent } from "./ledger.ts";
+/** The parts of a receipt this query needs. Decoded from a bundle's statement; nothing here is verified, so verify first. */
+export interface ReceiptSummary {
+    receiptId: string;
+    timestamp: string;
+    tool: string;
+    status: string;
+    /** fact ids the agent had been shown before this call, from the receipt's consumed field */
+    consumed: string[];
+}
+/** Reads every bundle in a receipts directory. Order is by timestamp. */
+export declare function loadReceipts(dir: string): ReceiptSummary[];
+export interface BlastRadius {
+    fact: Fact | null;
+    /** every receipt for a call made after the agent had been shown this fact or one derived from it */
+    receipts: ReceiptSummary[];
+    /** every fact written in one of those calls, transitively */
+    derivedFacts: Fact[];
+    /** the retraction of the root fact, when it has been undone */
+    retraction: RetractEvent | null;
+    /** derived facts that are still believed; the ones a cleanup has to decide about */
+    stillBelieved: Fact[];
+}
+export declare function blastRadius(ledger: Ledger, receipts: ReceiptSummary[], factId: string): BlastRadius;
+export declare function formatBlastRadius(b: BlastRadius, factId: string): string;

package/dist/blast.js

@@ -0,0 +1,62 @@
+// Blast radius: given a fact, everything that relied on it. The receipts say which facts the agent had been shown
+// before each call; the ledger says which facts were written in which call. Walking both, forward, gives every
+// downstream action and every derived belief, transitively, and the retraction that undoes the belief if there is one.
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** Reads every bundle in a receipts directory. Order is by timestamp. */
+export function loadReceipts(dir) {
+    const out = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        const bundle = JSON.parse(readFileSync(join(dir, f), "utf8"));
+        if (!bundle.envelope?.payload)
+            continue;
+        const st = JSON.parse(Buffer.from(bundle.envelope.payload, "base64").toString());
+        const p = st.predicate;
+        if (!p?.receiptId)
+            continue;
+        out.push({ receiptId: p.receiptId, timestamp: p.timestamp, tool: p.tool?.name ?? "?", status: p.execution?.status ?? "?", consumed: Array.isArray(p.consumed?.factIds) ? p.consumed.factIds : [] });
+    }
+    return out.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+}
+export function blastRadius(ledger, receipts, factId) {
+    const all = ledger.facts();
+    const byId = new Map(all.map((f) => [f.factId, f]));
+    const believed = new Set(ledger.asOf().map((f) => f.factId));
+    const seen = new Set([factId]);
+    const hit = new Map();
+    const derived = new Map();
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const r of receipts) {
+            if (hit.has(r.receiptId) || !r.consumed.some((id) => seen.has(id)))
+                continue;
+            hit.set(r.receiptId, r);
+            grew = true;
+        }
+        for (const f of all) {
+            if (f.factId === factId || derived.has(f.factId) || !f.source.receiptId || !hit.has(f.source.receiptId))
+                continue;
+            derived.set(f.factId, f);
+            seen.add(f.factId);
+            grew = true;
+        }
+    }
+    const retraction = ledger.history(factId).find((e) => e.kind === "retract") ?? null;
+    const derivedFacts = [...derived.values()];
+    return { fact: byId.get(factId) ?? null, receipts: [...hit.values()].sort((a, b) => a.timestamp.localeCompare(b.timestamp)), derivedFacts, retraction, stillBelieved: derivedFacts.filter((f) => believed.has(f.factId)) };
+}
+export function formatBlastRadius(b, factId) {
+    const lines = [];
+    lines.push(b.fact ? `fact ${factId}: ${b.fact.subject} ${b.fact.predicate} = ${JSON.stringify(b.fact.value)} (space ${b.fact.space}, by ${b.fact.actor}, ${b.fact.provenance})` : `fact ${factId}: not in this ledger`);
+    lines.push(b.retraction ? `retracted at ${b.retraction.txTime} by ${b.retraction.actor}: ${b.retraction.reason}` : "not retracted");
+    lines.push(`${b.receipts.length} call(s) made after the agent was shown it:`);
+    for (const r of b.receipts)
+        lines.push(`  ${r.timestamp}  ${r.tool.padEnd(18)} ${r.status.padEnd(9)} receipt ${r.receiptId.slice(0, 8)}`);
+    lines.push(`${b.derivedFacts.length} belief(s) written in those calls, ${b.stillBelieved.length} still believed:`);
+    for (const f of b.derivedFacts)
+        lines.push(`  ${f.subject} ${f.predicate} = ${JSON.stringify(f.value)}  fact ${f.factId.slice(0, 8)}  ${b.stillBelieved.includes(f) ? "STILL BELIEVED" : "no longer believed"}`);
+    return lines.join("\n");
+}

package/dist/cli.js

@@ -2,23 +2,51 @@
 import { parseArgs } from "node:util";
 import { Ledger } from "./ledger.js";
 import { createMemoryServer, serveStdio } from "./server.js";
+import { blastRadius, formatBlastRadius, loadReceipts } from "./blast.js";
+import { serveMemoryHttp } from "./http.js";
+import { loadPrivateKey } from "@agent-custody/receipts";
 const USAGE = `agent-custody-memory <command>
 
-  serve --ledger <ledger.jsonl> [--allow-direct]   the memory server over stdio; run it as the receipts gateway's upstream.
+  serve --ledger <ledger.jsonl> [--allow-direct] [--key <memory.key>]
+                                                   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
+  blast --ledger <ledger.jsonl> --receipts <dir> --fact <factId> [--json]
+                                                   everything that relied on a fact: later calls, derived beliefs, and whether it was retracted
 `;
 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 } } });
+            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" } } });
             if (!values.ledger)
                 throw new Error("serve needs --ledger");
             const ledger = new Ledger(values.ledger);
+            const identity = values.key ? loadPrivateKey(values.key) : undefined;
+            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 } : {}) });
+                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"] }));
+            await serveStdio(createMemoryServer(ledger, { requireGateway: !values["allow-direct"], ...(identity ? { identity } : {}) }));
             return 0;
         }
+        case "blast": {
+            const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, receipts: { type: "string" }, fact: { type: "string" }, json: { type: "boolean", default: false } } });
+            if (!values.ledger || !values.receipts || !values.fact)
+                throw new Error("blast needs --ledger, --receipts, and --fact");
+            const b = blastRadius(new Ledger(values.ledger), loadReceipts(values.receipts), values.fact);
+            console.log(values.json ? JSON.stringify(b, null, 2) : formatBlastRadius(b, values.fact));
+            return b.fact ? 0 : 1;
+        }
         default:
             console.error(USAGE);
             return cmd === undefined || cmd === "--help" || cmd === "-h" ? 0 : 2;

package/dist/http.d.ts

@@ -0,0 +1,16 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { Ledger } from "./ledger.ts";
+import { type MemoryServerOptions } from "./server.ts";
+export interface MemoryHttpOptions extends MemoryServerOptions {
+    port: number;
+    host?: string;
+    /** bearer tokens accepted; when empty, anyone who can reach the port may call */
+    tokens?: string[];
+}
+export interface RunningMemoryServer {
+    url: string;
+    close(): Promise<void>;
+}
+export declare function memoryHttpHandler(ledger: Ledger, opts: MemoryHttpOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+/** Starts the memory server over HTTP. Port 0 picks a free port. Host defaults to loopback; bind wider only behind auth. */
+export declare function serveMemoryHttp(ledger: Ledger, opts: MemoryHttpOptions): Promise<RunningMemoryServer>;

package/dist/http.js

@@ -0,0 +1,46 @@
+// The memory server over HTTP: one ledger shared by several gateways and, if allowed, direct writers. This is what
+// makes quarantine a live deployment: attested writes arrive through gateways, self-reported ones directly, and the
+// ledger tells them apart. Stateless Streamable HTTP, one MCP server instance per request over the shared ledger.
+import { timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMemoryServer } from "./server.js";
+export function memoryHttpHandler(ledger, opts) {
+    const tokens = opts.tokens ?? [];
+    const authorized = (req) => {
+        if (tokens.length === 0)
+            return true;
+        const h = req.headers.authorization ?? "";
+        const given = Buffer.from(h.startsWith("Bearer ") ? h.slice(7) : "");
+        return tokens.some((t) => Buffer.from(t).length === given.length && timingSafeEqual(Buffer.from(t), given));
+    };
+    return async (req, res) => {
+        if (!authorized(req)) {
+            res.writeHead(401, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "unauthorized" }));
+            return;
+        }
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        const server = createMemoryServer(ledger, opts);
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+    };
+}
+/** Starts the memory server over HTTP. Port 0 picks a free port. Host defaults to loopback; bind wider only behind auth. */
+export function serveMemoryHttp(ledger, opts) {
+    const host = opts.host ?? "127.0.0.1";
+    const handler = memoryHttpHandler(ledger, opts);
+    const server = createServer((req, res) => {
+        void handler(req, res);
+    });
+    return new Promise((resolve) => {
+        server.listen(opts.port, host, () => {
+            const { port } = server.address();
+            resolve({ url: `http://${host}:${port}/mcp`, close: () => new Promise((r) => server.close(() => r())) });
+        });
+    });
+}

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 export { Ledger } from "./ledger.ts";
-export type { AsOf, AssertEvent, AssertInput, ConfirmEvent, ConfirmInput, Fact, FactProvenance, LedgerEvent, RetractEvent, RetractInput, Source } from "./ledger.ts";
-export { AGENT_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, serveStdio } from "./server.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 { MemoryServerOptions } from "./server.ts";
 export { SCENARIOS, formatReport, runAll, runScenario } from "./evals.ts";
 export type { MemoryUnderTest, Op, Report, Scenario, ScenarioScore } from "./evals.ts";
 export { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.ts";
 export { factMetadata, factText, mem0Store, zepStore } from "./stores.ts";
+export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.ts";
+export { memoryHttpHandler, serveMemoryHttp } from "./http.ts";
+export type { MemoryHttpOptions, RunningMemoryServer } from "./http.ts";
+export type { BlastRadius, ReceiptSummary } from "./blast.ts";
 export type { Mem0Like, Mem0Options, Store, ZepLike, ZepOptions } from "./stores.ts";

package/dist/index.js

@@ -1,6 +1,8 @@
 // Public surface of @agent-custody/state.
 export { Ledger } from "./ledger.js";
-export { AGENT_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, serveStdio } from "./server.js";
+export { AGENT_META_KEY, FACTS_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, 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";
+export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.js";
+export { memoryHttpHandler, serveMemoryHttp } from "./http.js";

package/dist/ledger.d.ts

@@ -19,6 +19,11 @@ 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 */
+    forgotten?: {
+        valueDigest: string;
+        at: string;
+    };
     /** ids of this fact in the retrieval stores it was written through to, by store name; absent when there are none */
     external?: Record<string, string>;
     /** ISO timestamps. validTo is null while the fact is believed to still hold. */
@@ -53,7 +58,22 @@ export interface ConfirmEvent {
     actor: string;
     source: Source;
 }
-export type LedgerEvent = AssertEvent | RetractEvent | ConfirmEvent;
+/**
+ * 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.
+ */
+export interface ForgetEvent {
+    eventId: string;
+    kind: "forget";
+    txTime: string;
+    factId: string;
+    actor: string;
+    reason: string;
+    source: Source;
+    /** sha256 of the canonical JSON of the erased value */
+    valueDigest: string;
+}
+export type LedgerEvent = AssertEvent | RetractEvent | ConfirmEvent | ForgetEvent;
 export interface AssertInput {
     subject: string;
     predicate: string;
@@ -73,6 +93,12 @@ export interface ConfirmInput {
     actor: string;
     source?: Source;
 }
+export interface ForgetInput {
+    factId: string;
+    actor: string;
+    reason: string;
+    source?: Source;
+}
 export interface RetractInput {
     factId: string;
     actor: string;
@@ -103,8 +129,16 @@ export declare class Ledger {
     assert(input: AssertInput): AssertEvent;
     retract(input: RetractInput): RetractEvent;
     confirm(input: ConfirmInput): ConfirmEvent;
+    /**
+     * Erases a fact's value from the ledger file, keeping its digest, and stops believing it. The file is rewritten in
+     * 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.
+     */
+    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[];
+    /** Every fact ever asserted, with supersession applied and retracted ones included, for audits that must see everything. */
+    facts(): Fact[];
     /** Every event that touched a fact, oldest first: its assert, the assert that superseded it, its confirmation, its retraction. */
     history(factId: string): LedgerEvent[];
     private confirmedAt;

package/dist/ledger.js

@@ -2,7 +2,8 @@
 // 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 { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 export class Ledger {
     events = [];
@@ -95,12 +96,38 @@ export class Ledger {
         this.append(event);
         return event;
     }
+    /**
+     * Erases a fact's value from the ledger file, keeping its digest, and stops believing it. The file is rewritten in
+     * 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.
+     */
+    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`);
+        const txTime = this.now().toISOString();
+        const valueDigest = createHash("sha256").update(canonical(prior.fact.value)).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 };
+            }
+        }
+        const event = { eventId: randomUUID(), kind: "forget", txTime, factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null }, valueDigest };
+        this.events.push(event);
+        const tmp = `${this.file}.tmp`;
+        writeFileSync(tmp, this.events.map((e) => JSON.stringify(e)).join("\n") + "\n");
+        renameSync(tmp, this.file);
+        return event;
+    }
     /** The facts believed at a moment. Valid time answers "was it true then"; transaction time answers "did the ledger know it then". */
     asOf(q = {}) {
         const validAt = q.validAt ?? this.now().toISOString();
         const txAt = q.txAt ?? this.now().toISOString();
         const known = this.events.filter((e) => e.txTime <= txAt);
-        const retracted = new Set(known.filter((e) => e.kind === "retract").map((e) => e.factId));
+        const retracted = new Set(known.filter((e) => e.kind === "retract" || e.kind === "forget").map((e) => e.factId));
         const confirmed = new Set(known.filter((e) => e.kind === "confirm").map((e) => e.factId));
         const facts = new Map();
         for (const e of known) {
@@ -119,6 +146,18 @@ export class Ledger {
             (q.predicate === undefined || f.predicate === q.predicate) &&
             (q.include !== "attested" || f.provenance === "attested"));
     }
+    /** Every fact ever asserted, with supersession applied and retracted ones included, for audits that must see everything. */
+    facts() {
+        const out = new Map();
+        for (const e of this.events) {
+            if (e.kind !== "assert")
+                continue;
+            out.set(e.fact.factId, { ...e.fact });
+            if (e.supersedes && out.has(e.supersedes) && !this.retractedAt(e.fact.factId))
+                out.get(e.supersedes).validTo = e.fact.validFrom;
+        }
+        return [...out.values()];
+    }
     /** Every event that touched a fact, oldest first: its assert, the assert that superseded it, its confirmation, its retraction. */
     history(factId) {
         return this.events.filter((e) => (e.kind === "assert" ? e.fact.factId === factId || e.supersedes === factId : e.factId === factId));
@@ -137,10 +176,28 @@ export class Ledger {
         return found;
     }
     retractedAt(factId) {
-        return this.events.some((e) => e.kind === "retract" && e.factId === factId);
+        return this.events.some((e) => (e.kind === "retract" || e.kind === "forget") && e.factId === factId);
     }
     append(event) {
         appendFileSync(this.file, JSON.stringify(event) + "\n");
         this.events.push(event);
     }
 }
+/** Canonical JSON: sorted keys, no whitespace, undefined dropped. The same encoding the receipts package uses. */
+function canonical(value) {
+    const sort = (v) => {
+        if (Array.isArray(v))
+            return v.map(sort);
+        if (v && typeof v === "object") {
+            const o = {};
+            for (const k of Object.keys(v).sort()) {
+                const x = v[k];
+                if (x !== undefined)
+                    o[k] = sort(x);
+            }
+            return o;
+        }
+        return v;
+    };
+    return JSON.stringify(sort(value));
+}

package/dist/server.d.ts

@@ -1,17 +1,22 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type KeyPair } from "@agent-custody/receipts";
 import type { Ledger } from "./ledger.ts";
 import type { Store } from "./stores.ts";
 export declare const SERVER_VERSION = "0.1.0";
 /** The same keys the receipts gateway sets on the upstream call. Duplicated here so this package needs no runtime import from receipts. */
 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";
 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. */
     requireGateway?: boolean;
     /** Retrieval stores every write goes through to and every retraction reaches. A store that refuses a write fails the write; nothing is recorded. */
     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;
 }
 export declare function createMemoryServer(ledger: Ledger, opts?: MemoryServerOptions): Server;
 /** Serves over stdio, the way the gateway spawns it. Diagnostics must go to stderr. */

package/dist/server.js

@@ -7,10 +7,13 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
+import { signResult } from "@agent-custody/receipts";
 export const SERVER_VERSION = "0.1.0";
 /** The same keys the receipts gateway sets on the upstream call. Duplicated here so this package needs no runtime import from receipts. */
 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";
 const iso = z.string().datetime({ offset: true });
 const Write = z.object({
     subject: z.string().min(1),
@@ -27,6 +30,8 @@ const Read = z.object({ subject: z.string().min(1).optional(), predicate: z.stri
 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 str = { type: "string" };
 export const TOOLS = [
     {
@@ -49,6 +54,16 @@ export const TOOLS = [
         description: "Undo a belief: the fact leaves the present, stays visible to questions about the past, and whatever it superseded is believed again.",
         inputSchema: { type: "object", properties: { factId: str, reason: str, actor: str }, required: ["factId", "reason"] },
     },
+    {
+        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.",
+        inputSchema: { type: "object", properties: { factId: str, reason: str }, required: ["factId", "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.",
+        inputSchema: { type: "object", properties: { factId: str }, required: ["factId"] },
+    },
     {
         name: "memory.history",
         description: "Every event that touched a fact, oldest first.",
@@ -63,15 +78,18 @@ export function createMemoryServer(ledger, opts = {}) {
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const meta = (req.params._meta ?? {});
         const receiptId = typeof meta[RECEIPT_META_KEY] === "string" ? meta[RECEIPT_META_KEY] : null;
+        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 handle(name, args, meta, receiptId) {
         const gatewayAgent = typeof meta[AGENT_META_KEY] === "string" ? meta[AGENT_META_KEY] : null;
         if (opts.requireGateway && !receiptId)
             return fail("memory server accepts calls only through the receipts gateway; no receipt id on this call");
-        const args = req.params.arguments ?? {};
         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";
         try {
-            switch (req.params.name) {
+            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 } : {}) };
@@ -87,7 +105,8 @@ export function createMemoryServer(ledger, opts = {}) {
                 }
                 case "memory.read": {
                     const { includeClaimed, ...q } = Read.parse(args);
-                    return json({ facts: ledger.asOf({ ...q, include: includeClaimed ? "all" : "attested" }) });
+                    const facts = ledger.asOf({ ...q, include: includeClaimed ? "all" : "attested" });
+                    return { ...json({ facts }), _meta: { [FACTS_META_KEY]: facts.map((f) => f.factId) } };
                 }
                 case "memory.retract": {
                     const a = Retract.parse(args);
@@ -119,16 +138,49 @@ export function createMemoryServer(ledger, opts = {}) {
                     const ev = ledger.confirm({ factId: a.factId, actor: actorFor(undefined), source: { receiptId } });
                     return json({ eventId: ev.eventId, factId: ev.factId, txTime: ev.txTime, actor: ev.actor, source: ev.source });
                 }
+                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)
+                            continue;
+                        try {
+                            await store.remove(id, fact);
+                            removedFrom.push(store.name);
+                        }
+                        catch (e) {
+                            stillHeld.push(`${store.name}: ${e instanceof Error ? e.message : String(e)}`);
+                        }
+                    }
+                    const out = { factId: ev.factId, valueDigest: ev.valueDigest, txTime: ev.txTime, actor: ev.actor, reason: ev.reason, source: ev.source, erasedFromLedger: true, removedFrom, 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 json(out);
+                }
+                case "memory.get": {
+                    const a = Get.parse(args);
+                    const f = ledger.facts().find((x) => x.factId === a.factId);
+                    if (!f)
+                        return fail(`unknown fact ${a.factId}`);
+                    const retracted = ledger.history(a.factId).some((e) => e.kind === "retract");
+                    // Cedar has no null: absent fields stay absent, so a policy tests them with `has`.
+                    const clean = Object.fromEntries(Object.entries({ ...f, source: f.source.receiptId ?? undefined, retracted }).filter(([, v]) => v !== null && v !== undefined));
+                    return json(clean);
+                }
                 case "memory.history":
                     return json({ events: ledger.history(History.parse(args).factId) });
                 default:
-                    return fail(`unknown tool ${req.params.name}`);
+                    return fail(`unknown tool ${name}`);
             }
         }
         catch (e) {
             return fail(e instanceof z.ZodError ? `invalid arguments: ${e.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}` : String(e instanceof Error ? e.message : e));
         }
-    });
+    }
     return server;
 }
 /** Serves over stdio, the way the gateway spawns it. Diagnostics must go to stderr. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/state",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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.4",
+    "@agent-custody/receipts": "0.1.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.5.4"
   },