@agent-custody/state 0.1.1 → 0.1.3

package/README.md

@@ -22,7 +22,32 @@ 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.
+Three runnable examples, all executed by the test suite. [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.retract` | undoes a belief, keeping it visible to questions about the past | `factId`, `reason` |
+| `memory.history` | every event that touched a fact | `factId` |
+
+Trust tiers are Cedar policies over the space: `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.
 
 ## The ledger
 
@@ -46,6 +71,8 @@ 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/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 +84,12 @@ 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.
 
 **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.
+3. 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.
+4. Write-through adapters for existing memory stores, tested against the real packages.
+5. Signed forget statements: a retention or deletion request produces a verifiable record of which facts were removed.

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/index.d.ts

@@ -1,2 +1,4 @@
 export { Ledger } from "./ledger.ts";
 export type { AsOf, AssertEvent, AssertInput, Fact, 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";

package/dist/index.js

@@ -1,2 +1,3 @@
 // 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";

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { Ledger } from "./ledger.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;
+}
+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,99 @@
+// 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() });
+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.",
+        inputSchema: { type: "object", properties: { subject: str, predicate: str, space: str, validAt: str, txAt: str } },
+    },
+    {
+        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";
+        try {
+            switch (req.params.name) {
+                case "memory.write": {
+                    const a = Write.parse(args);
+                    const ev = ledger.assert({ subject: a.subject, predicate: a.predicate, value: a.value ?? null, space: a.space, actor: actorFor(a.actor), source: { receiptId }, ...(a.validFrom ? { validFrom: a.validFrom } : {}), ...(a.confidence !== undefined ? { confidence: a.confidence } : {}), ...(a.supersedes ? { supersedes: a.supersedes } : {}) });
+                    return json({ fact: ev.fact, eventId: ev.eventId, txTime: ev.txTime, supersedes: ev.supersedes });
+                }
+                case "memory.read": {
+                    const q = Read.parse(args);
+                    return json({ facts: ledger.asOf(q) });
+                }
+                case "memory.retract": {
+                    const a = Retract.parse(args);
+                    const ev = ledger.retract({ factId: a.factId, actor: actorFor(a.actor), reason: a.reason, source: { receiptId } });
+                    return json({ eventId: ev.eventId, factId: ev.factId, txTime: ev.txTime, actor: ev.actor, reason: ev.reason, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/state",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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,14 +26,16 @@
   ],
   "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.1"
+    "@agent-custody/receipts": "0.1.3",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",