@agent-custody/state 0.1.2 → 0.1.4

package/README.md

@@ -22,7 +22,62 @@ ledger.retract({ factId: a.fact.factId, actor: "user:admin", reason: "poisoned b
 ledger.asOf({ validAt: "2026-09-01T00:00:00Z", txAt: "2026-09-01T00:00:00Z" });
 ```
 
-Two runnable examples, both executed by the test suite. [01-ledger.ts](examples/01-ledger.ts) walks through a wrong write and its undo. [02-receipt-to-belief.ts](examples/02-receipt-to-belief.ts) runs the whole loop with the receipts package: a tool call gets a signed receipt, the receipt is verified, the belief taken from it is recorded citing the receipt, and later retracted. Run them with `node examples/<file>` from this directory, after `bun run build` at the repository root.
+Four runnable examples, all executed by the test suite. [04-evals.ts](examples/04-evals.ts) scores the ledger and a naive store on the same memory incidents. [03-memory-behind-the-gateway.ts](examples/03-memory-behind-the-gateway.ts) runs the memory server as the gateway's upstream. [01-ledger.ts](examples/01-ledger.ts) walks through a wrong write and its undo. [02-receipt-to-belief.ts](examples/02-receipt-to-belief.ts) runs the whole loop with the receipts package: a tool call gets a signed receipt, the receipt is verified, the belief taken from it is recorded citing the receipt, and later retracted. Run them with `node examples/<file>` from this directory, after `bun run build` at the repository root.
+
+## The memory server
+
+The ledger as MCP tools, meant to run as the upstream of the receipts gateway. Behind the gateway, every write and read is checked by the Cedar policy and gets a signed receipt, and two things reach this server in the call's `_meta` that no caller can supply: the receipt id, which becomes the fact's `source`, and the agent from the signed delegation grant, which becomes the fact's `actor`. A caller's own claims about either are ignored.
+
+```bash
+agent-custody-memory serve --ledger ./ledger.jsonl        # over stdio; refuses calls that did not come through the gateway
+```
+
+In the gateway's config, the memory server is the upstream, and the grant names the memory tools as scopes:
+
+```json
+{ "upstream": { "command": "agent-custody-memory", "args": ["serve", "--ledger", "/abs/path/ledger.jsonl"] }, ... }
+```
+
+| tool | does | policy sees |
+| --- | --- | --- |
+| `memory.write` | records a belief in a space, optionally superseding an earlier fact | `context.args.space`, `subject`, `predicate`, `value` |
+| `memory.read` | the facts believed at a moment, by space, subject, predicate, valid time, transaction time | the query |
+| `memory.confirm` | lifts a quarantined fact to attested; accepted only through the gateway | `factId` |
+| `memory.retract` | undoes a belief, keeping it visible to questions about the past | `factId`, `reason` |
+| `memory.history` | every event that touched a fact | `factId` |
+
+**Quarantine.** Every fact carries a provenance. A write that came through the gateway is `attested`: its actor is the agent named in a human-signed grant and its receipt exists. A write that arrived any other way is `claimed`, and claimed facts are quarantined: `memory.read` leaves them out unless the caller asks for `includeClaimed`, and the policy can refuse that. `memory.confirm`, accepted only through the gateway, lifts a claimed fact to attested with its own receipt and transaction time, so "was this fact still in quarantine on Tuesday" is answerable. A tool result an SDK-only agent wrote down cannot become something the rest of the fleet believes until an attested party says so. Today the server has one client, over stdio, so claimed facts reach a gateway-fronted ledger by being there before it was put under the gateway, or by a direct writer sharing the file; a shared memory server over HTTP, on the plan, is what makes mixed attested and self-reported writers a live deployment.
+
+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.
+
+## Write-through to the stores you already use
+
+The ledger is not a retrieval store, and it does not try to be. `src/stores.ts` puts it under the ones teams already run: a fact written through the memory server also lands in every configured store, with its custody metadata (fact id, space, actor, provenance, receipt id), the store's own id is recorded on the fact, and a retraction reaches the store by that id. Certified forget will be built on this: a deletion is only real once it has reached the stores that serve recall.
+
+```ts
+import { MemoryClient } from "mem0ai";
+import { ZepClient } from "@getzep/zep-cloud";
+import { Ledger, createMemoryServer, mem0Store, zepStore } from "@agent-custody/state";
+
+const stores = [
+  mem0Store(new MemoryClient({ apiKey: process.env.MEM0_API_KEY! }), { userId: "user_42" }),   // infer is off: the memory is the fact, verbatim
+  zepStore(new ZepClient({ apiKey: process.env.ZEP_API_KEY! }), { userId: "user_42" }),         // or { graphId } for a shared graph
+];
+createMemoryServer(new Ledger("./ledger.jsonl"), { stores });
+```
+
+Order matters and is fixed: the ledger's checks run first, so a write it would refuse never reaches a store; the stores are written next, so their ids can be recorded; the ledger appends last. A store that refuses the write fails the write and nothing is recorded anywhere. On retraction the ledger goes first, since custody must not depend on a store being up, and a store that fails to remove is named in the error so the caller knows recall may still serve the value. The adapters are typed structurally and carry no runtime dependency on either vendor; the tests drive the real `mem0ai` and `@getzep/zep-cloud` clients against fake endpoints, offline.
+
+## Scoring memory mutations
+
+`src/evals.ts` is a harness that scores a memory system on what goes wrong after writes, not on recall. A scenario is a script of writes, reads, supersessions, and retractions with the value a correct system returns at each read. The score counts stale reads (a value served after a correction was known), contradictions (two values for one subject and predicate at once), blast radius (reads that served a write the scenario marks as bad), and correct reads. Any system behind the small `MemoryUnderTest` interface can be scored; this ledger and a naive overwrite store ship as the two reference points, and [examples/04-evals.ts](examples/04-evals.ts) prints both reports side by side.
+
+```ts
+import { Ledger, ledgerUnderTest, runAll, SCENARIOS, formatReport } from "@agent-custody/state";
+console.log(formatReport(await runAll(ledgerUnderTest(new Ledger("./ledger.jsonl")), SCENARIOS)));
+```
 
 ## The ledger
 
@@ -46,6 +101,11 @@ The ledger refuses to supersede a fact that is unknown, already superseded, or r
 
 ```
 src/ledger.ts   the fact record, the two event kinds, as-of queries, supersession, retraction, JSONL persistence
+src/server.ts   the ledger as MCP tools; source and actor taken from the gateway's _meta
+src/cli.ts      agent-custody-memory serve
+src/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/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
@@ -57,12 +117,14 @@ 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.
+- 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.
+- Write-through adapters for Mem0 and Zep: every write lands in the store with custody metadata, the store id is recorded on the fact, retractions reach the store, and failures are ordered so nothing is half-recorded.
+- The memory-mutation eval harness: stale reads, contradictions, blast radius, and correct reads over scripted incidents, scored the same way for the ledger and for anything behind the same interface.
+- Quarantine: facts carry `attested` or `claimed` provenance; claimed facts are hidden from reads by default and a gateway-only `memory.confirm` lifts them, as a recorded event.
 
 **Next, in the order it pays off**
 
-1. A memory MCP server exposing write, read, supersede, and forget as tools, run behind the receipts gateway so every call is receipted and policy-checked and the source receipt id is filled in by the gateway rather than the caller.
-2. A consumed-facts field on receipts: the gateway records which fact ids a read returned, so later receipts in the session show what the agent relied on.
-3. Blast radius: given a fact id, every downstream receipt and derived fact that cited it.
-4. Trust tiers as Cedar policies over spaces and receipt provenance: a self-reported write cannot overwrite an org-space fact that was attested through the gateway.
-5. Write-through adapters for existing memory stores, tested against the real packages.
-6. Signed forget statements: a retention or deletion request produces a verifiable record of which facts were removed.
+1. A consumed-facts field on receipts: the gateway records which fact ids a read returned, so later receipts in the session show what the agent relied on.
+2. Blast radius: given a fact id, every downstream receipt and derived fact that cited it, and the retraction that undoes the belief.
+3. Trust tiers, the rest: Cedar policy over provenance so a claimed write cannot supersede an attested org-space fact, and quarantine of values that came from untrusted tool output even when the actor is attested.
+4. Signed forget statements: a retention or deletion request produces a verifiable record of which facts were removed from the ledger and from every store behind it.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { Ledger } from "./ledger.js";
+import { createMemoryServer, serveStdio } from "./server.js";
+const USAGE = `agent-custody-memory <command>
+
+  serve --ledger <ledger.jsonl> [--allow-direct]   the memory server over stdio; run it as the receipts gateway's upstream.
+                                                   By default it refuses calls that did not come through the gateway.
+`;
+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 } } });
+            if (!values.ledger)
+                throw new Error("serve needs --ledger");
+            const ledger = new Ledger(values.ledger);
+            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"] }));
+            return 0;
+        }
+        default:
+            console.error(USAGE);
+            return cmd === undefined || cmd === "--help" || cmd === "-h" ? 0 : 2;
+    }
+}
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    console.error(`error: ${e instanceof Error ? e.message : e}`);
+    process.exit(1);
+});

package/dist/evals-ledger.d.ts

@@ -0,0 +1,8 @@
+import { Ledger } from "./ledger.ts";
+import type { MemoryUnderTest } from "./evals.ts";
+export declare function ledgerUnderTest(ledger: Ledger): MemoryUnderTest;
+/**
+ * A key-value memory that overwrites on write and deletes on retract: the shape most memory layers have. It has no
+ * idea what a retracted value displaced, so a retraction leaves a hole where the earlier belief should return.
+ */
+export declare function overwriteStoreUnderTest(): MemoryUnderTest;

package/dist/evals-ledger.js

@@ -0,0 +1,30 @@
+export function ledgerUnderTest(ledger) {
+    return {
+        write: (i) => ({ id: ledger.assert({ ...i, provenance: "attested" }).fact.factId }),
+        read: (q) => ledger.asOf({ ...q, include: "attested" }).map(({ subject, predicate, value }) => ({ subject, predicate, value })),
+        retract: (i) => {
+            ledger.retract({ factId: i.id, actor: i.actor, reason: i.reason });
+        },
+    };
+}
+/**
+ * A key-value memory that overwrites on write and deletes on retract: the shape most memory layers have. It has no
+ * idea what a retracted value displaced, so a retraction leaves a hole where the earlier belief should return.
+ */
+export function overwriteStoreUnderTest() {
+    const rows = new Map();
+    let n = 0;
+    return {
+        write: (i) => {
+            const id = `m${++n}`;
+            rows.set(`${i.space}|${i.subject}|${i.predicate}`, { id, subject: i.subject, predicate: i.predicate, value: i.value });
+            return { id };
+        },
+        read: (q) => [...rows.values()].filter((r) => r.subject === q.subject && (!q.predicate || r.predicate === q.predicate)).map(({ subject, predicate, value }) => ({ subject, predicate, value })),
+        retract: (i) => {
+            for (const [k, r] of rows)
+                if (r.id === i.id)
+                    rows.delete(k);
+        },
+    };
+}

package/dist/evals.d.ts

@@ -0,0 +1,74 @@
+import type { Fact } from "./ledger.ts";
+/** What the harness needs from a memory system. Reads return whatever the system would give an agent right now. */
+export interface MemoryUnderTest {
+    write(input: {
+        subject: string;
+        predicate: string;
+        value: unknown;
+        space: string;
+        actor: string;
+        supersedes?: string;
+    }): Promise<{
+        id: string;
+    }> | {
+        id: string;
+    };
+    read(query: {
+        subject: string;
+        predicate?: string;
+        space?: string;
+    }): Promise<Pick<Fact, "subject" | "predicate" | "value">[]> | Pick<Fact, "subject" | "predicate" | "value">[];
+    retract(input: {
+        id: string;
+        actor: string;
+        reason: string;
+    }): Promise<void> | void;
+}
+export type Op = {
+    op: "write";
+    key: string;
+    subject: string;
+    predicate: string;
+    value: unknown;
+    space?: string;
+    actor?: string;
+    supersedes?: string; /** the harness marks this write as wrong; later reads that return its value count against the system */
+    bad?: boolean;
+} | {
+    op: "read";
+    subject: string;
+    predicate?: string;
+    space?: string; /** the single value a correct system returns, or null for nothing */
+    expect: unknown | null;
+} | {
+    op: "retract";
+    key: string;
+    actor?: string;
+    reason?: string;
+};
+export interface Scenario {
+    name: string;
+    ops: Op[];
+}
+export interface ScenarioScore {
+    name: string;
+    reads: number;
+    /** reads that returned a value the scenario says should no longer be believed */
+    staleReads: number;
+    /** reads that returned more than one value for one subject and predicate */
+    contradictions: number;
+    /** reads that returned the value of a write marked bad, before or after its retraction */
+    blastRadius: number;
+    /** reads whose result matched exactly what the scenario expected */
+    correctReads: number;
+    failures: string[];
+}
+export interface Report {
+    scenarios: ScenarioScore[];
+    totals: Omit<ScenarioScore, "name" | "failures">;
+}
+export declare function runScenario(system: MemoryUnderTest, scenario: Scenario): Promise<ScenarioScore>;
+export declare function runAll(system: MemoryUnderTest, scenarios: Scenario[]): Promise<Report>;
+/** The built-in scenarios: each is a memory incident a platform owner has actually had. */
+export declare const SCENARIOS: Scenario[];
+export declare function formatReport(r: Report): string;

package/dist/evals.js

@@ -0,0 +1,104 @@
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+export async function runScenario(system, scenario) {
+    const ids = new Map();
+    const badValues = [];
+    const score = { name: scenario.name, reads: 0, staleReads: 0, contradictions: 0, blastRadius: 0, correctReads: 0, failures: [] };
+    for (const [i, op] of scenario.ops.entries()) {
+        try {
+            if (op.op === "write") {
+                const supersedes = op.supersedes ? ids.get(op.supersedes) : undefined;
+                if (op.supersedes && !supersedes)
+                    throw new Error(`write ${op.key} supersedes unknown key ${op.supersedes}`);
+                const { id } = await system.write({ subject: op.subject, predicate: op.predicate, value: op.value, space: op.space ?? "org", actor: op.actor ?? "agent", ...(supersedes ? { supersedes } : {}) });
+                ids.set(op.key, id);
+                if (op.bad)
+                    badValues.push(op.value);
+            }
+            else if (op.op === "retract") {
+                const id = ids.get(op.key);
+                if (!id)
+                    throw new Error(`retract of unknown key ${op.key}`);
+                await system.retract({ id, actor: op.actor ?? "admin", reason: op.reason ?? "wrong" });
+            }
+            else {
+                score.reads++;
+                const facts = await system.read({ subject: op.subject, ...(op.predicate ? { predicate: op.predicate } : {}), ...(op.space ? { space: op.space } : {}) });
+                const values = facts.map((f) => f.value);
+                const byPredicate = new Map();
+                for (const f of facts)
+                    byPredicate.set(f.predicate, [...(byPredicate.get(f.predicate) ?? []), f.value]);
+                if ([...byPredicate.values()].some((vs) => vs.length > 1))
+                    score.contradictions++;
+                if (values.some((v) => badValues.some((b) => same(b, v))))
+                    score.blastRadius++;
+                const correct = op.expect === null ? values.length === 0 : values.length === 1 && same(values[0], op.expect);
+                if (correct)
+                    score.correctReads++;
+                else if (values.length > 0 && !values.some((v) => same(v, op.expect)))
+                    score.staleReads++;
+                else if (values.length > 1)
+                    score.staleReads++;
+            }
+        }
+        catch (e) {
+            score.failures.push(`op ${i} (${op.op}): ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    return score;
+}
+export async function runAll(system, scenarios) {
+    const results = [];
+    for (const s of scenarios)
+        results.push(await runScenario(system, s));
+    const totals = results.reduce((t, s) => ({ reads: t.reads + s.reads, staleReads: t.staleReads + s.staleReads, contradictions: t.contradictions + s.contradictions, blastRadius: t.blastRadius + s.blastRadius, correctReads: t.correctReads + s.correctReads }), { reads: 0, staleReads: 0, contradictions: 0, blastRadius: 0, correctReads: 0 });
+    return { scenarios: results, totals };
+}
+/** The built-in scenarios: each is a memory incident a platform owner has actually had. */
+export const SCENARIOS = [
+    {
+        name: "correction: a superseded value must stop being served",
+        ops: [
+            { op: "write", key: "a", subject: "acct:42", predicate: "plan", value: "pro" },
+            { op: "read", subject: "acct:42", predicate: "plan", expect: "pro" },
+            { op: "write", key: "b", subject: "acct:42", predicate: "plan", value: "enterprise", supersedes: "a" },
+            { op: "read", subject: "acct:42", predicate: "plan", expect: "enterprise" },
+        ],
+    },
+    {
+        name: "contradiction: two writers, one belief",
+        ops: [
+            { op: "write", key: "a", subject: "acct:42", predicate: "owner", value: "dana", actor: "support" },
+            { op: "write", key: "b", subject: "acct:42", predicate: "owner", value: "mallory", actor: "intern", supersedes: "a" },
+            { op: "read", subject: "acct:42", predicate: "owner", expect: "mallory" },
+            { op: "retract", key: "b", reason: "poisoned tool result" },
+            { op: "read", subject: "acct:42", predicate: "owner", expect: "dana" },
+        ],
+    },
+    {
+        name: "blast radius: a bad write is retracted and must not be served afterwards",
+        ops: [
+            { op: "write", key: "good", subject: "acct:7", predicate: "credit_limit", value: 1000 },
+            { op: "write", key: "bad", subject: "acct:7", predicate: "credit_limit", value: 1000000, supersedes: "good", bad: true },
+            { op: "read", subject: "acct:7", predicate: "credit_limit", expect: 1000000 },
+            { op: "read", subject: "acct:7", predicate: "credit_limit", expect: 1000000 },
+            { op: "retract", key: "bad" },
+            { op: "read", subject: "acct:7", predicate: "credit_limit", expect: 1000 },
+            { op: "read", subject: "acct:7", predicate: "credit_limit", expect: 1000 },
+        ],
+    },
+    {
+        name: "retraction with nothing underneath: the belief must disappear, not linger",
+        ops: [
+            { op: "write", key: "a", subject: "deal:9", predicate: "status", value: "signed", bad: true },
+            { op: "read", subject: "deal:9", predicate: "status", expect: "signed" },
+            { op: "retract", key: "a" },
+            { op: "read", subject: "deal:9", predicate: "status", expect: null },
+        ],
+    },
+];
+export function formatReport(r) {
+    const row = (s) => `${s.name.padEnd(76)} reads ${String(s.reads).padStart(2)}  correct ${String(s.correctReads).padStart(2)}  stale ${String(s.staleReads).padStart(2)}  contradictions ${String(s.contradictions).padStart(2)}  blast ${String(s.blastRadius).padStart(2)}`;
+    const lines = r.scenarios.map((s) => row(s) + (s.failures.length ? `\n${s.failures.map((f) => `    ! ${f}`).join("\n")}` : ""));
+    lines.push(row({ name: "TOTAL", ...r.totals }));
+    return lines.join("\n");
+}

package/dist/index.d.ts

@@ -1,2 +1,9 @@
 export { Ledger } from "./ledger.ts";
-export type { AsOf, AssertEvent, AssertInput, Fact, LedgerEvent, RetractEvent, RetractInput, Source } from "./ledger.ts";
+export type { AsOf, AssertEvent, AssertInput, ConfirmEvent, ConfirmInput, Fact, FactProvenance, LedgerEvent, RetractEvent, RetractInput, Source } from "./ledger.ts";
+export { AGENT_META_KEY, RECEIPT_META_KEY, SERVER_VERSION, TOOLS, createMemoryServer, serveStdio } from "./server.ts";
+export type { MemoryServerOptions } from "./server.ts";
+export { SCENARIOS, formatReport, runAll, runScenario } from "./evals.ts";
+export type { MemoryUnderTest, Op, Report, Scenario, ScenarioScore } from "./evals.ts";
+export { ledgerUnderTest, overwriteStoreUnderTest } from "./evals-ledger.ts";
+export { factMetadata, factText, mem0Store, zepStore } from "./stores.ts";
+export type { Mem0Like, Mem0Options, Store, ZepLike, ZepOptions } from "./stores.ts";

package/dist/index.js

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

package/dist/ledger.d.ts

@@ -2,6 +2,12 @@
 export interface Source {
     receiptId: string | null;
 }
+/**
+ * How far the write can be trusted. attested: it came through the receipts gateway, so the actor is the agent named in
+ * a human-signed grant and the receipt exists. claimed: it came from somewhere that only says who it is. A claimed
+ * fact is quarantined: the memory server does not return it by default until an attested party confirms it.
+ */
+export type FactProvenance = "attested" | "claimed";
 export interface Fact {
     factId: string;
     subject: string;
@@ -12,6 +18,9 @@ export interface Fact {
     /** Who wrote it: a user id, an agent id, a tool name. */
     actor: string;
     source: Source;
+    provenance: FactProvenance;
+    /** ids of this fact in the retrieval stores it was written through to, by store name; absent when there are none */
+    external?: Record<string, string>;
     /** ISO timestamps. validTo is null while the fact is believed to still hold. */
     validFrom: string;
     validTo: string | null;
@@ -35,7 +44,16 @@ export interface RetractEvent {
     reason: string;
     source: Source;
 }
-export type LedgerEvent = AssertEvent | RetractEvent;
+/** A confirm lifts a claimed fact to attested. Only an attested party can confirm; the event records who and which receipt. */
+export interface ConfirmEvent {
+    eventId: string;
+    kind: "confirm";
+    txTime: string;
+    factId: string;
+    actor: string;
+    source: Source;
+}
+export type LedgerEvent = AssertEvent | RetractEvent | ConfirmEvent;
 export interface AssertInput {
     subject: string;
     predicate: string;
@@ -43,10 +61,18 @@ export interface AssertInput {
     space: string;
     actor: string;
     source?: Source;
+    /** default claimed; the memory server sets attested for writes that came through the gateway */
+    provenance?: FactProvenance;
+    external?: Record<string, string>;
     validFrom?: string;
     confidence?: number;
     supersedes?: string;
 }
+export interface ConfirmInput {
+    factId: string;
+    actor: string;
+    source?: Source;
+}
 export interface RetractInput {
     factId: string;
     actor: string;
@@ -61,6 +87,8 @@ export interface AsOf {
     space?: string;
     subject?: string;
     predicate?: string;
+    /** "attested" returns only facts that were attested at txAt; default "all" */
+    include?: "attested" | "all";
 }
 export declare class Ledger {
     private readonly events;
@@ -70,12 +98,16 @@ export declare class Ledger {
         now?: () => Date;
     });
     get size(): number;
+    /** The checks assert makes, without appending. For callers that must do something irreversible before the append. */
+    validateAssert(input: AssertInput): void;
     assert(input: AssertInput): AssertEvent;
     retract(input: RetractInput): RetractEvent;
+    confirm(input: ConfirmInput): ConfirmEvent;
     /** The facts believed at a moment. Valid time answers "was it true then"; transaction time answers "did the ledger know it then". */
     asOf(q?: AsOf): Fact[];
-    /** Every event that touched a fact, oldest first: its assert, the assert that superseded it, its retraction. */
+    /** Every event that touched a fact, oldest first: its assert, the assert that superseded it, its confirmation, its retraction. */
     history(factId: string): LedgerEvent[];
+    private confirmedAt;
     private factById;
     private retractedAt;
     private append;

package/dist/ledger.js

@@ -24,9 +24,9 @@ export class Ledger {
     get size() {
         return this.events.length;
     }
-    assert(input) {
-        const txTime = this.now().toISOString();
-        const validFrom = input.validFrom ?? txTime;
+    /** The checks assert makes, without appending. For callers that must do something irreversible before the append. */
+    validateAssert(input) {
+        const validFrom = input.validFrom ?? this.now().toISOString();
         if (input.supersedes !== undefined) {
             const prior = this.factById(input.supersedes);
             if (!prior)
@@ -38,6 +38,11 @@ export class Ledger {
             if (validFrom < prior.fact.validFrom)
                 throw new Error(`replacement cannot start before the fact it supersedes`);
         }
+    }
+    assert(input) {
+        this.validateAssert(input);
+        const txTime = this.now().toISOString();
+        const validFrom = input.validFrom ?? txTime;
         const event = {
             eventId: randomUUID(),
             kind: "assert",
@@ -50,6 +55,8 @@ export class Ledger {
                 space: input.space,
                 actor: input.actor,
                 source: input.source ?? { receiptId: null },
+                provenance: input.provenance ?? "claimed",
+                ...(input.external && Object.keys(input.external).length > 0 ? { external: input.external } : {}),
                 validFrom,
                 validTo: null,
                 confidence: input.confidence ?? null,
@@ -76,17 +83,30 @@ export class Ledger {
         this.append(event);
         return event;
     }
+    confirm(input) {
+        const prior = this.factById(input.factId);
+        if (!prior)
+            throw new Error(`cannot confirm unknown fact ${input.factId}`);
+        if (this.retractedAt(input.factId))
+            throw new Error(`fact ${input.factId} is retracted`);
+        if (prior.fact.provenance === "attested" || this.confirmedAt(input.factId))
+            throw new Error(`fact ${input.factId} is already attested`);
+        const event = { eventId: randomUUID(), kind: "confirm", txTime: this.now().toISOString(), factId: input.factId, actor: input.actor, source: input.source ?? { receiptId: null } };
+        this.append(event);
+        return event;
+    }
     /** The facts believed at a moment. Valid time answers "was it true then"; transaction time answers "did the ledger know it then". */
     asOf(q = {}) {
         const validAt = q.validAt ?? this.now().toISOString();
         const txAt = q.txAt ?? this.now().toISOString();
         const known = this.events.filter((e) => e.txTime <= txAt);
         const retracted = new Set(known.filter((e) => e.kind === "retract").map((e) => e.factId));
+        const confirmed = new Set(known.filter((e) => e.kind === "confirm").map((e) => e.factId));
         const facts = new Map();
         for (const e of known) {
             if (e.kind !== "assert")
                 continue;
-            facts.set(e.fact.factId, { ...e.fact });
+            facts.set(e.fact.factId, { ...e.fact, provenance: confirmed.has(e.fact.factId) ? "attested" : e.fact.provenance });
             if (e.supersedes && facts.has(e.supersedes) && !retracted.has(e.fact.factId)) {
                 facts.get(e.supersedes).validTo = e.fact.validFrom;
             }
@@ -96,12 +116,16 @@ export class Ledger {
             (f.validTo === null || validAt < f.validTo) &&
             (q.space === undefined || f.space === q.space) &&
             (q.subject === undefined || f.subject === q.subject) &&
-            (q.predicate === undefined || f.predicate === q.predicate));
+            (q.predicate === undefined || f.predicate === q.predicate) &&
+            (q.include !== "attested" || f.provenance === "attested"));
     }
-    /** Every event that touched a fact, oldest first: its assert, the assert that superseded it, its retraction. */
+    /** Every event that touched a fact, oldest first: its assert, the assert that superseded it, its confirmation, its retraction. */
     history(factId) {
         return this.events.filter((e) => (e.kind === "assert" ? e.fact.factId === factId || e.supersedes === factId : e.factId === factId));
     }
+    confirmedAt(factId) {
+        return this.events.some((e) => e.kind === "confirm" && e.factId === factId);
+    }
     factById(factId) {
         let found;
         for (const e of this.events) {

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Ledger } from "./ledger.ts";
+import type { Store } from "./stores.ts";
+export declare const SERVER_VERSION = "0.1.0";
+/** The same keys the receipts gateway sets on the upstream call. Duplicated here so this package needs no runtime import from receipts. */
+export declare const RECEIPT_META_KEY = "agent-custody/receipt";
+export declare const AGENT_META_KEY = "agent-custody/agent";
+export declare const TOOLS: Tool[];
+export interface MemoryServerOptions {
+    /** Refuse calls that did not come through the gateway, i.e. carry no receipt id. On by default when served from the CLI. */
+    requireGateway?: boolean;
+    /** Retrieval stores every write goes through to and every retraction reaches. A store that refuses a write fails the write; nothing is recorded. */
+    stores?: Store[];
+}
+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

@@ -0,0 +1,140 @@
+// The memory server: the ledger as MCP tools, meant to run as an upstream of the receipts gateway.
+// Behind the gateway every write and read is policy-checked and receipted, and the gateway tells this server, in the
+// call's _meta, which receipt it is and who the attested grant says is calling. Those become the fact's source and
+// actor; a caller cannot supply them. Run it directly and the source is null and the actor is whatever the caller
+// claims, which is recorded as such.
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+export const SERVER_VERSION = "0.1.0";
+/** The same keys the receipts gateway sets on the upstream call. Duplicated here so this package needs no runtime import from receipts. */
+export const RECEIPT_META_KEY = "agent-custody/receipt";
+export const AGENT_META_KEY = "agent-custody/agent";
+const iso = z.string().datetime({ offset: true });
+const Write = z.object({
+    subject: z.string().min(1),
+    predicate: z.string().min(1),
+    value: z.unknown(),
+    space: z.string().min(1),
+    /** ignored behind the gateway, which supplies the attested agent instead */
+    actor: z.string().min(1).optional(),
+    validFrom: iso.optional(),
+    confidence: z.number().min(0).max(1).optional(),
+    supersedes: z.string().min(1).optional(),
+});
+const Read = z.object({ subject: z.string().min(1).optional(), predicate: z.string().min(1).optional(), space: z.string().min(1).optional(), validAt: iso.optional(), txAt: iso.optional(), includeClaimed: z.boolean().optional() });
+const 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 str = { type: "string" };
+export const TOOLS = [
+    {
+        name: "memory.write",
+        description: "Record a belief: subject, predicate, value, in a space. Optionally supersede an earlier fact. Returns the new fact with its id, transaction time, actor, and source receipt.",
+        inputSchema: { type: "object", properties: { subject: str, predicate: str, value: {}, space: str, actor: str, validFrom: str, confidence: { type: "number" }, supersedes: str }, required: ["subject", "predicate", "value", "space"] },
+    },
+    {
+        name: "memory.read",
+        description: "The facts believed at a moment. validAt asks whether a fact was true then; txAt asks whether the ledger knew it then. Both default to now. Filter by space, subject, predicate. Quarantined (claimed, unconfirmed) facts are left out unless includeClaimed is true.",
+        inputSchema: { type: "object", properties: { subject: str, predicate: str, space: str, validAt: str, txAt: str, includeClaimed: { type: "boolean" } } },
+    },
+    {
+        name: "memory.confirm",
+        description: "Lift a quarantined (claimed) fact to attested. Only accepted through the gateway, so the confirming actor is the one named in the signed grant.",
+        inputSchema: { type: "object", properties: { factId: str }, required: ["factId"] },
+    },
+    {
+        name: "memory.retract",
+        description: "Undo a belief: the fact leaves the present, stays visible to questions about the past, and whatever it superseded is believed again.",
+        inputSchema: { type: "object", properties: { factId: str, reason: str, actor: str }, required: ["factId", "reason"] },
+    },
+    {
+        name: "memory.history",
+        description: "Every event that touched a fact, oldest first.",
+        inputSchema: { type: "object", properties: { factId: str }, required: ["factId"] },
+    },
+];
+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 = {}) {
+    const server = new Server({ name: "agent-custody-memory", version: SERVER_VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const meta = (req.params._meta ?? {});
+        const receiptId = typeof meta[RECEIPT_META_KEY] === "string" ? meta[RECEIPT_META_KEY] : null;
+        const gatewayAgent = typeof meta[AGENT_META_KEY] === "string" ? meta[AGENT_META_KEY] : null;
+        if (opts.requireGateway && !receiptId)
+            return fail("memory server accepts calls only through the receipts gateway; no receipt id on this call");
+        const args = req.params.arguments ?? {};
+        const actorFor = (claimed) => gatewayAgent ?? claimed ?? "anonymous";
+        // A write is attested when it came through the gateway: the actor is from a signed grant and the receipt exists.
+        const provenance = receiptId && gatewayAgent ? "attested" : "claimed";
+        try {
+            switch (req.params.name) {
+                case "memory.write": {
+                    const a = Write.parse(args);
+                    const input = { subject: a.subject, predicate: a.predicate, value: a.value ?? null, space: a.space, actor: actorFor(a.actor), source: { receiptId }, provenance, ...(a.validFrom ? { validFrom: a.validFrom } : {}), ...(a.confidence !== undefined ? { confidence: a.confidence } : {}), ...(a.supersedes ? { supersedes: a.supersedes } : {}) };
+                    // The stores are written first, so their ids can be recorded on the fact; the ledger's checks run beforehand
+                    // so a write the ledger would refuse never reaches a store.
+                    ledger.validateAssert(input);
+                    const external = {};
+                    const preview = { ...input, factId: "pending", validFrom: input.validFrom ?? new Date().toISOString(), validTo: null, confidence: input.confidence ?? null };
+                    for (const store of opts.stores ?? [])
+                        external[store.name] = await store.put(preview);
+                    const ev = ledger.assert({ ...input, external });
+                    return json({ fact: ev.fact, eventId: ev.eventId, txTime: ev.txTime, supersedes: ev.supersedes });
+                }
+                case "memory.read": {
+                    const { includeClaimed, ...q } = Read.parse(args);
+                    return json({ facts: ledger.asOf({ ...q, include: includeClaimed ? "all" : "attested" }) });
+                }
+                case "memory.retract": {
+                    const a = Retract.parse(args);
+                    const fact = ledger.history(a.factId).find((e) => e.kind === "assert" && e.fact.factId === a.factId)?.fact;
+                    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))) };
+                    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);
+                }
+                case "memory.confirm": {
+                    if (provenance !== "attested")
+                        return fail("confirmation must come through the receipts gateway; a self-reported caller cannot lift a fact out of quarantine");
+                    const a = Confirm.parse(args);
+                    const ev = ledger.confirm({ factId: a.factId, actor: actorFor(undefined), source: { receiptId } });
+                    return json({ eventId: ev.eventId, factId: ev.factId, txTime: ev.txTime, actor: ev.actor, source: ev.source });
+                }
+                case "memory.history":
+                    return json({ events: ledger.history(History.parse(args).factId) });
+                default:
+                    return fail(`unknown tool ${req.params.name}`);
+            }
+        }
+        catch (e) {
+            return fail(e instanceof z.ZodError ? `invalid arguments: ${e.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}` : String(e instanceof Error ? e.message : e));
+        }
+    });
+    return server;
+}
+/** Serves over stdio, the way the gateway spawns it. Diagnostics must go to stderr. */
+export async function serveStdio(server) {
+    await server.connect(new StdioServerTransport());
+    await new Promise((resolve) => {
+        server.onclose = resolve;
+    });
+}

package/dist/stores.d.ts

@@ -0,0 +1,55 @@
+import type { Fact } from "./ledger.ts";
+export interface Store {
+    /** the key under which the store's id is recorded on the fact */
+    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 */
+    remove(externalId: string, fact: Fact): Promise<void>;
+}
+/** 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. */
+export declare function factMetadata(f: Fact): Record<string, unknown>;
+/** The subset of mem0ai's MemoryClient this adapter uses. */
+export interface Mem0Like {
+    add(messages: {
+        role: "user" | "assistant";
+        content: string;
+    }[], options?: Record<string, unknown>): Promise<{
+        id?: string;
+    }[]>;
+    delete(memoryId: string): Promise<unknown>;
+}
+export interface Mem0Options {
+    userId: string;
+    /** Mem0 extracts memories with an LLM when infer is true. Off by default, so the memory is the fact, verbatim. */
+    infer?: boolean;
+}
+export declare function mem0Store(client: Mem0Like, opts: Mem0Options): Store;
+/** The subset of @getzep/zep-cloud's ZepClient this adapter uses. */
+export interface ZepLike {
+    graph: {
+        add(request: {
+            userId?: string;
+            graphId?: string;
+            type: "json" | "text";
+            data: string;
+            sourceDescription?: string;
+            metadata?: Record<string, unknown>;
+        }): Promise<{
+            uuid: string;
+        }>;
+        episode: {
+            delete(uuid: string): Promise<unknown>;
+        };
+    };
+}
+export type ZepOptions = {
+    userId: string;
+    graphId?: undefined;
+} | {
+    graphId: string;
+    userId?: undefined;
+};
+export declare function zepStore(client: ZepLike, opts: ZepOptions): Store;

package/dist/stores.js

@@ -0,0 +1,38 @@
+/** One line a retrieval store can index: what the fact says, in words. */
+export function factText(f) {
+    return `${f.subject} ${f.predicate}: ${typeof f.value === "string" ? f.value : JSON.stringify(f.value)}`;
+}
+/** Metadata every store receives alongside the text, so a memory can always be traced back to its custody. */
+export function factMetadata(f) {
+    return { factId: f.factId, space: f.space, actor: f.actor, provenance: f.provenance, receiptId: f.source.receiptId, validFrom: f.validFrom, source: "agent-custody" };
+}
+export function mem0Store(client, opts) {
+    return {
+        name: "mem0",
+        async put(fact) {
+            const results = await client.add([{ role: "user", content: factText(fact) }], { user_id: opts.userId, infer: opts.infer ?? false, metadata: factMetadata(fact) });
+            const id = results.find((r) => typeof r.id === "string")?.id;
+            if (!id)
+                throw new Error("mem0 returned no memory id");
+            return id;
+        },
+        async remove(externalId) {
+            await client.delete(externalId);
+        },
+    };
+}
+export function zepStore(client, opts) {
+    return {
+        name: "zep",
+        async put(fact) {
+            const target = opts.graphId ? { graphId: opts.graphId } : { userId: opts.userId };
+            const episode = await client.graph.add({ ...target, type: "json", data: JSON.stringify({ subject: fact.subject, predicate: fact.predicate, value: fact.value, ...factMetadata(fact) }), sourceDescription: "agent-custody", metadata: factMetadata(fact) });
+            if (!episode?.uuid)
+                throw new Error("zep returned no episode uuid");
+            return episode.uuid;
+        },
+        async remove(externalId) {
+            await client.graph.episode.delete(externalId);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/state",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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": {
@@ -12,6 +12,9 @@
     "access": "public"
   },
   "type": "module",
+  "bin": {
+    "agent-custody-memory": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -23,18 +26,22 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p ../receipts/tsconfig.build.json && tsc --noEmit",
     "test": "tsc -p ../receipts/tsconfig.build.json && vitest run"
   },
   "engines": {
     "node": ">=22"
   },
   "dependencies": {
-    "@agent-custody/receipts": "0.1.2"
+    "@agent-custody/receipts": "0.1.4",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",
     "typescript": "^7.0.2",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.0",
+    "mem0ai": "^3.1.8",
+    "@getzep/zep-cloud": "^3.28.0"
   }
 }