@agent-custody/state 0.5.9 → 0.6.1

package/README.md

@@ -146,17 +146,22 @@ The first eight lines come from the receipt alone and work without a ledger; the
 
 ## 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. For teams whose recall is a pgvector table, `pgvectorStore` writes the fact's text, its embedding from the function you already use, and its custody metadata as one row keyed by the fact id, and verifies a removal with the same nearest-neighbour query a retrieval call runs.
+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. For teams whose recall is a pgvector table, `pgvectorStore` writes the fact's text, its embedding from the function you already use, and its custody metadata as one row keyed by the fact id, and verifies a removal with the same nearest-neighbour query a retrieval call runs. Three more, each with its own limitation stated: `lettaStore` writes a passage to an agent's archival memory with the custody as tags, since Letta passages carry no free metadata, and verifies removal through archival search; `langgraphStore` writes one item per fact into a LangGraph store, which is where LangMem keeps its memories, keyed by the fact id under the namespace you give, and verifies removal with `get` and a filtered `search`; `cogneeStore` speaks Cognee's REST API directly, because Cognee has no JavaScript client, adding the text with the custody as external metadata and finding the data id by listing the dataset, since Cognee's add returns a pipeline run rather than an id; it was built against Cognee's routers and tested against a stand-in of them, not a running Cognee.
 
 ```ts
 import { MemoryClient } from "mem0ai";
 import { ZepClient } from "@getzep/zep-cloud";
-import { Ledger, createMemoryServer, mem0Store, zepStore } from "@agent-custody/state";
+import { Letta } from "@letta-ai/letta-client";
+import { InMemoryStore } from "@langchain/langgraph";
+import { Ledger, cogneeStore, createMemoryServer, langgraphStore, lettaStore, mem0Store, pgvectorStore, 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
   pgvectorStore(pool, { embed, dimensions: 1536, table: "agent_memories" }),                    // your Postgres, your embedding function
+  lettaStore(new Letta({ apiKey: process.env.LETTA_API_KEY! }), { agentId: "agent-…" }),            // archival memory of one agent, custody as tags
+  langgraphStore(new InMemoryStore(), { namespace: ["memories", "user_42"] }),                    // or any BaseStore: LangMem's memories live here
+  cogneeStore({ url: "http://localhost:8000", datasetId: "…", apiKeyEnv: "COGNEE_API_KEY" }),    // Cognee's REST API, no client package exists
 ];
 createMemoryServer(new Ledger("./ledger.jsonl"), { stores });
 ```
@@ -220,7 +225,7 @@ src/review.ts   the review page: the explain output as pages, served on loopback
 src/pack.ts     the custody pack: build, sign, verify, format
 src/cli.ts      agent-custody-memory serve (stdio or --http, with --retention and --forget-key-env), sweep (ledger-only or --via a gateway), eval, explain, review, pack, export, blast
 src/blast.ts    blast radius: from receipts' consumed facts and the ledger's source receipts, forward
-src/stores.ts   write-through adapters: Mem0, Zep, and pgvector, and the Store interface for others
+src/stores.ts   write-through adapters: Mem0, Zep, pgvector, Letta, a LangGraph store (LangMem), and Cognee, 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
@@ -250,6 +255,7 @@ 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 to pgvector: the fact's text, embedding, and custody metadata as one row in the Postgres a team already runs, keyed by the fact id; removal verified by the same nearest-neighbour query recall runs; tested against Postgres with the extension in Docker.
+- Write-through adapters for Letta (archival passages, custody as tags), a LangGraph store where LangMem keeps its memories (one item per fact under a namespace), and Cognee (its REST API, the data id found by listing the dataset); each verifies its own removals, each states its limitation.
 - 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.

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export type { MemoryUnderTest, Op, Report, Scenario, ScenarioScore } from "./eva
 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, pgvectorStore, zepStore } from "./stores.ts";
+export { cogneeStore, factMetadata, factText, langgraphStore, lettaStore, mem0Store, pgvectorStore, zepStore } from "./stores.ts";
 export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.ts";
 export { memoryHttpHandler, serveMemoryHttp } from "./http.ts";
 export { PACK_TYPE, buildPack, formatPack, signPack, verifyPack } from "./pack.ts";
@@ -20,4 +20,4 @@ export type { ActionPack, ActionPackCheck, ActionPackVerification, ReceiptKeys }
 export type { CustodyPack, PackCheck, PackVerification } from "./pack.ts";
 export type { MemoryHttpOptions, RunningMemoryServer } from "./http.ts";
 export type { BlastRadius, ReceiptSummary } from "./blast.ts";
-export type { Mem0Like, Mem0Options, PgLike, PgvectorOptions, RemovalOutcome, Store, ZepLike, ZepOptions } from "./stores.ts";
+export type { CogneeOptions, LangGraphStoreLike, LangGraphStoreOptions, LettaLike, LettaOptions, Mem0Like, Mem0Options, PgLike, PgvectorOptions, RemovalOutcome, Store, ZepLike, ZepOptions } from "./stores.ts";

package/dist/index.js

@@ -5,7 +5,7 @@ export { AGENT_META_KEY, FACTS_META_KEY, OBSERVED_META_KEY, RECEIPT_META_KEY, SE
 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, pgvectorStore, zepStore } from "./stores.js";
+export { cogneeStore, factMetadata, factText, langgraphStore, lettaStore, mem0Store, pgvectorStore, zepStore } from "./stores.js";
 export { blastRadius, formatBlastRadius, loadReceipts } from "./blast.js";
 export { memoryHttpHandler, serveMemoryHttp } from "./http.js";
 export { PACK_TYPE, buildPack, formatPack, signPack, verifyPack } from "./pack.js";

package/dist/stores.d.ts

@@ -104,3 +104,86 @@ export interface PgvectorOptions {
  * and checks the removed id is not among the nearest rows, which is what a retrieval query would return.
  */
 export declare function pgvectorStore(client: PgLike, opts: PgvectorOptions): Store;
+/** The subset of @letta-ai/letta-client's Letta this adapter uses: an agent's archival memory. */
+export interface LettaLike {
+    agents: {
+        passages: {
+            create(agentId: string, body: {
+                text: string;
+                tags?: string[] | null;
+            }): Promise<{
+                id?: string | undefined;
+            }[]>;
+            delete(memoryId: string, params: {
+                agent_id: string;
+            }): Promise<unknown>;
+            search?(agentId: string, query: {
+                query: string;
+                tags?: string[] | null;
+                tag_match_mode?: "any" | "all";
+            }): Promise<{
+                results: {
+                    id: string;
+                    content: string;
+                }[];
+            }>;
+        };
+    };
+}
+export interface LettaOptions {
+    /** the agent whose archival memory receives the fact */
+    agentId: string;
+    /** tags attached to every passage, beside the custody tags; default none */
+    tags?: string[];
+}
+/**
+ * Letta keeps archival memory as passages with text and tags, no free metadata. Custody travels as tags
+ * (`agent-custody`, `fact:<id>`, `space:<name>`, `receipt:<id>`) so a passage always leads back to its fact.
+ */
+export declare function lettaStore(client: LettaLike, opts: LettaOptions): Store;
+/**
+ * The subset of LangGraph's BaseStore this adapter uses. LangMem's memories live in this store, so custody over a
+ * LangMem deployment is custody over its store: one item per fact, keyed by the fact id, in the namespace given.
+ */
+export interface LangGraphStoreLike {
+    put(namespace: string[], key: string, value: Record<string, unknown>): Promise<void>;
+    get(namespace: string[], key: string): Promise<{
+        key: string;
+        value: Record<string, unknown>;
+    } | null>;
+    delete(namespace: string[], key: string): Promise<void>;
+    search?(namespacePrefix: string[], options?: {
+        filter?: Record<string, unknown>;
+        limit?: number;
+        query?: string;
+    }): Promise<{
+        key: string;
+        namespace: string[];
+        value: Record<string, unknown>;
+    }[]>;
+}
+export interface LangGraphStoreOptions {
+    /** the namespace the memories live under, e.g. ["memories", userId] */
+    namespace: string[];
+}
+export declare function langgraphStore(store: LangGraphStoreLike, opts: LangGraphStoreOptions): Store;
+export interface CogneeOptions {
+    /** the Cognee server, e.g. http://localhost:8000 */
+    url: string;
+    /** the dataset the facts go into, by id */
+    datasetId: string;
+    /** environment variable holding an API key (sent as X-Api-Key) */
+    apiKeyEnv?: string;
+    /** environment variable holding a bearer token (sent as Authorization: Bearer) */
+    tokenEnv?: string;
+    fetch?: typeof fetch;
+    env?: Record<string, string | undefined>;
+}
+/**
+ * Cognee has no JavaScript client; this adapter speaks its REST API directly, built against the add and datasets
+ * routers of cognee 0.3: `POST /api/v1/add` (multipart, `raw_data` and `external_metadata`), `GET
+ * /api/v1/datasets/{id}/data`, `DELETE /api/v1/datasets/{id}/data/{dataId}`. The add call returns a pipeline run,
+ * not the data id, so the id is found by listing the dataset and matching the fact id written into the item's
+ * external metadata. Tested against a stand-in of those three routes, not against a running Cognee.
+ */
+export declare function cogneeStore(opts: CogneeOptions): Store;

package/dist/stores.js

@@ -96,3 +96,117 @@ export function pgvectorStore(client, opts) {
         },
     };
 }
+/**
+ * Letta keeps archival memory as passages with text and tags, no free metadata. Custody travels as tags
+ * (`agent-custody`, `fact:<id>`, `space:<name>`, `receipt:<id>`) so a passage always leads back to its fact.
+ */
+export function lettaStore(client, opts) {
+    const tagsFor = (f) => ["agent-custody", `fact:${f.factId}`, `space:${f.space}`, ...(f.source.receiptId ? [`receipt:${f.source.receiptId}`] : []), ...(opts.tags ?? [])];
+    return {
+        name: "letta",
+        async put(fact) {
+            const passages = await client.agents.passages.create(opts.agentId, { text: factText(fact), tags: tagsFor(fact) });
+            const id = passages.find((p) => typeof p.id === "string")?.id;
+            if (!id)
+                throw new Error("letta returned no passage id");
+            return id;
+        },
+        async remove(externalId) {
+            await client.agents.passages.delete(externalId, { agent_id: opts.agentId });
+        },
+        ...(client.agents.passages.search
+            ? {
+                async verifyRemoved(externalId, fact) {
+                    const { results } = await client.agents.passages.search(opts.agentId, { query: factText(fact), tags: [`fact:${fact.factId}`], tag_match_mode: "any" });
+                    return !results.some((r) => r.id === externalId || r.content === factText(fact));
+                },
+            }
+            : {}),
+    };
+}
+export function langgraphStore(store, opts) {
+    return {
+        name: "langgraph",
+        async put(fact) {
+            await store.put(opts.namespace, fact.factId, { content: factText(fact), subject: fact.subject, predicate: fact.predicate, value: fact.value, ...factMetadata(fact) });
+            return fact.factId;
+        },
+        async remove(externalId) {
+            await store.delete(opts.namespace, externalId);
+        },
+        async verifyRemoved(externalId, fact) {
+            if ((await store.get(opts.namespace, externalId)) !== null)
+                return false;
+            if (!store.search)
+                return true;
+            const hits = await store.search(opts.namespace, { filter: { factId: fact.factId }, limit: 10 });
+            return !hits.some((h) => h.key === externalId);
+        },
+    };
+}
+/**
+ * Cognee has no JavaScript client; this adapter speaks its REST API directly, built against the add and datasets
+ * routers of cognee 0.3: `POST /api/v1/add` (multipart, `raw_data` and `external_metadata`), `GET
+ * /api/v1/datasets/{id}/data`, `DELETE /api/v1/datasets/{id}/data/{dataId}`. The add call returns a pipeline run,
+ * not the data id, so the id is found by listing the dataset and matching the fact id written into the item's
+ * external metadata. Tested against a stand-in of those three routes, not against a running Cognee.
+ */
+export function cogneeStore(opts) {
+    const f = opts.fetch ?? fetch;
+    const env = opts.env ?? process.env;
+    const headers = {};
+    if (opts.apiKeyEnv) {
+        const v = env[opts.apiKeyEnv];
+        if (!v)
+            throw new Error(`cognee: environment variable ${opts.apiKeyEnv} is not set`);
+        headers["x-api-key"] = v;
+    }
+    if (opts.tokenEnv) {
+        const v = env[opts.tokenEnv];
+        if (!v)
+            throw new Error(`cognee: environment variable ${opts.tokenEnv} is not set`);
+        headers.authorization = `Bearer ${v}`;
+    }
+    const base = opts.url.endsWith("/") ? opts.url : `${opts.url}/`;
+    const call = async (method, path, body) => {
+        const res = await f(new URL(path, base), { method, headers, ...(body ? { body } : {}), signal: AbortSignal.timeout(30_000) });
+        if (!res.ok)
+            throw new Error(`cognee ${method} ${path}: ${res.status} ${(await res.text()).slice(0, 200)}`);
+        const text = await res.text();
+        return text ? JSON.parse(text) : null;
+    };
+    const list = async () => (await call("GET", `api/v1/datasets/${opts.datasetId}/data`));
+    const metadataOf = (item) => {
+        const m = item.external_metadata;
+        if (typeof m === "string") {
+            try {
+                return JSON.parse(m);
+            }
+            catch {
+                return {};
+            }
+        }
+        return (m ?? {});
+    };
+    return {
+        name: "cognee",
+        async put(fact) {
+            const form = new FormData();
+            form.append("raw_data", factText(fact));
+            form.append("datasetId", opts.datasetId);
+            form.append("external_metadata", JSON.stringify([factMetadata(fact)]));
+            form.append("labels", JSON.stringify(["agent-custody", `fact:${fact.factId}`]));
+            await call("POST", "api/v1/add", form);
+            const item = (await list()).reverse().find((i) => metadataOf(i).factId === fact.factId);
+            if (!item)
+                throw new Error(`cognee accepted the add but the dataset lists no item carrying fact ${fact.factId}`);
+            return item.id;
+        },
+        async remove(externalId) {
+            await call("DELETE", `api/v1/datasets/${opts.datasetId}/data/${externalId}`);
+        },
+        async verifyRemoved(externalId, fact) {
+            return !(await list()).some((i) => i.id === externalId || metadataOf(i).factId === fact.factId);
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/state",
-  "version": "0.5.9",
+  "version": "0.6.1",
   "description": "Governed memory for AI agents: a fact ledger with provenance, valid time, rollback, lineage, certified forget, and a store that is a JSONL file, SQLite, or Postgres, built on @agent-custody/receipts",
   "license": "Apache-2.0",
   "repository": {
@@ -33,7 +33,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@agent-custody/receipts": "0.5.9",
+    "@agent-custody/receipts": "0.6.1",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.5.4"
   },