@agent-custody/state 0.1.6 → 0.1.8

package/README.md

@@ -74,19 +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. `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.
+**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
 
@@ -138,9 +138,23 @@ import { Ledger, ledgerUnderTest, runAll, SCENARIOS, formatReport } from "@agent
 console.log(formatReport(await runAll(ledgerUnderTest(new Ledger("./ledger.jsonl")), SCENARIOS)));
 ```
 
+From the shell, on a schedule:
+
+```bash
+agent-custody-memory eval --baseline                                     # built-in scenarios, ledger and a naive store side by side
+agent-custody-memory eval --scenarios incidents.json --sign keys/eval.key --out report.json   # your own incidents, signed report
+agent-custody-memory eval --verify report.json --key keys/eval.pub       # what a reviewer runs
+```
+
+A scenario file is `{ "version": "0.1", "scenarios": [{ "name", "ops": [...] }] }` with the same write, read, and retract ops as the built-ins; every read carries `expect`, null meaning nothing. The file is validated and a bad one names the offending op. The signed report is an in-toto statement over the scores, bound to a digest of the scenarios it ran, in the same envelope format as receipts; `eval --verify` checks the signature and the digest. `eval` exits non-zero when the ledger scores below perfect on the scenarios it was given, so a cron job that runs it fails loudly when a change regresses memory behaviour.
+
 ## The ledger
 
-`src/ledger.ts` is an append-only JSONL log of two kinds of event.
+`src/ledger.ts` keeps an append-only log of events, in memory for its queries and in one of two stores for durability. **JSONL** is the default: one event per line, readable by anyone, the file you copy for an audit. **SQLite** is for durability and shared use, chosen by giving the ledger a path ending in `.sqlite` or `.db`: transactional writes with write-ahead logging, an in-place forget that overwrites the erased value (secure delete, then a truncating checkpoint so nothing lingers in the write-ahead log), indexes by fact and by time, and a file more than one process can open. Node ships the SQLite module, so there is no native dependency; on Node 22 it prints an experimental warning once. `agent-custody-memory export --ledger ledger.sqlite --out ledger.jsonl` writes the auditable JSONL from any store, so the copy-the-file audit path survives the choice. The whole ledger test suite runs against both stores.
+
+Choose JSONL for one server process and for anything an auditor should be able to read with `cat`. Choose SQLite when the ledger is shared over HTTP by several gateways, when a crash between two writes must not cost you an event, or when a deletion demand must leave no trace of the value in the file. Query pushdown to SQLite's indexes is not done yet: both stores load every event into memory, which is fine to tens of thousands of facts. [Issue #8](https://github.com/ch4r10t33r/agent-custody/issues/8) tracks indexed queries for larger ledgers.
+
+The log holds these kinds of event.
 
 - **assert** creates a fact: subject, predicate, value, the space it lives in (a person, a team, an org), the actor that wrote it, the source receipt id if the write went through a receipts producer, and the valid-time interval. An assert may **supersede** an earlier fact, which ends that fact's validity where the new one begins.
 - **retract** says a fact should never have been believed. This is the undo. The record stays, so queries about earlier moments still see the fact, and anything the retracted fact had superseded is believed again.
@@ -159,14 +173,16 @@ The ledger refuses to supersede a fact that is unknown, already superseded, or r
 ## Layout
 
 ```
-src/ledger.ts   the fact record, the two event kinds, as-of queries, supersession, retraction, JSONL persistence
+src/ledger.ts   the fact record, the event kinds, as-of queries, supersession, retraction, forget, holds, sweeps
+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), sweep, blast
+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/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
+src/evals-file.ts    scenario files, validated; signed eval reports and their verification
 src/index.ts    public surface
 examples/       runnable walkthroughs, each ends with OK and is run by the test suite
 test/           one test per question a platform owner asks after a memory incident
@@ -177,8 +193,10 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 
 **Done**
 
-- Bitemporal fact ledger with supersession, retraction, as-of and history queries, persisted as JSONL.
+- Bitemporal fact ledger with supersession, retraction, as-of and history queries, persisted as JSONL or SQLite behind one store interface, with export back to 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.
@@ -187,10 +205,13 @@ tsconfig.build.json  emits dist/ for consumers; the repo itself runs the .ts dir
 - 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 eval CLI: built-in or custom scenario files, the naive baseline beside the ledger, a signed report a reviewer verifies, and a non-zero exit on regression, for cron.
 - 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 retention schedule: run sweeps on a timer from the CLI or a hosted plane, with the receipts of each sweep kept as the record.
+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).
 

package/dist/cli.js

@@ -4,18 +4,55 @@ 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";
+import { loadPrivateKey, loadPublicKey } from "@agent-custody/receipts";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+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 { 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|ledger.sqlite> [--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 --ledger <ledger.jsonl> --before <ISO instant> [--space <space>] --reason <text> [--actor <id>]
-                                                   retention on the ledger file alone: forgets what was learned before the instant, skipping held facts.
-                                                   Through the gateway, memory.sweep does the same and reaches the stores.
+  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.
+  eval [--scenarios <file.json>] [--baseline] [--json] [--sign <key> --out <report.json>]
+                                                   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
+  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
 `;
@@ -23,33 +60,100 @@ 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" }, before: { type: "string" }, space: { type: "string" }, reason: { type: "string" }, actor: { type: "string", default: "cli" } } });
+            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");
-            const r = new Ledger(values.ledger).sweep({ before: new Date(values.before).toISOString(), ...(values.space ? { space: values.space } : {}), actor: values.actor, reason: 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}  digest ${f.valueDigest.slice(0, 12)}`);
+                console.log(`  ${f.factId}  ${f.digestKind}${f.valueDigest ? ` ${f.valueDigest.slice(0, 12)}` : ""}`);
+            return 0;
+        }
+        case "eval": {
+            const { values } = parseArgs({ args: rest, options: { scenarios: { type: "string" }, baseline: { type: "boolean", default: false }, json: { type: "boolean", default: false }, sign: { type: "string" }, out: { type: "string" }, verify: { type: "string" }, key: { type: "string", multiple: true } } });
+            if (values.verify) {
+                if (!values.key?.length)
+                    throw new Error("eval --verify needs --key <pub>");
+                const r = verifyReport(JSON.parse(readFileSync(values.verify, "utf8")), values.key.map(loadPublicKey));
+                if (!r.ok) {
+                    console.log(`NOT VERIFIED: ${r.error}`);
+                    return 1;
+                }
+                console.log(`VERIFIED  signed by ${r.keyid.slice(0, 12)}  system ${r.predicate.system}  ran ${r.predicate.ranAt}  scenarios ${r.predicate.scenarioNames.length} (digest ${r.predicate.scenariosDigest.slice(0, 12)})`);
+                console.log(formatReport(r.predicate.report));
+                return 0;
+            }
+            const scenarios = values.scenarios ? loadScenarios(values.scenarios) : SCENARIOS;
+            const ledger = new Ledger(join(mkdtempSync(join(tmpdir(), "agent-custody-eval-")), "ledger.jsonl"));
+            const report = await runAll(ledgerUnderTest(ledger), scenarios);
+            const baseline = values.baseline ? await runAll(overwriteStoreUnderTest(), scenarios) : null;
+            const regressed = report.totals.correctReads < report.totals.reads || report.scenarios.some((s) => s.failures.length > 0);
+            if (values.json)
+                console.log(JSON.stringify({ ledger: report, baseline }, null, 2));
+            else {
+                console.log("The ledger:");
+                console.log(formatReport(report));
+                if (baseline) {
+                    console.log("\nA naive overwrite store:");
+                    console.log(formatReport(baseline));
+                }
+            }
+            if (values.sign) {
+                if (!values.out)
+                    throw new Error("eval --sign needs --out <report.json>");
+                writeFileSync(values.out, JSON.stringify(signReport("agent-custody-ledger", scenarios, report, loadPrivateKey(values.sign)), null, 2));
+                console.error(`signed report written to ${values.out}`);
+            }
+            return regressed ? 1 : 0;
+        }
+        case "export": {
+            const { values } = parseArgs({ args: rest, options: { ledger: { type: "string" }, out: { type: "string" } } });
+            if (!values.ledger || !values.out)
+                throw new Error("export needs --ledger and --out");
+            const l = new Ledger(values.ledger);
+            writeFileSync(values.out, l.export().map((e) => JSON.stringify(e)).join("\n") + "\n");
+            console.log(`exported ${l.size} event(s) from ${l.location} to ${values.out}`);
+            l.close();
             return 0;
         }
         case "blast": {

package/dist/evals-file.d.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { type Envelope, type KeyPair, type PublicKeyRef } from "@agent-custody/receipts";
+import type { Report, Scenario } from "./evals.ts";
+export declare const EVAL_REPORT_TYPE = "https://agent-custody.dev/eval-report/v0.1";
+export declare const ScenarioFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<"0.1">;
+    scenarios: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        ops: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            op: z.ZodLiteral<"write">;
+            key: z.ZodString;
+            subject: z.ZodString;
+            predicate: z.ZodString;
+            value: z.ZodUnknown;
+            space: z.ZodOptional<z.ZodString>;
+            actor: z.ZodOptional<z.ZodString>;
+            supersedes: z.ZodOptional<z.ZodString>;
+            bad: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            op: z.ZodLiteral<"read">;
+            subject: z.ZodString;
+            predicate: z.ZodOptional<z.ZodString>;
+            space: z.ZodOptional<z.ZodString>;
+            expect: z.ZodUnknown;
+        }, z.core.$strip>, z.ZodObject<{
+            op: z.ZodLiteral<"retract">;
+            key: z.ZodString;
+            actor: z.ZodOptional<z.ZodString>;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "op">>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ScenarioFile = z.infer<typeof ScenarioFileSchema>;
+/** Loads and validates a scenario file. Every read must carry `expect`, null meaning "nothing". */
+export declare function loadScenarios(path: string): Scenario[];
+export interface EvalReportPredicate {
+    system: string;
+    scenariosDigest: string;
+    scenarioNames: string[];
+    report: Report;
+    ranAt: string;
+}
+/** An in-toto statement over the report, signed with the given key: the artefact a reviewer verifies. */
+export declare function signReport(system: string, scenarios: Scenario[], report: Report, key: KeyPair): Envelope;
+export type ReportCheck = {
+    ok: true;
+    predicate: EvalReportPredicate;
+    keyid: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function verifyReport(envelope: Envelope, keys: PublicKeyRef[]): ReportCheck;

package/dist/evals-file.js

@@ -0,0 +1,43 @@
+// Scenario files and signed eval reports. A team encodes its own memory incidents as scenarios, runs them on a
+// schedule, and hands a reviewer a report signed with a key, verifiable with the same envelope format as receipts.
+import { readFileSync } from "node:fs";
+import { z } from "zod";
+import { digestOf, dsseSign, dsseVerify } from "@agent-custody/receipts";
+export const EVAL_REPORT_TYPE = "https://agent-custody.dev/eval-report/v0.1";
+const OpSchema = z.discriminatedUnion("op", [
+    z.object({ op: z.literal("write"), key: z.string().min(1), subject: z.string().min(1), predicate: z.string().min(1), value: z.unknown(), space: z.string().min(1).optional(), actor: z.string().min(1).optional(), supersedes: z.string().min(1).optional(), bad: z.boolean().optional() }),
+    z.object({ op: z.literal("read"), subject: z.string().min(1), predicate: z.string().min(1).optional(), space: z.string().min(1).optional(), expect: z.unknown() }),
+    z.object({ op: z.literal("retract"), key: z.string().min(1), actor: z.string().min(1).optional(), reason: z.string().min(1).optional() }),
+]);
+export const ScenarioFileSchema = z.object({
+    version: z.literal("0.1"),
+    scenarios: z.array(z.object({ name: z.string().min(1), ops: z.array(OpSchema).min(1) })).min(1),
+});
+/** Loads and validates a scenario file. Every read must carry `expect`, null meaning "nothing". */
+export function loadScenarios(path) {
+    const parsed = ScenarioFileSchema.safeParse(JSON.parse(readFileSync(path, "utf8")));
+    if (!parsed.success)
+        throw new Error(`scenario file ${path}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`);
+    for (const [si, s] of parsed.data.scenarios.entries())
+        for (const [oi, o] of s.ops.entries())
+            if (o.op === "read" && !("expect" in o))
+                throw new Error(`scenario file ${path}: scenarios.${si}.ops.${oi}: a read needs expect (null for nothing)`);
+    return parsed.data.scenarios;
+}
+/** An in-toto statement over the report, signed with the given key: the artefact a reviewer verifies. */
+export function signReport(system, scenarios, report, key) {
+    const predicate = { system, scenariosDigest: digestOf(scenarios), scenarioNames: scenarios.map((s) => s.name), report, ranAt: new Date().toISOString() };
+    const statement = { _type: "https://in-toto.io/Statement/v1", subject: [{ name: `eval:${system}`, digest: { sha256: digestOf(report) } }], predicateType: EVAL_REPORT_TYPE, predicate };
+    return dsseSign("application/vnd.in-toto+json", statement, key);
+}
+export function verifyReport(envelope, keys) {
+    const v = dsseVerify(envelope, keys);
+    if (!v.ok)
+        return { ok: false, error: v.error };
+    const st = v.payload;
+    if (st.predicateType !== EVAL_REPORT_TYPE || !st.predicate)
+        return { ok: false, error: `not an eval report: ${String(st.predicateType)}` };
+    if (st.subject?.[0]?.digest?.sha256 !== digestOf(st.predicate.report))
+        return { ok: false, error: "report digest does not match the subject" };
+    return { ok: true, predicate: st.predicate, keyid: v.keyid };
+}

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 export { Ledger } from "./ledger.ts";
-export type { AsOf, AssertEvent, AssertInput, ConfirmEvent, ConfirmInput, Fact, FactProvenance, 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, serveStdio } from "./server.ts";
+export { JsonlStore, SqliteStore, openStore } from "./storage.ts";
+export type { EventStore } from "./storage.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";
 export { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.ts";
+export { EVAL_REPORT_TYPE, ScenarioFileSchema, loadScenarios, signReport, verifyReport } from "./evals-file.ts";
+export type { EvalReportPredicate, ReportCheck, ScenarioFile } from "./evals-file.ts";
 export { factMetadata, factText, mem0Store, zepStore } from "./stores.ts";
 export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.ts";
 export { memoryHttpHandler, serveMemoryHttp } from "./http.ts";

package/dist/index.js

@@ -1,8 +1,10 @@
 // Public surface of @agent-custody/state.
 export { Ledger } from "./ledger.js";
-export { AGENT_META_KEY, FACTS_META_KEY, OBSERVED_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, serveStdio } from "./server.js";
+export { JsonlStore, SqliteStore, openStore } from "./storage.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 { EVAL_REPORT_TYPE, ScenarioFileSchema, loadScenarios, signReport, verifyReport } from "./evals-file.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

@@ -1,3 +1,4 @@
+import { type EventStore } from "./storage.ts";
 /** Where a write came from. A receipt id means the write went through a receipts producer and can be verified there. */
 export interface Source {
     receiptId: string | null;
@@ -22,9 +23,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 */
@@ -61,6 +63,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.
@@ -73,8 +80,9 @@ 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 {
@@ -111,6 +119,8 @@ export interface ForgetInput {
     actor: string;
     reason: string;
     source?: Source;
+    /** false keeps no digest at all; default true */
+    keepDigest?: boolean;
 }
 export interface HoldInput {
     factId: string;
@@ -125,6 +135,7 @@ export interface SweepInput {
     actor: string;
     reason: string;
     source?: Source;
+    keepDigest?: boolean;
 }
 export interface RetractInput {
     factId: string;
@@ -145,11 +156,22 @@ export interface AsOf {
 }
 export declare class Ledger {
     private readonly events;
-    private readonly file;
+    private readonly store;
     private readonly now;
-    constructor(file: string, opts?: {
+    private readonly forgetKey;
+    /**
+     * `location` is a path: JSONL by default, SQLite when it ends in .sqlite or .db; or pass a store.
+     * forgetKey: a secret kept outside the store; with it, forgotten values leave an HMAC rather than a plain hash.
+     */
+    constructor(location: string | EventStore, opts?: {
         now?: () => Date;
+        forgetKey?: string | Buffer;
     });
+    /** Where the events live, for reports. */
+    get location(): string;
+    /** Every event in order, for export. */
+    export(): LedgerEvent[];
+    close(): void;
     get size(): number;
     /** The checks assert makes, without appending. For callers that must do something irreversible before the append. */
     validateAssert(input: AssertInput): void;

package/dist/ledger.js

@@ -2,26 +2,34 @@
 // 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 { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
+import { createHash, createHmac } from "node:crypto";
+import { openStore } from "./storage.js";
 const RANK = { claimed: 0, attested: 1, verified: 2 };
 export class Ledger {
-    events = [];
-    file;
+    events;
+    store;
     now;
-    constructor(file, opts = {}) {
-        this.file = file;
+    forgetKey;
+    /**
+     * `location` is a path: JSONL by default, SQLite when it ends in .sqlite or .db; or pass a store.
+     * forgetKey: a secret kept outside the store; with it, forgotten values leave an HMAC rather than a plain hash.
+     */
+    constructor(location, opts = {}) {
+        this.store = typeof location === "string" ? openStore(location) : location;
         this.now = opts.now ?? (() => new Date());
-        if (existsSync(file)) {
-            for (const line of readFileSync(file, "utf8").split("\n")) {
-                if (line.trim())
-                    this.events.push(JSON.parse(line));
-            }
-        }
-        else {
-            mkdirSync(dirname(file), { recursive: true });
-        }
+        this.forgetKey = opts.forgetKey ? Buffer.from(opts.forgetKey) : null;
+        this.events = this.store.load();
+    }
+    /** Where the events live, for reports. */
+    get location() {
+        return this.store.location;
+    }
+    /** Every event in order, for export. */
+    export() {
+        return [...this.events];
+    }
+    close() {
+        this.store.close();
     }
     get size() {
         return this.events.length;
@@ -139,7 +147,7 @@ export class Ledger {
                 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 } : {}) }));
+            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 };
     }
@@ -152,18 +160,18 @@ export class Ledger {
         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 };
+                this.store.replaceAssert(e);
             }
         }
-        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);
+        const event = { eventId: randomUUID(), kind: "forget", txTime, factId: input.factId, actor: input.actor, reason: input.reason, source: input.source ?? { receiptId: null }, valueDigest, digestKind };
+        this.append(event);
         return event;
     }
     /** The facts believed at a moment. Valid time answers "was it true then"; transaction time answers "did the ledger know it then". */
@@ -223,7 +231,7 @@ export class Ledger {
         return this.events.some((e) => (e.kind === "retract" || e.kind === "forget") && e.factId === factId);
     }
     append(event) {
-        appendFileSync(this.file, JSON.stringify(event) + "\n");
+        this.store.append(event);
         this.events.push(event);
     }
 }

package/dist/server.d.ts

@@ -19,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

@@ -35,9 +35,9 @@ 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, space: z.string().min(1).optional(), 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 = [
     {
@@ -62,8 +62,8 @@ 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.",
-        inputSchema: { type: "object", properties: { factId: str, reason: str }, required: ["factId", "reason"] },
+        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",
@@ -77,8 +77,8 @@ export const TOOLS = [
     },
     {
         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. The receipt is the record of the sweep.",
-        inputSchema: { type: "object", properties: { before: str, space: str, reason: str }, required: ["before", "reason"] },
+        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",
@@ -91,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 = {}) {
@@ -102,9 +119,9 @@ 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) {
+    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 } });
+        const ev = ledger.forget({ factId, actor: currentActor, reason, source: { receiptId: currentReceipt }, ...(keepDigest === undefined ? {} : { keepDigest }) });
         const removedFrom = [];
         const stillHeld = [];
         for (const store of opts.stores ?? []) {
@@ -119,7 +136,7 @@ export function createMemoryServer(ledger, opts = {}) {
                 stillHeld.push(`${store.name}: ${e instanceof Error ? e.message : String(e)}`);
             }
         }
-        return { factId: ev.factId, valueDigest: ev.valueDigest, txTime: ev.txTime, actor: ev.actor, reason: ev.reason, source: ev.source, erasedFromLedger: true, removedFrom, stillHeld };
+        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;
@@ -197,7 +214,7 @@ export function createMemoryServer(ledger, opts = {}) {
                 }
                 case "memory.forget": {
                     const a = Forget.parse(args);
-                    const out = await forgetOne(a.factId, a.reason);
+                    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);
@@ -212,8 +229,15 @@ export function createMemoryServer(ledger, opts = {}) {
                 }
                 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) => ledger.history(f.factId).find((e) => e.kind === "assert" && e.fact.factId === f.factId).txTime < a.before).map((f) => f.factId));
+                    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) {
@@ -223,10 +247,10 @@ export function createMemoryServer(ledger, opts = {}) {
                             held.push(f.factId);
                             continue;
                         }
-                        forgotten.push(await forgetOne(f.factId, a.reason));
+                        forgotten.push(await forgetOne(f.factId, a.reason, a.keepDigest));
                     }
                     const stillHeld = forgotten.flatMap((o) => o.stillHeld);
-                    const out = { before: a.before, space: a.space ?? null, forgotten: forgotten.map((o) => ({ factId: o.factId, valueDigest: o.valueDigest, 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 })), 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/storage.d.ts

@@ -0,0 +1,32 @@
+import type { AssertEvent, LedgerEvent } from "./ledger.ts";
+export interface EventStore {
+    readonly kind: "jsonl" | "sqlite";
+    readonly location: string;
+    /** every event, in order */
+    load(): LedgerEvent[];
+    append(event: LedgerEvent): void;
+    /** replaces one assert event in place, for forget: the value is gone from the store, not merely superseded */
+    replaceAssert(event: AssertEvent): void;
+    close(): void;
+}
+export declare class JsonlStore implements EventStore {
+    readonly kind: "jsonl";
+    readonly location: string;
+    constructor(file: string);
+    load(): LedgerEvent[];
+    append(event: LedgerEvent): void;
+    replaceAssert(event: AssertEvent): void;
+    close(): void;
+}
+export declare class SqliteStore implements EventStore {
+    readonly kind: "sqlite";
+    readonly location: string;
+    private readonly db;
+    constructor(file: string);
+    load(): LedgerEvent[];
+    append(event: LedgerEvent): void;
+    replaceAssert(event: AssertEvent): void;
+    close(): void;
+}
+/** JSONL unless the path ends in .sqlite or .db. */
+export declare function openStore(location: string): EventStore;

package/dist/storage.js

@@ -0,0 +1,67 @@
+// Where the ledger's events live. The ledger keeps every event in memory for its queries; a store makes them durable.
+// JSONL is the default and the auditable artefact: one event per line, readable by anyone, copied for an audit.
+// SQLite is for durability and shared use: transactional writes, write-ahead logging, an in-place forget that leaves
+// no copy of the value behind, and a file more than one process can open. Node ships the SQLite module; no native
+// dependency.
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname } from "node:path";
+export class JsonlStore {
+    kind = "jsonl";
+    location;
+    constructor(file) {
+        this.location = file;
+        if (!existsSync(file))
+            mkdirSync(dirname(file), { recursive: true });
+    }
+    load() {
+        if (!existsSync(this.location))
+            return [];
+        return readFileSync(this.location, "utf8").split("\n").filter((l) => l.trim()).map((l) => JSON.parse(l));
+    }
+    append(event) {
+        appendFileSync(this.location, JSON.stringify(event) + "\n");
+    }
+    replaceAssert(event) {
+        const all = this.load().map((e) => (e.kind === "assert" && e.eventId === event.eventId ? event : e));
+        const tmp = `${this.location}.tmp`;
+        writeFileSync(tmp, all.map((e) => JSON.stringify(e)).join("\n") + "\n");
+        renameSync(tmp, this.location);
+    }
+    close() { }
+}
+export class SqliteStore {
+    kind = "sqlite";
+    location;
+    db;
+    constructor(file) {
+        this.location = file;
+        mkdirSync(dirname(file), { recursive: true });
+        // Loaded on demand so a JSONL ledger never touches the SQLite module, which warns on Node 22 that it is experimental.
+        const { DatabaseSync } = createRequire(import.meta.url)("node:sqlite");
+        this.db = new DatabaseSync(file);
+        // secure_delete overwrites removed content with zeros, so a forgotten value does not linger in freed page space.
+        this.db.exec("PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL; PRAGMA secure_delete = ON;");
+        this.db.exec("CREATE TABLE IF NOT EXISTS events (seq INTEGER PRIMARY KEY AUTOINCREMENT, event_id TEXT NOT NULL UNIQUE, kind TEXT NOT NULL, tx_time TEXT NOT NULL, fact_id TEXT NOT NULL, json TEXT NOT NULL)");
+        this.db.exec("CREATE INDEX IF NOT EXISTS events_fact ON events(fact_id); CREATE INDEX IF NOT EXISTS events_tx ON events(tx_time)");
+    }
+    load() {
+        return this.db.prepare("SELECT json FROM events ORDER BY seq").all().map((r) => JSON.parse(r.json));
+    }
+    append(event) {
+        const factId = event.kind === "assert" ? event.fact.factId : event.factId;
+        this.db.prepare("INSERT INTO events (event_id, kind, tx_time, fact_id, json) VALUES (?, ?, ?, ?, ?)").run(event.eventId, event.kind, event.txTime, factId, JSON.stringify(event));
+    }
+    replaceAssert(event) {
+        this.db.prepare("UPDATE events SET json = ? WHERE event_id = ?").run(JSON.stringify(event), event.eventId);
+        // The old row image would otherwise linger in the write-ahead log; a truncating checkpoint removes it.
+        this.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    }
+    close() {
+        this.db.close();
+    }
+}
+/** JSONL unless the path ends in .sqlite or .db. */
+export function openStore(location) {
+    return /\.(sqlite|db)$/i.test(location) ? new SqliteStore(location) : new JsonlStore(location);
+}

package/package.json

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