@agent-custody/state 0.1.8 → 0.1.9

package/README.md

@@ -45,6 +45,7 @@ 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` |
+| `pack` (CLI) | one fact's history, receipts, holds, blast radius, and forget certificate as one signed artefact, verifiable offline | |
 | `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` |
@@ -84,6 +85,12 @@ A deletion demand is different from a correction. Retract keeps the record; forg
 
 **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.
 
+What forget reaches is the ledger and the stores with adapters. It does not reach caches, a model's context window, application logs, or any store without an adapter. Say that plainly to whoever is relying on it.
+
+**Removal is verified, not assumed.** A delete by id and a search index catching up are different moments. After every retraction, forget, or sweep, the server asks each store's own search whether the fact still surfaces, a few times with backoff, and records the outcome per store in the result and so in the receipt: `verified` (the store's search no longer finds it), `stillIndexed` (it still does, after the retries), `unverified` (the store cannot be asked, or the adapter has no search), or `failed` (the removal itself failed). Mem0 and Zep both verify through their search APIs; the tests drive the real clients against indexes that lag by a configurable number of searches. A certificate that says `stillIndexed` is an honest certificate; run forget again later, or read it as the store's problem to fix.
+
+**The pack.** `agent-custody-memory pack --ledger ... --receipts ... --fact <id> --out pack.json --sign keys/pack.key` gathers everything about one fact into one signed artefact: its history with the receipt that produced each event, its holds and releases, its blast radius with every downstream receipt, and, if it was forgotten, the forget certificate with what each store answered. `pack --verify pack.json --key keys/pack.pub --issuer-key keys/gateway.pub --principal-key keys/principal.pub` checks the pack's signature and digest, every receipt inside it against the gateway's keys, that every event's receipt is present, and that the forget receipt names this fact and records the erasure. Touch one receipt inside and the whole pack fails. It is the artefact counsel attaches to a ticket; the reviewer needs the two public keys and nothing from you.
+
 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.
 
 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.
@@ -177,7 +184,8 @@ src/ledger.ts   the fact record, the event kinds, as-of queries, supersession, r
 src/storage.ts  the event stores: JSONL (default, auditable) and SQLite (durable, shared), chosen by file extension
 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, with --retention and --forget-key-env), sweep (ledger-only or --via a gateway), eval, export, blast
+src/pack.ts     the custody pack: build, sign, verify, format
+src/cli.ts      agent-custody-memory serve (stdio or --http, with --retention and --forget-key-env), sweep (ledger-only or --via a gateway), eval, pack, export, 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
@@ -197,6 +205,8 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 - 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.
+- The custody pack: a fact's history with receipts, holds, blast radius, and forget certificate as one signed artefact, verified as a whole.
+- Removal verification: after a retraction, forget, or sweep the server asks each store's search whether the value still surfaces and records verified, stillIndexed, unverified, or failed per store, in the receipt.
 - 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.
@@ -213,5 +223,5 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 
 1. Indexed queries on the SQLite store, so a shared ledger with millions of events answers reads without loading them all. [Issue #8](https://github.com/ch4r10t33r/agent-custody/issues/8).
 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 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).
+3. The hosted plane, behind early access: tenanted log, then memory, then reports and a control plane, with SSO, SCIM, residency, and SIEM export. [Issue #6](https://github.com/ch4r10t33r/agent-custody/issues/6).
 

package/dist/cli.js

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { formatReport, runAll, SCENARIOS } from "./evals.js";
 import { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.js";
 import { loadScenarios, signReport, verifyReport } from "./evals-file.js";
+import { buildPack, formatPack, signPack, verifyPack } from "./pack.js";
 import { fileURLToPath } from "node:url";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -52,6 +53,11 @@ const USAGE = `agent-custody-memory <command>
                                                    runs the memory-mutation scenarios on a fresh ledger; --baseline also scores a naive
                                                    overwrite store; --sign writes a signed report. Exits 1 if the ledger regresses.
   eval --verify <report.json> --key <pub>          checks a signed report and prints its scores
+  pack --ledger <ledger> --receipts <dir> --fact <factId> --out <pack.json> --sign <key>
+                                                   everything about one fact as one signed artefact: history with receipts, blast radius,
+                                                   holds, the forget certificate and what the stores answered. For counsel and auditors.
+  pack --verify <pack.json> --key <pub> [--issuer-key <pub>] [--principal-key <pub>]
+                                                   checks the pack's signature and every receipt inside it
   export --ledger <ledger.sqlite> --out <ledger.jsonl>  the auditable JSONL of any ledger, one event per line
   blast --ledger <ledger.jsonl> --receipts <dir> --fact <factId> [--json]
                                                    everything that relied on a fact: later calls, derived beliefs, and whether it was retracted
@@ -64,6 +70,8 @@ async function main(argv) {
             if (!values.ledger)
                 throw new Error("serve needs --ledger");
             const ledger = new Ledger(values.ledger, forgetKeyFrom(values["forget-key-env"]));
+            // Printed after the startup line, which supervisors and tests read first for the address.
+            const digestWarning = values["forget-key-env"] ? "" : "agent-custody-memory: no --forget-key-env; forgotten values leave a plain sha256, which is guessable for short values. Set a forget key, or forget with keepDigest false.";
             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 } : {}) };
@@ -73,11 +81,15 @@ async function main(argv) {
                     throw new Error(`serve: environment variable ${values["token-env"]} is not set`);
                 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"}`);
+                if (digestWarning)
+                    console.error(digestWarning);
                 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"}`);
+            if (digestWarning)
+                console.error(digestWarning);
             await serveStdio(createMemoryServer(ledger, common));
             return 0;
         }
@@ -146,6 +158,31 @@ async function main(argv) {
             }
             return regressed ? 1 : 0;
         }
+        case "pack": {
+            const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, receipts: { type: "string" }, fact: { type: "string" }, out: { type: "string" }, sign: { type: "string" }, verify: { type: "string" }, key: { type: "string", multiple: true }, "issuer-key": { type: "string", multiple: true }, "principal-key": { type: "string", multiple: true }, json: { type: "boolean", default: false } } });
+            if (values.verify) {
+                if (!values.key?.length)
+                    throw new Error("pack --verify needs --key <pub>");
+                const r = verifyPack(JSON.parse(readFileSync(values.verify, "utf8")), values.key.map(loadPublicKey), values["issuer-key"]?.length ? { issuerKeys: values["issuer-key"].map(loadPublicKey), principalKeys: (values["principal-key"] ?? []).map(loadPublicKey) } : undefined);
+                if (values.json)
+                    console.log(JSON.stringify(r, null, 2));
+                else {
+                    for (const c of r.checks)
+                        console.log(`${c.ok ? "PASS" : "FAIL"}  ${c.name}${c.detail ? `  (${c.detail})` : ""}`);
+                    console.log(`\nRESULT: ${r.ok ? "VERIFIED" : "NOT VERIFIED"}`);
+                    if (r.pack)
+                        console.log("\n" + formatPack(r.pack));
+                }
+                return r.ok ? 0 : 1;
+            }
+            if (!values.ledger || !values.receipts || !values.fact || !values.out || !values.sign)
+                throw new Error("pack needs --ledger, --receipts, --fact, --out, and --sign");
+            const pack = buildPack(new Ledger(values.ledger), values.receipts, values.fact);
+            writeFileSync(values.out, JSON.stringify(signPack(pack, loadPrivateKey(values.sign)), null, 2));
+            console.log(formatPack(pack));
+            console.error(`signed pack written to ${values.out}`);
+            return pack.missingReceipts.length ? 1 : 0;
+        }
         case "export": {
             const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, out: { type: "string" } } });
             if (!values.ledger || !values.out)

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export type { EvalReportPredicate, ReportCheck, ScenarioFile } from "./evals-fil
 export { factMetadata, factText, mem0Store, zepStore } from "./stores.ts";
 export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.ts";
 export { memoryHttpHandler, serveMemoryHttp } from "./http.ts";
+export { PACK_TYPE, buildPack, formatPack, signPack, verifyPack } from "./pack.ts";
+export type { CustodyPack, PackCheck, PackVerification } from "./pack.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";
+export type { Mem0Like, Mem0Options, RemovalOutcome, Store, ZepLike, ZepOptions } from "./stores.ts";

package/dist/index.js

@@ -8,3 +8,4 @@ export { EVAL_REPORT_TYPE, ScenarioFileSchema, loadScenarios, signReport, verify
 export { factMetadata, factText, mem0Store, zepStore } from "./stores.js";
 export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.js";
 export { memoryHttpHandler, serveMemoryHttp } from "./http.js";
+export { PACK_TYPE, buildPack, formatPack, signPack, verifyPack } from "./pack.js";

package/dist/pack.d.ts

@@ -0,0 +1,49 @@
+import { type Envelope, type KeyPair, type PublicKeyRef, type ReceiptBundle } from "@agent-custody/receipts";
+import { type BlastRadius } from "./blast.ts";
+import type { Fact, Ledger, LedgerEvent } from "./ledger.ts";
+export declare const PACK_TYPE = "https://agent-custody.dev/custody-pack/v0.1";
+export interface CustodyPack {
+    version: "0.1";
+    generatedAt: string;
+    factId: string;
+    fact: Fact | null;
+    /** every event that touched the fact, oldest first */
+    history: LedgerEvent[];
+    /** every receipt referenced by the history or the blast radius, by id, as the full verifiable bundle */
+    receipts: Record<string, ReceiptBundle>;
+    /** receipt ids the history or blast radius cited but no bundle was found for */
+    missingReceipts: string[];
+    blast: BlastRadius;
+    /** the forget event and what the forget receipt recorded, when the fact was forgotten */
+    forget: {
+        event: LedgerEvent;
+        receiptId: string | null;
+        verification: Record<string, string> | null;
+        removedFrom: string[] | null;
+    } | null;
+    /** hold and release events, in order */
+    holds: LedgerEvent[];
+}
+export declare function buildPack(ledger: Ledger, receiptsDir: string, factId: string): CustodyPack;
+export declare function signPack(pack: CustodyPack, key: KeyPair): Envelope;
+export interface PackCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+}
+export interface PackVerification {
+    ok: boolean;
+    checks: PackCheck[];
+    pack: CustodyPack | null;
+}
+/**
+ * Verifies the pack's own signature and digest, then every receipt inside it against the gateway's keys when given,
+ * that every event's source receipt is present, and that the forget receipt's result names this fact.
+ */
+export declare function verifyPack(envelope: Envelope, packKeys: PublicKeyRef[], receiptKeys?: {
+    issuerKeys: PublicKeyRef[];
+    principalKeys?: PublicKeyRef[];
+    logKeys?: PublicKeyRef[];
+    upstreamKeys?: PublicKeyRef[];
+}): PackVerification;
+export declare function formatPack(p: CustodyPack): string;

package/dist/pack.js

@@ -0,0 +1,148 @@
+// The custody pack: everything about one fact as a single artefact a reviewer can verify. Its history with the
+// receipt that produced each event, its blast radius with every downstream receipt, its forget certificate and what
+// the stores answered, all inside one signed statement. Hand it to counsel, an auditor, or the person who asked for
+// the deletion; they need the signing key and the gateway's key, and nothing from you.
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { digestOf, dsseSign, dsseVerify, verifyBundle } from "@agent-custody/receipts";
+import { blastRadius, loadReceipts } from "./blast.js";
+export const PACK_TYPE = "https://agent-custody.dev/custody-pack/v0.1";
+function loadBundles(dir) {
+    const out = new Map();
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith(".json"))
+            continue;
+        try {
+            const bundle = JSON.parse(readFileSync(join(dir, f), "utf8"));
+            const st = JSON.parse(Buffer.from(bundle.envelope.payload, "base64").toString());
+            if (st.predicate?.receiptId)
+                out.set(st.predicate.receiptId, bundle);
+        }
+        catch {
+            // not a bundle; skip
+        }
+    }
+    return out;
+}
+function receiptResult(bundle) {
+    try {
+        const st = JSON.parse(Buffer.from(bundle.envelope.payload, "base64").toString());
+        const text = st.predicate?.execution?.result?.content?.find((c) => c.type === "text")?.text;
+        if (!text)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    catch {
+        return null; // a damaged bundle; the receipt check reports it
+    }
+}
+export function buildPack(ledger, receiptsDir, factId) {
+    const bundles = loadBundles(receiptsDir);
+    const history = ledger.history(factId);
+    const blast = blastRadius(ledger, loadReceipts(receiptsDir), factId);
+    const wanted = new Set();
+    for (const e of history) {
+        const src = e.kind === "assert" ? e.fact.source.receiptId : e.source.receiptId;
+        if (src)
+            wanted.add(src);
+    }
+    for (const r of blast.receipts)
+        wanted.add(r.receiptId);
+    for (const f of blast.derivedFacts)
+        if (f.source.receiptId)
+            wanted.add(f.source.receiptId);
+    const receipts = {};
+    const missingReceipts = [];
+    for (const id of [...wanted].sort()) {
+        const b = bundles.get(id);
+        if (b)
+            receipts[id] = b;
+        else
+            missingReceipts.push(id);
+    }
+    const forgetEvent = history.find((e) => e.kind === "forget");
+    let forget = null;
+    if (forgetEvent && forgetEvent.kind === "forget") {
+        const rid = forgetEvent.source.receiptId;
+        const result = rid && receipts[rid] ? receiptResult(receipts[rid]) : null;
+        forget = { event: forgetEvent, receiptId: rid, verification: result?.verification ?? null, removedFrom: result?.removedFrom ?? null };
+    }
+    return {
+        version: "0.1",
+        generatedAt: new Date().toISOString(),
+        factId,
+        fact: blast.fact,
+        history,
+        receipts,
+        missingReceipts,
+        blast,
+        forget,
+        holds: history.filter((e) => e.kind === "hold" || e.kind === "release"),
+    };
+}
+export function signPack(pack, key) {
+    const statement = { _type: "https://in-toto.io/Statement/v1", subject: [{ name: `custody-pack:${pack.factId}`, digest: { sha256: digestOf(pack) } }], predicateType: PACK_TYPE, predicate: pack };
+    return dsseSign("application/vnd.in-toto+json", statement, key);
+}
+/**
+ * Verifies the pack's own signature and digest, then every receipt inside it against the gateway's keys when given,
+ * that every event's source receipt is present, and that the forget receipt's result names this fact.
+ */
+export function verifyPack(envelope, packKeys, receiptKeys) {
+    const checks = [];
+    const add = (name, ok, detail) => {
+        checks.push(detail === undefined ? { name, ok } : { name, ok, detail });
+        return ok;
+    };
+    const v = dsseVerify(envelope, packKeys);
+    if (!v.ok) {
+        add("pack signature", false, v.error);
+        return { ok: false, checks, pack: null };
+    }
+    add("pack signature", true, `keyid ${v.keyid.slice(0, 12)}`);
+    const st = v.payload;
+    if (!add("pack type", st.predicateType === PACK_TYPE && !!st.predicate))
+        return { ok: false, checks, pack: null };
+    const pack = st.predicate;
+    add("pack digest", st.subject?.[0]?.digest?.sha256 === digestOf(pack));
+    add("no receipts missing", pack.missingReceipts.length === 0, pack.missingReceipts.length ? `${pack.missingReceipts.length} cited receipt(s) absent` : undefined);
+    for (const e of pack.history) {
+        const src = e.kind === "assert" ? e.fact.source.receiptId : e.source.receiptId;
+        if (src)
+            add(`${e.kind} event cites a receipt in the pack`, src in pack.receipts, src.slice(0, 8));
+    }
+    if (receiptKeys) {
+        for (const [id, bundle] of Object.entries(pack.receipts)) {
+            const r = verifyBundle(bundle, { issuerKeys: receiptKeys.issuerKeys, principalKeys: receiptKeys.principalKeys ?? [], ...(receiptKeys.logKeys ? { logKeys: receiptKeys.logKeys } : {}), ...(receiptKeys.upstreamKeys ? { upstreamKeys: receiptKeys.upstreamKeys } : {}) });
+            add(`receipt ${id.slice(0, 8)} verifies`, r.ok, r.ok ? undefined : r.checks.filter((c) => !c.ok).map((c) => c.name).join(", "));
+            if (r.ok && r.statement && r.statement.predicate.receiptId !== id)
+                add(`receipt ${id.slice(0, 8)} is the receipt it claims to be`, false);
+        }
+    }
+    else {
+        add("receipts checked against the gateway's keys", false, "no issuer key given; pass --issuer-key to check the receipts inside the pack");
+    }
+    if (pack.forget) {
+        const bundle = pack.forget.receiptId ? pack.receipts[pack.forget.receiptId] : undefined;
+        const result = bundle ? receiptResult(bundle) : null;
+        add("forget receipt names this fact and records the erasure", !!result && result.factId === pack.factId && result.erasedFromLedger === true, bundle ? undefined : "forget receipt not in the pack");
+    }
+    return { ok: checks.every((c) => c.ok), checks, pack };
+}
+export function formatPack(p) {
+    const lines = [];
+    lines.push(p.fact ? `fact ${p.factId}: ${p.fact.subject} ${p.fact.predicate}${p.fact.forgotten ? " = (erased)" : ` = ${JSON.stringify(p.fact.value)}`} (space ${p.fact.space}, by ${p.fact.actor}, ${p.fact.provenance})` : `fact ${p.factId}: not in this ledger`);
+    lines.push(`history: ${p.history.map((e) => e.kind).join(" → ")}`);
+    lines.push(`receipts in pack: ${Object.keys(p.receipts).length}${p.missingReceipts.length ? `, missing ${p.missingReceipts.length}` : ""}`);
+    if (p.holds.length)
+        lines.push(`holds: ${p.holds.map((e) => (e.kind === "hold" || e.kind === "release" ? `${e.kind} by ${e.actor} (${e.reason})` : e.kind)).join("; ")}`);
+    if (p.forget)
+        lines.push(`forgotten at ${p.forget.event.txTime} by ${p.forget.event.actor}; receipt ${p.forget.receiptId?.slice(0, 8) ?? "none"}; stores: ${p.forget.verification ? Object.entries(p.forget.verification).map(([k, v]) => `${k}=${v}`).join(", ") : "none"}`);
+    lines.push(`blast radius: ${p.blast.receipts.length} later call(s), ${p.blast.derivedFacts.length} derived belief(s), ${p.blast.stillBelieved.length} still believed`);
+    return lines.join("\n");
+}

package/dist/server.d.ts

@@ -21,6 +21,11 @@ export interface MemoryServerOptions {
     identity?: KeyPair;
     /** Retention windows by space pattern, ISO 8601 durations: { "org": "P365D", "team:*": "P90D" }. memory.sweep without `before` uses them. */
     retention?: Record<string, string>;
+    /** After a removal, how many times to ask a store's search whether the value is gone, and the first wait between asks (doubling). Default 3 and 200 ms. */
+    verify?: {
+        attempts?: number;
+        delayMs?: number;
+    };
 }
 /** 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;

package/dist/server.js

@@ -119,11 +119,16 @@ 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 }) });
+    /**
+     * Removes a fact from every store it was written to, then asks each store's search whether it is really gone.
+     * The outcome per store is what the receipt records: verified, stillIndexed, unverified (the store cannot say), or failed.
+     */
+    async function removeFromStores(fact) {
         const removedFrom = [];
         const stillHeld = [];
+        const verification = {};
+        const attempts = Math.max(1, opts.verify?.attempts ?? 3);
+        const delayMs = opts.verify?.delayMs ?? 200;
         for (const store of opts.stores ?? []) {
             const id = fact?.external?.[store.name];
             if (!id)
@@ -134,9 +139,36 @@ export function createMemoryServer(ledger, opts = {}) {
             }
             catch (e) {
                 stillHeld.push(`${store.name}: ${e instanceof Error ? e.message : String(e)}`);
+                verification[store.name] = "failed";
+                continue;
+            }
+            if (!store.verifyRemoved) {
+                verification[store.name] = "unverified";
+                continue;
+            }
+            let gone = false;
+            let checked = true;
+            for (let i = 0; i < attempts && !gone; i++) {
+                if (i > 0)
+                    await new Promise((r) => setTimeout(r, delayMs * 2 ** (i - 1)));
+                try {
+                    gone = await store.verifyRemoved(id, fact);
+                }
+                catch {
+                    // The store could not be asked; that is not the same as the value being gone.
+                    checked = false;
+                    break;
+                }
             }
+            verification[store.name] = !checked ? "unverified" : gone ? "verified" : "stillIndexed";
         }
-        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 };
+        return { removedFrom, stillHeld, verification };
+    }
+    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, stillHeld, verification } = await removeFromStores(fact);
+        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, verification };
     }
     let currentActor = "anonymous";
     let currentReceipt = null;
@@ -188,19 +220,8 @@ export function createMemoryServer(ledger, opts = {}) {
                     const ev = ledger.retract({ factId: a.factId, actor: actorFor(a.actor), reason: a.reason, source: { receiptId } });
                     // The ledger is retracted first: custody must not depend on a store being up. A store that fails to remove
                     // is reported, so the caller knows recall may still serve the value.
-                    const stillHeld = [];
-                    for (const store of opts.stores ?? []) {
-                        const id = fact?.external?.[store.name];
-                        if (!id)
-                            continue;
-                        try {
-                            await store.remove(id, fact);
-                        }
-                        catch (e) {
-                            stillHeld.push(`${store.name}: ${e instanceof Error ? e.message : String(e)}`);
-                        }
-                    }
-                    const out = { eventId: ev.eventId, factId: ev.factId, txTime: ev.txTime, actor: ev.actor, reason: ev.reason, source: ev.source, removedFrom: (opts.stores ?? []).map((s) => s.name).filter((n) => fact?.external?.[n] && !stillHeld.some((h) => h.startsWith(n))) };
+                    const { removedFrom, stillHeld, verification } = await removeFromStores(fact);
+                    const out = { eventId: ev.eventId, factId: ev.factId, txTime: ev.txTime, actor: ev.actor, reason: ev.reason, source: ev.source, removedFrom, verification };
                     if (stillHeld.length > 0)
                         return { isError: true, content: [{ type: "text", text: `retracted in the ledger, but still held by ${stillHeld.join("; ")}` }, { type: "text", text: JSON.stringify(out) }] };
                     return json(out);
@@ -250,7 +271,7 @@ export function createMemoryServer(ledger, opts = {}) {
                         forgotten.push(await forgetOne(f.factId, a.reason, a.keepDigest));
                     }
                     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 };
+                    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, verification: o.verification })), held, stillHeld };
                     if (stillHeld.length > 0)
                         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);

package/dist/stores.d.ts

@@ -4,9 +4,16 @@ export interface Store {
     readonly name: string;
     /** writes the fact and returns the store's own id for it */
     put(fact: Fact): Promise<string>;
-    /** removes the fact from the store; called on retraction */
+    /** removes the fact from the store; called on retraction and forget */
     remove(externalId: string, fact: Fact): Promise<void>;
+    /**
+     * Checks the store's own search no longer surfaces the fact: a delete by id and a search index catching up are
+     * different moments. Optional; a store without it is reported as unverified, never as verified.
+     */
+    verifyRemoved?(externalId: string, fact: Fact): Promise<boolean>;
 }
+/** What the server reports per store after a removal. */
+export type RemovalOutcome = "verified" | "stillIndexed" | "unverified" | "failed";
 /** One line a retrieval store can index: what the fact says, in words. */
 export declare function factText(f: Fact): string;
 /** Metadata every store receives alongside the text, so a memory can always be traced back to its custody. */
@@ -20,6 +27,12 @@ export interface Mem0Like {
         id?: string;
     }[]>;
     delete(memoryId: string): Promise<unknown>;
+    search?(query: string, options?: Record<string, unknown>): Promise<{
+        results: {
+            id?: string;
+            memory?: string;
+        }[];
+    }>;
 }
 export interface Mem0Options {
     userId: string;
@@ -43,6 +56,22 @@ export interface ZepLike {
         episode: {
             delete(uuid: string): Promise<unknown>;
         };
+        search?(request: {
+            userId?: string;
+            graphId?: string;
+            query: string;
+            limit?: number;
+        }): Promise<{
+            edges?: {
+                uuid: string;
+                fact: string;
+                episodes?: string[];
+            }[];
+            episodes?: {
+                uuid: string;
+                content: string;
+            }[];
+        }>;
     };
 }
 export type ZepOptions = {

package/dist/stores.js

@@ -19,6 +19,15 @@ export function mem0Store(client, opts) {
         async remove(externalId) {
             await client.delete(externalId);
         },
+        ...(client.search
+            ? {
+                async verifyRemoved(externalId, fact) {
+                    // Mem0's search scopes by filters, not by top-level entity parameters; the real client refuses the latter.
+                    const { results } = await client.search(factText(fact), { filters: { user_id: opts.userId } });
+                    return !results.some((r) => r.id === externalId || r.memory === factText(fact));
+                },
+            }
+            : {}),
     };
 }
 export function zepStore(client, opts) {
@@ -34,5 +43,16 @@ export function zepStore(client, opts) {
         async remove(externalId) {
             await client.graph.episode.delete(externalId);
         },
+        ...(client.graph.search
+            ? {
+                async verifyRemoved(externalId, fact) {
+                    const target = opts.graphId ? { graphId: opts.graphId } : { userId: opts.userId };
+                    const r = await client.graph.search({ ...target, query: factText(fact), limit: 20 });
+                    const episodeHit = (r.episodes ?? []).some((e) => e.uuid === externalId);
+                    const edgeHit = (r.edges ?? []).some((e) => (e.episodes ?? []).includes(externalId));
+                    return !episodeHit && !edgeHit;
+                },
+            }
+            : {}),
     };
 }

package/package.json

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