Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

feat(export): paginate the non-session collections the frame guard's hint calls out (#1143)

Dmitrii Zhukov4b95a629a575
diff --git a/README.md b/README.md
index 526fb608..6bfbb400 100644
--- a/README.md
+++ b/README.md
@@ -1122,7 +1122,7 @@ Three tool surfaces, smallest to largest: `AGENTMEMORY_TOOLS=core` trims visibil
| `memory_vision_search` | Search image observations |
| `memory_timeline` | Chronological observations |
| `memory_profile` | Project profile (concepts, files, patterns) |
-| `memory_export` | Export all memory data |
+| `memory_export` | Export memory data, in pages or selected collections on a large store |
| `memory_relations` | Query relationship graph |
| `memory_commit_lookup` | Sessions behind a git commit |
| `memory_commits` | Commits recorded for a session |
@@ -1422,7 +1422,7 @@ else
fi
```
-`/agentmemory/export` also accepts `?maxSessions=` and `?offset=` for chunking a large corpus across several calls; `strategy` on import is `merge` (default-safe), `replace`, or `skip`.
+`/agentmemory/export` also accepts `?maxSessions=` and `?offset=` for chunking a large corpus across several calls, `?collectionLimit=` and `?collectionOffset=` to page memories, the graph and the other collections, and `?collections=` to return only the named ones; `strategy` on import is `merge` (default-safe), `replace`, or `skip`, and `replace` refuses a paged or selected export.
### What iii replaces
diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md
index b15dce08..68fe3deb 100644
--- a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md
+++ b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md
@@ -18,7 +18,7 @@ agentmemory exposes 54 MCP tools. 8 are in the lean core set (`--tools core` or
| `memory_consolidate` | yes | `tier`: string | Run the 4-tier memory consolidation pipeline (working -> episodic -> semantic -> procedural). |
| `memory_crystallize` | | `actionIds`*: string, `project`: string, `sessionId`: string | Compress completed action chains into compact crystal digests using LLM summarization. Extracts narrative, key outcomes, files affected, and lessons. |
| `memory_diagnose` | yes | `categories`: string | Run health checks across all subsystems (actions, leases, sentinels, sketches, signals, sessions, memories, mesh). Identifies stuck, orphaned, and inconsistent state. |
-| `memory_export` | | none | Export all memory data as JSON. |
+| `memory_export` | | `maxSessions`: number, `offset`: number, `collectionLimit`: number, `collectionOffset`: number, `collections`: string | Export memory data as JSON. Past the transport size limit the export is refused, so use the paging arguments on a large store. |
| `memory_facet_query` | | `matchAll`: string, `matchAny`: string, `targetType`: string | Query targets by facet tags with AND/OR logic. Find all actions tagged priority:urgent AND team:backend. |
| `memory_facet_tag` | | `targetId`*: string, `targetType`*: string, `dimension`*: string, `value`*: string | Attach a structured tag (dimension:value) to an action, memory, or observation for multi-dimensional categorization. |
| `memory_file_history` | | `files`*: string, `sessionId`: string | Get past observations about specific files. |
diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts
index 86bad3c4..1987180e 100644
--- a/src/functions/export-import.ts
+++ b/src/functions/export-import.ts
@@ -70,7 +70,7 @@ async function runChunked<T>(
}
const EXPORT_OVERSIZE_HINT =
- "narrow the range with ?maxSessions / ?offset, or export fewer collections; the non-session collections (memories, graph, semantic, actions, lessons, ...) are not yet paginated";
+ "narrow the range with ?maxSessions / ?offset, page the rest with ?collectionLimit / ?collectionOffset, or ask for a subset with ?collections=";
const EXPORT_COLLECTIONS: ReadonlyArray<readonly [keyof ExportData, string]> = [
["graphNodes", KV.graphNodes],
@@ -91,6 +91,23 @@ const EXPORT_COLLECTIONS: ReadonlyArray<readonly [keyof ExportData, string]> = [
["accessLogs", KV.accessLog],
];
+const EXPORT_COLLECTION_NAMES: ReadonlySet<string> = new Set([
+ "sessions",
+ "memories",
+ "summaries",
+ ...EXPORT_COLLECTIONS.map(([field]) => field),
+]);
+
+function parseCollections(raw: unknown): ReadonlySet<string> | undefined {
+ if (raw === undefined || raw === null) return undefined;
+ const names = Array.isArray(raw) ? raw : String(raw).split(",");
+ return new Set(
+ names
+ .map((name) => String(name).trim())
+ .filter((name) => EXPORT_COLLECTION_NAMES.has(name)),
+ );
+}
+
export class ExportBudget {
bytes = 0;
@@ -108,12 +125,40 @@ export class ExportBudget {
export function registerExportImportFunction(sdk: IIIClient, state: StateKV): void {
sdk.registerFunction("mem::export",
- async (data?: { maxSessions?: number; offset?: number }) => {
+ async (data?: {
+ maxSessions?: number;
+ offset?: number;
+ collectionLimit?: number;
+ collectionOffset?: number;
+ collections?: string[] | string;
+ }) => {
const kv = await pinGraphState(state);
const rawMax = Number(data?.maxSessions);
const maxSessions = Number.isFinite(rawMax) && rawMax > 0 ? Math.min(Math.floor(rawMax), 1000) : undefined;
const rawOffset = Number(data?.offset);
const offset = Number.isFinite(rawOffset) && rawOffset >= 0 ? Math.floor(rawOffset) : 0;
+ const rawCollectionLimit = Number(data?.collectionLimit);
+ const collectionLimit =
+ Number.isFinite(rawCollectionLimit) && rawCollectionLimit > 0
+ ? Math.floor(rawCollectionLimit)
+ : undefined;
+ const rawCollectionOffset = Number(data?.collectionOffset);
+ const collectionOffset =
+ Number.isFinite(rawCollectionOffset) && rawCollectionOffset >= 0
+ ? Math.floor(rawCollectionOffset)
+ : 0;
+
+ const selection = parseCollections(data?.collections);
+ const isSelected = (name: string): boolean =>
+ selection === undefined || selection.has(name);
+
+ const collectionTotals: Record<string, number> = {};
+ const sliceCollection = <T>(name: string, rows: T[]): T[] => {
+ collectionTotals[name] = rows.length;
+ if (!isSelected(name)) return [];
+ if (collectionLimit === undefined) return rows;
+ return rows.slice(collectionOffset, collectionOffset + collectionLimit);
+ };
const budget = new ExportBudget();
const refuse = (collection: string) => {
@@ -130,15 +175,19 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
kv.list<T>(scope).catch(() => [] as T[]);
const allSessions = await kv.list<Session>(KV.sessions);
- const paginatedSessions = maxSessions !== undefined
+ const sessionWindow = maxSessions !== undefined
? allSessions.slice(offset, offset + maxSessions)
: allSessions;
+ const paginatedSessions = isSelected("sessions") ? sessionWindow : [];
if (!budget.fits(paginatedSessions)) return refuse("sessions");
- const memories = await kv.list<Memory>(KV.memories);
+ const memories = sliceCollection("memories", await kv.list<Memory>(KV.memories));
if (!budget.fits(memories)) return refuse("memories");
- const summaries = await kv.list<SessionSummary>(KV.summaries);
+ const summaries = sliceCollection(
+ "summaries",
+ await kv.list<SessionSummary>(KV.summaries),
+ );
if (!budget.fits(summaries)) return refuse("summaries");
const observations: Record<string, CompressedObservation[]> = {};
@@ -163,9 +212,20 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
}
if (!budget.fits(profiles)) return refuse("profiles");
+ const partial = collectionLimit !== undefined || selection !== undefined;
+ const exportedMemoryIds = new Set(memories.map((m) => m.id));
+ const accessLogsFor = (rows: AccessLogExport[]): AccessLogExport[] => {
+ collectionTotals["accessLogs"] = rows.length;
+ if (!isSelected("accessLogs")) return [];
+ return rows.filter((row) => exportedMemoryIds.has(row.memoryId));
+ };
const collections: Partial<ExportData> = {};
for (const [field, scope] of EXPORT_COLLECTIONS) {
- const items = await optional<unknown>(scope);
+ const rows = await optional<unknown>(scope);
+ const items =
+ field === "accessLogs" && partial
+ ? accessLogsFor(rows as AccessLogExport[])
+ : sliceCollection(field, rows);
if (items.length === 0) continue;
if (!budget.fits(items, field)) return refuse(field);
(collections as Record<string, unknown>)[field] = items;
@@ -191,6 +251,23 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
};
}
+ if (partial) {
+ exportData.collectionPagination = {
+ offset: collectionOffset,
+ ...(collectionLimit !== undefined ? { limit: collectionLimit } : {}),
+ ...(selection !== undefined ? { collections: [...selection] } : {}),
+ totals: collectionTotals,
+ hasMore:
+ collectionLimit !== undefined &&
+ Object.entries(collectionTotals).some(
+ ([name, total]) =>
+ name !== "accessLogs" &&
+ isSelected(name) &&
+ collectionOffset + collectionLimit < total,
+ ),
+ };
+ }
+
const oversized = checkPayloadFrameSize(exportData, EXPORT_OVERSIZE_HINT);
if (oversized) {
logger.warn("Export exceeds transport frame limit", {
@@ -209,6 +286,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
observations: totalObs,
memories: memories.length,
summaries: summaries.length,
+ collections: selection && [...selection],
});
return exportData;
@@ -238,6 +316,17 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
error: `Unsupported export version: ${importData.version}`,
};
}
+ const sessionPage = importData.pagination;
+ const partialSessions =
+ sessionPage !== undefined &&
+ ((sessionPage.offset ?? 0) > 0 || sessionPage.hasMore === true);
+ if (strategy === "replace" && (importData.collectionPagination || partialSessions)) {
+ return {
+ success: false,
+ error:
+ "replace needs a complete export; this one is a page or a selection of collections",
+ };
+ }
const MAX_SESSIONS = 10_000;
const MAX_MEMORIES = 50_000;
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 52a1d83f..fa526182 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -383,7 +383,25 @@ export function registerMcpEndpoints(
}
case "memory_export": {
- const result = await sdk.trigger({ function_id: "mem::export", payload: {} });
+ const exportPayload: {
+ maxSessions?: number;
+ offset?: number;
+ collectionLimit?: number;
+ collectionOffset?: number;
+ collections?: string;
+ } = {};
+ for (const key of ["maxSessions", "collectionLimit"] as const) {
+ const n = Number(args[key]);
+ if (Number.isInteger(n) && n > 0) exportPayload[key] = n;
+ }
+ for (const key of ["offset", "collectionOffset"] as const) {
+ const n = Number(args[key]);
+ if (Number.isInteger(n) && n >= 0) exportPayload[key] = n;
+ }
+ if (typeof args.collections === "string") {
+ exportPayload.collections = args.collections;
+ }
+ const result = await sdk.trigger({ function_id: "mem::export", payload: exportPayload });
return {
status_code: 200,
body: {
diff --git a/src/mcp/standalone.ts b/src/mcp/standalone.ts
index 8fd7f58e..0a5a8206 100644
--- a/src/mcp/standalone.ts
+++ b/src/mcp/standalone.ts
@@ -133,6 +133,7 @@ interface Validated {
includeLessons?: boolean;
memoryIds?: string[];
reason?: string;
+ exportQuery?: string;
sessionQuery?: Record<string, string>;
}
@@ -212,8 +213,17 @@ function validate(toolName: string, args: Record<string, unknown>): Validated {
v.reason = (args["reason"] as string) || "plugin skill request";
return v;
}
- case "memory_export":
+ case "memory_export": {
+ const query = new URLSearchParams();
+ for (const key of ["maxSessions", "offset", "collectionLimit", "collectionOffset"]) {
+ const n = Number(args[key]);
+ const min = key === "maxSessions" || key === "collectionLimit" ? 1 : 0;
+ if (args[key] !== undefined && Number.isInteger(n) && n >= min) query.set(key, String(n));
+ }
+ if (typeof args["collections"] === "string") query.set("collections", args["collections"]);
+ v.exportQuery = query.toString();
return v;
+ }
case "memory_audit": {
v.limit = parseLimit(args["limit"], 50);
return v;
@@ -293,7 +303,10 @@ async function handleProxy(
}
case "memory_export": {
try {
- const result = await handle.call("/agentmemory/export", { method: "GET" });
+ const result = await handle.call(
+ `/agentmemory/export${v.exportQuery ? `?${v.exportQuery}` : ""}`,
+ { method: "GET" },
+ );
return textResponse(result, true);
} catch (err) {
if (
diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts
index c7ef910d..22ffa047 100644
--- a/src/mcp/tools-registry.ts
+++ b/src/mcp/tools-registry.ts
@@ -223,8 +223,32 @@ export const CORE_TOOLS: McpToolDef[] = [
},
{
name: "memory_export",
- description: "Export all memory data as JSON.",
- inputSchema: { type: "object", properties: {} },
+ description:
+ "Export memory data as JSON. Past the transport size limit the export is refused, so use the paging arguments on a large store.",
+ inputSchema: {
+ type: "object",
+ properties: {
+ maxSessions: {
+ type: "number",
+ description: "Sessions per page (with their observations)",
+ },
+ offset: { type: "number", description: "Session offset" },
+ collectionLimit: {
+ type: "number",
+ description:
+ "Rows per page for memories, summaries, graphNodes, lessons and the other top-level collections; access logs follow the memories on the page. Sessions and their observations are paged only by maxSessions and offset, so pass collections to leave them out of each page",
+ },
+ collectionOffset: {
+ type: "number",
+ description: "Row offset for the top-level collections",
+ },
+ collections: {
+ type: "string",
+ description:
+ "Comma-separated collections to return, e.g. memories,lessons. Sessions and their observations come back only when the list names sessions, access logs only together with memories. Unknown names are ignored. Omit for everything. A paged or selected export cannot be imported with strategy replace.",
+ },
+ },
+ },
},
{
name: "memory_relations",
diff --git a/src/triggers/api.ts b/src/triggers/api.ts
index 566eb86d..f4eaf079 100644
--- a/src/triggers/api.ts
+++ b/src/triggers/api.ts
@@ -1970,9 +1970,18 @@ export function registerApiTriggers(
// real corpus (40 sessions × 34K observations × 8K memories) hit the
// iii engine invocation timeout and `agentmemory status` reported 0.
// Pass through the query-string pagination so callers can chunk.
+ const payload: {
+ maxSessions?: number;
+ offset?: number;
+ collectionLimit?: number;
+ collectionOffset?: number;
+ collections?: string;
+ } = {};
const rawMax = req.query_params?.["maxSessions"];
const rawOffset = req.query_params?.["offset"];
- const payload: { maxSessions?: number; offset?: number } = {};
+ const rawCollectionLimit = req.query_params?.["collectionLimit"];
+ const rawCollectionOffset = req.query_params?.["collectionOffset"];
+ const rawCollections = req.query_params?.["collections"];
if (typeof rawMax === "string") {
const n = Number(rawMax);
if (Number.isInteger(n) && n > 0) payload.maxSessions = n;
@@ -1981,6 +1990,17 @@ export function registerApiTriggers(
const n = Number(rawOffset);
if (Number.isInteger(n) && n >= 0) payload.offset = n;
}
+ if (typeof rawCollectionLimit === "string") {
+ const n = Number(rawCollectionLimit);
+ if (Number.isInteger(n) && n > 0) payload.collectionLimit = n;
+ }
+ if (typeof rawCollectionOffset === "string") {
+ const n = Number(rawCollectionOffset);
+ if (Number.isInteger(n) && n >= 0) payload.collectionOffset = n;
+ }
+ if (typeof rawCollections === "string") {
+ payload.collections = rawCollections;
+ }
const result = await sdk.trigger({
function_id: "mem::export",
payload,
diff --git a/src/types.ts b/src/types.ts
index 0feecabc..92b7e998 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -382,6 +382,14 @@ export interface ExportPagination {
hasMore: boolean;
}
+export interface ExportCollectionPagination {
+ offset: number;
+ limit?: number;
+ collections?: string[];
+ totals: Record<string, number>;
+ hasMore: boolean;
+}
+
export interface ExportData {
version: "0.3.0" | "0.4.0" | "0.5.0" | "0.6.0" | "0.6.1" | "0.7.0" | "0.7.2" | "0.7.3" | "0.7.4" | "0.7.5" | "0.7.6" | "0.7.7" | "0.7.9" | "0.8.0" | "0.8.1" | "0.8.2" | "0.8.3" | "0.8.4" | "0.8.5" | "0.8.6" | "0.8.7" | "0.8.8" | "0.8.9" | "0.8.10" | "0.8.11" | "0.8.12" | "0.8.13" | "0.9.0" | "0.9.1" | "0.9.2" | "0.9.3" | "0.9.4" | "0.9.5" | "0.9.6" | "0.9.7" | "0.9.8" | "0.9.9" | "0.9.10" | "0.9.11" | "0.9.12" | "0.9.13" | "0.9.14" | "0.9.15" | "0.9.16" | "0.9.17" | "0.9.18" | "0.9.19" | "0.9.20" | "0.9.21" | "0.9.22" | "0.9.23" | "0.9.24" | "0.9.25" | "0.9.26" | "0.9.27" | "0.9.28" | "0.9.29" | "0.9.30";
exportedAt: string;
@@ -407,6 +415,7 @@ export interface ExportData {
insights?: Insight[];
accessLogs?: AccessLogExport[];
pagination?: ExportPagination;
+ collectionPagination?: ExportCollectionPagination;
}
export interface AccessLogExport {
diff --git a/test/export-import.test.ts b/test/export-import.test.ts
index 5e2c9c4c..4ed46449 100644
--- a/test/export-import.test.ts
+++ b/test/export-import.test.ts
@@ -430,3 +430,295 @@ describe("import bounds graph provenance", () => {
expect(e!.sourceObservationIds).toEqual(bloatedIds("eobs", 100).slice(-32));
});
});
+
+describe("Export collection pagination", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerExportImportFunction(sdk as never, kv as never);
+ await kv.set("mem:sessions", "ses_1", testSession);
+ for (let i = 0; i < 7; i++) {
+ await kv.set("mem:memories", `mem_${i}`, { ...testMemory, id: `mem_${i}` });
+ }
+ for (let i = 0; i < 5; i++) {
+ await kv.set("mem:graph:nodes", `node_${i}`, { id: `node_${i}`, label: `n${i}` });
+ }
+ });
+
+ it("returns every collection in full when no collection limit is given", async () => {
+ const result = (await sdk.trigger("mem::export", {})) as ExportData;
+
+ expect(result.memories.length).toBe(7);
+ expect(result.graphNodes?.length).toBe(5);
+ expect(result.collectionPagination).toBeUndefined();
+ });
+
+ it("bounds every collection, not just sessions, when a collection limit is given", async () => {
+ const result = (await sdk.trigger("mem::export", {
+ collectionLimit: 3,
+ })) as ExportData;
+
+ expect(result.memories.length).toBe(3);
+ expect(result.graphNodes?.length).toBe(3);
+ expect(result.collectionPagination?.limit).toBe(3);
+ expect(result.collectionPagination?.offset).toBe(0);
+ expect(result.collectionPagination?.totals["memories"]).toBe(7);
+ expect(result.collectionPagination?.totals["graphNodes"]).toBe(5);
+ expect(result.collectionPagination?.hasMore).toBe(true);
+ });
+
+ it("walks a collection to its end across pages", async () => {
+ const page2 = (await sdk.trigger("mem::export", {
+ collectionLimit: 3,
+ collectionOffset: 3,
+ })) as ExportData;
+ expect(page2.memories.length).toBe(3);
+ expect(page2.collectionPagination?.offset).toBe(3);
+ expect(page2.collectionPagination?.limit).toBe(3);
+ expect(page2.collectionPagination?.hasMore).toBe(true);
+
+ const page3 = (await sdk.trigger("mem::export", {
+ collectionLimit: 3,
+ collectionOffset: 6,
+ })) as ExportData;
+ expect(page3.memories.length).toBe(1);
+ expect(page3.collectionPagination?.hasMore).toBe(false);
+ });
+});
+
+describe("Export collection pages and import", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+ const logged = ["mem_0", "mem_2", "mem_4", "mem_5", "mem_6"];
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerExportImportFunction(sdk as never, kv as never);
+ for (let i = 0; i < 7; i++) {
+ await kv.set("mem:memories", `mem_${i}`, { ...testMemory, id: `mem_${i}` });
+ }
+ for (const id of logged) {
+ await kv.set("mem:access", id, { memoryId: id, count: 2, lastAt: "2026-02-01T00:00:00Z", recent: [] });
+ }
+ });
+
+ it("pages access logs together with the memories they belong to", async () => {
+ const seen: string[] = [];
+ for (const collectionOffset of [0, 3, 6]) {
+ const page = (await sdk.trigger("mem::export", {
+ collectionLimit: 3,
+ collectionOffset,
+ })) as ExportData;
+ const ids = new Set(page.memories.map((m) => m.id));
+ const logIds = (page.accessLogs ?? []).map((l) => l.memoryId);
+ expect(logIds.every((id) => ids.has(id))).toBe(true);
+ expect(page.collectionPagination?.totals["accessLogs"]).toBe(5);
+ seen.push(...logIds);
+ }
+ expect(seen.sort()).toEqual(logged);
+ });
+
+ it("restores every access log when the pages are imported one by one", async () => {
+ const target = mockKV();
+ const targetSdk = mockSdk();
+ registerExportImportFunction(targetSdk as never, target as never);
+ for (const collectionOffset of [0, 3, 6]) {
+ const page = await sdk.trigger("mem::export", { collectionLimit: 3, collectionOffset });
+ const result = (await targetSdk.trigger("mem::import", {
+ exportData: page,
+ strategy: "merge",
+ })) as { success: boolean };
+ expect(result.success).toBe(true);
+ }
+ expect((await target.list("mem:memories")).length).toBe(7);
+ expect((await target.list("mem:access")).length).toBe(5);
+ });
+
+ it("refuses to replace the store with a page of an export", async () => {
+ const page = await sdk.trigger("mem::export", { collectionLimit: 3 });
+ const result = (await sdk.trigger("mem::import", {
+ exportData: page,
+ strategy: "replace",
+ })) as { success: boolean; error?: string };
+
+ expect(result.success).toBe(false);
+ expect(result.error).toMatch(/replace/);
+ expect((await kv.list("mem:memories")).length).toBe(7);
+ });
+
+ it("refuses to replace the store with a selection of collections", async () => {
+ const selection = await sdk.trigger("mem::export", { collections: "memories" });
+ const result = (await sdk.trigger("mem::import", {
+ exportData: selection,
+ strategy: "replace",
+ })) as { success: boolean };
+
+ expect(result.success).toBe(false);
+ expect((await kv.list("mem:access")).length).toBe(5);
+ });
+
+ it("refuses to replace the store with a page of sessions", async () => {
+ for (const id of ["ses_1", "ses_2", "ses_3"]) {
+ await kv.set("mem:sessions", id, { ...testSession, id });
+ }
+ for (const offset of [0, 2]) {
+ const page = await sdk.trigger("mem::export", { maxSessions: 2, offset });
+ const result = (await sdk.trigger("mem::import", {
+ exportData: page,
+ strategy: "replace",
+ })) as { success: boolean };
+ expect(result.success).toBe(false);
+ }
+ expect((await kv.list("mem:sessions")).length).toBe(3);
+ expect((await kv.list("mem:memories")).length).toBe(7);
+ });
+
+ it("replaces the store with a session window that covers every session", async () => {
+ await kv.set("mem:sessions", "ses_1", testSession);
+ const whole = await sdk.trigger("mem::export", { maxSessions: 10 });
+ const result = (await sdk.trigger("mem::import", {
+ exportData: whole,
+ strategy: "replace",
+ })) as { success: boolean };
+
+ expect(result.success).toBe(true);
+ });
+
+ it("reports no further page for an access-log selection", async () => {
+ const page = (await sdk.trigger("mem::export", {
+ collections: "accessLogs",
+ collectionLimit: 3,
+ })) as ExportData;
+
+ expect(page.collectionPagination?.hasMore).toBe(false);
+ });
+});
+
+describe("Export collection allowlist", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+ let kv: ReturnType<typeof mockKV>;
+
+ beforeEach(async () => {
+ sdk = mockSdk();
+ kv = mockKV();
+ registerExportImportFunction(sdk as never, kv as never);
+ await kv.set("mem:sessions", "ses_1", testSession);
+ await kv.set("mem:obs:ses_1", "obs_1", testObs);
+ await kv.set("mem:summaries", "ses_1", testSummary);
+ for (let i = 0; i < 7; i++) {
+ await kv.set("mem:memories", `mem_${i}`, { ...testMemory, id: `mem_${i}` });
+ }
+ for (let i = 0; i < 20; i++) {
+ await kv.set("mem:graph:nodes", `node_${i}`, { id: `node_${i}`, label: `n${i}` });
+ }
+ });
+
+ it("drops the collections outside the allowlist", async () => {
+ await kv.set("mem:access", "mem_0", { memoryId: "mem_0", count: 1, lastAt: "2026-02-01T00:00:00Z", recent: [] });
+ const result = (await sdk.trigger("mem::export", {
+ collections: ["memories", "summaries"],
+ })) as ExportData;
+
+ expect(result.memories.length).toBe(7);
+ expect(result.summaries.length).toBe(1);
+ expect(result.graphNodes).toBeUndefined();
+ expect(result.accessLogs).toBeUndefined();
+ });
+
+ it("accepts the allowlist as a comma-separated string", async () => {
+ const result = (await sdk.trigger("mem::export", {
+ collections: "memories, summaries",
+ })) as ExportData;
+
+ expect(result.memories.length).toBe(7);
+ expect(result.summaries.length).toBe(1);
+ expect(result.graphNodes).toBeUndefined();
+ });
+
+ it("keeps collectionTotals reporting every collection", async () => {
+ const result = (await sdk.trigger("mem::export", {
+ collections: ["memories"],
+ collectionLimit: 3,
+ })) as ExportData;
+
+ expect(result.collectionPagination?.totals["memories"]).toBe(7);
+ expect(result.collectionPagination?.totals["summaries"]).toBe(1);
+ expect(result.collectionPagination?.totals["graphNodes"]).toBe(20);
+ });
+
+ it("computes hasMore from the allowlist alone", async () => {
+ const selected = (await sdk.trigger("mem::export", {
+ collections: ["memories"],
+ collectionLimit: 7,
+ })) as ExportData;
+ expect(selected.collectionPagination?.hasMore).toBe(false);
+
+ const everything = (await sdk.trigger("mem::export", {
+ collectionLimit: 7,
+ })) as ExportData;
+ expect(everything.collectionPagination?.hasMore).toBe(true);
+ });
+
+ it("ignores unknown collection names instead of failing", async () => {
+ const result = (await sdk.trigger("mem::export", {
+ collections: ["memories", "notACollection"],
+ collectionLimit: 7,
+ })) as ExportData;
+
+ expect(result.memories.length).toBe(7);
+ expect(result.graphNodes).toBeUndefined();
+ expect(result.collectionPagination?.collections).toEqual(["memories"]);
+ expect(result.collectionPagination?.hasMore).toBe(false);
+ });
+
+ it("selects nothing when the allowlist names no known collection", async () => {
+ const result = (await sdk.trigger("mem::export", {
+ collections: ["notACollection"],
+ collectionLimit: 3,
+ })) as ExportData;
+
+ expect(result.memories).toEqual([]);
+ expect(result.summaries).toEqual([]);
+ expect(result.graphNodes).toBeUndefined();
+ expect(result.collectionPagination?.totals["memories"]).toBe(7);
+ expect(result.collectionPagination?.hasMore).toBe(false);
+ });
+
+ it("treats an empty allowlist as an explicit empty selection", async () => {
+ const result = (await sdk.trigger("mem::export", {
+ collections: "",
+ })) as ExportData;
+
+ expect(result.memories).toEqual([]);
+ expect(result.graphNodes).toBeUndefined();
+ });
+
+ it("exports sessions only when the selection names them", async () => {
+ const without = (await sdk.trigger("mem::export", {
+ collections: ["memories"],
+ })) as ExportData;
+ expect(without.sessions).toEqual([]);
+ expect(without.observations).toEqual({});
+
+ const withSessions = (await sdk.trigger("mem::export", {
+ collections: ["memories", "sessions"],
+ })) as ExportData;
+ expect(withSessions.sessions.length).toBe(1);
+ expect(withSessions.observations["ses_1"].length).toBe(1);
+ });
+
+ it("marks a selection without a collection limit as partial", async () => {
+ const result = (await sdk.trigger("mem::export", {
+ collections: "memories",
+ })) as ExportData;
+
+ expect(result.collectionPagination?.collections).toEqual(["memories"]);
+ expect(result.collectionPagination?.limit).toBeUndefined();
+ expect(result.collectionPagination?.totals["graphNodes"]).toBe(20);
+ expect(result.collectionPagination?.hasMore).toBe(false);
+ });
+});
diff --git a/test/export-incremental-budget.test.ts b/test/export-incremental-budget.test.ts
index e7ac00e8..aeb71f19 100644
--- a/test/export-incremental-budget.test.ts
+++ b/test/export-incremental-budget.test.ts
@@ -160,6 +160,50 @@ describe("mem::export stops assembling once the frame budget is exceeded", () =>
});
});
+describe("mem::export pages a collection that alone exceeds the frame limit", () => {
+ it("serves summaries in pages under the limit once the whole collection is refused", async () => {
+ const kv = countingKV();
+ const sdk = mockSdk();
+ registerExportImportFunction(sdk as never, kv as never);
+ registerApiTriggers(sdk as never, kv as never, BEARER);
+ seedSessions(kv, 3, 10);
+ const ids: string[] = [];
+ for (let i = 0; i < 24; i++) {
+ ids.push(`ses_${i}`);
+ kv.seed(KV.summaries, `ses_${i}`, { sessionId: `ses_${i}`, narrative: "s".repeat(MIB) });
+ }
+ type Page = {
+ status_code: number;
+ body: {
+ stoppedAt?: string;
+ summaries: Array<{ sessionId: string }>;
+ collectionPagination: { hasMore: boolean };
+ };
+ };
+ const get = (query_params: Record<string, string>) =>
+ sdk.fns.get("api::export")!({
+ headers: { authorization: `Bearer ${BEARER}` },
+ query_params,
+ }) as Promise<Page>;
+
+ const whole = await get({});
+ expect(whole.status_code).toBe(413);
+ expect(whole.body.stoppedAt).toBe("summaries");
+
+ const exported: string[] = [];
+ let last: Page | undefined;
+ for (const collectionOffset of ["0", "10", "20"]) {
+ last = await get({ collections: "summaries", collectionLimit: "10", collectionOffset });
+ expect(last.status_code).toBe(200);
+ expect(payloadByteLength(last.body)).toBeLessThanOrEqual(SAFE_PAYLOAD_BYTES);
+ exported.push(...last.body.summaries.map((s) => s.sessionId));
+ }
+
+ expect(last!.body.collectionPagination.hasMore).toBe(false);
+ expect(exported.sort()).toEqual(ids.sort());
+ });
+});
+
describe("ExportBudget", () => {
it("tracks a collection's serialized size to within its framing", () => {
const items = [{ a: 1 }, { b: "two" }, { c: [3, 4] }];
diff --git a/test/export-refusal-status.test.ts b/test/export-refusal-status.test.ts
index f1b65d11..058277c6 100644
--- a/test/export-refusal-status.test.ts
+++ b/test/export-refusal-status.test.ts
@@ -101,3 +101,32 @@ describe("api::export refusal status", () => {
expect(res.body.version).toBeUndefined();
});
});
+
+describe("api::export collection paging parameters", () => {
+ it("forwards collectionLimit, collectionOffset and collections to mem::export", async () => {
+ const kv = mockKV();
+ for (let i = 0; i < 7; i++) {
+ await kv.set(KV.memories, `m${i}`, { ...hugeMemory(), id: `m${i}`, content: "small" });
+ }
+ for (let i = 0; i < 3; i++) {
+ await kv.set(KV.graphNodes, `n${i}`, { id: `n${i}` });
+ }
+ const sdk = mockSdk();
+ registerExportImportFunction(sdk as never, kv as never);
+ registerApiTriggers(sdk as never, kv as never, SECRET);
+
+ const res = await sdk._fns.get("api::export")!({
+ headers: { authorization: `Bearer ${SECRET}` },
+ query_params: { collectionLimit: "3", collectionOffset: "6", collections: "memories" },
+ });
+
+ expect(res.status_code).toBe(200);
+ expect((res.body.memories as Memory[]).map((m) => m.id)).toEqual(["m6"]);
+ expect(res.body.graphNodes).toBeUndefined();
+ expect(res.body.collectionPagination).toMatchObject({
+ offset: 6,
+ limit: 3,
+ collections: ["memories"],
+ });
+ });
+});
diff --git a/test/mcp-export-tool.test.ts b/test/mcp-export-tool.test.ts
new file mode 100644
index 00000000..534e6eed
--- /dev/null
+++ b/test/mcp-export-tool.test.ts
@@ -0,0 +1,173 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+vi.mock("../src/logger.js", () => ({
+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+import { registerMcpEndpoints } from "../src/mcp/server.js";
+import { registerExportImportFunction } from "../src/functions/export-import.js";
+import type { ExportData } from "../src/types.js";
+
+function mockKV() {
+ const store = new Map<string, Map<string, unknown>>();
+ return {
+ get: async <T>(scope: string, key: string): Promise<T | null> =>
+ (store.get(scope)?.get(key) as T) ?? null,
+ set: async <T>(scope: string, key: string, data: T): Promise<T> => {
+ if (!store.has(scope)) store.set(scope, new Map());
+ store.get(scope)!.set(key, data);
+ return data;
+ },
+ delete: async (scope: string, key: string): Promise<void> => {
+ store.get(scope)?.delete(key);
+ },
+ list: async <T>(scope: string): Promise<T[]> => {
+ const entries = store.get(scope);
+ return entries ? (Array.from(entries.values()) as T[]) : [];
+ },
+ };
+}
+
+function mockSdk() {
+ const functions = new Map<string, Function>();
+ const overrides = new Map<string, Function>();
+ return {
+ registerFunction: (idOrOpts: string | { id: string }, handler: Function) => {
+ functions.set(
+ typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id,
+ handler,
+ );
+ },
+ registerTrigger: () => {},
+ trigger: async (
+ idOrInput: string | { function_id: string; payload: unknown },
+ data?: unknown,
+ ) => {
+ const id =
+ typeof idOrInput === "string" ? idOrInput : idOrInput.function_id;
+ const payload = typeof idOrInput === "string" ? data : idOrInput.payload;
+ if (overrides.has(id)) return overrides.get(id)!(payload);
+ const fn = functions.get(id);
+ if (!fn) throw new Error(`No function: ${id}`);
+ return fn(payload);
+ },
+ overrideTrigger: (id: string, handler: Function) => {
+ overrides.set(id, handler);
+ },
+ getFunction: (id: string) => functions.get(id),
+ };
+}
+
+function callTool(sdk: ReturnType<typeof mockSdk>, args: unknown) {
+ const fn = sdk.getFunction("mcp::tools::call")!;
+ return fn({
+ body: { name: "memory_export", arguments: args },
+ headers: {},
+ query_params: {},
+ }) as Promise<{ status_code: number; body: unknown }>;
+}
+
+describe("memory_export MCP tool", () => {
+ let sdk: ReturnType<typeof mockSdk>;
+
+ beforeEach(() => {
+ sdk = mockSdk();
+ registerMcpEndpoints(sdk as never, mockKV() as never);
+ });
+
+ it("forwards the paging arguments to mem::export", async () => {
+ let seen: unknown;
+ sdk.overrideTrigger("mem::export", (payload: unknown) => {
+ seen = payload;
+ return { version: "0.9.28", sessions: [], memories: [] };
+ });
+
+ await callTool(sdk, {
+ maxSessions: 100,
+ offset: 200,
+ collectionLimit: 300,
+ collectionOffset: 400,
+ });
+
+ expect(seen).toEqual({
+ maxSessions: 100,
+ offset: 200,
+ collectionLimit: 300,
+ collectionOffset: 400,
+ });
+ });
+
+ it("drops arguments that are not usable page bounds", async () => {
+ let seen: unknown;
+ sdk.overrideTrigger("mem::export", (payload: unknown) => {
+ seen = payload;
+ return { version: "0.9.28", sessions: [], memories: [] };
+ });
+
+ await callTool(sdk, {
+ maxSessions: 0,
+ offset: -1,
+ collectionLimit: "many",
+ collectionOffset: 1.5,
+ });
+
+ expect(seen).toEqual({});
+ });
+
+ it("forwards the collections allowlist as given", async () => {
+ let seen: unknown;
+ sdk.overrideTrigger("mem::export", (payload: unknown) => {
+ seen = payload;
+ return { version: "0.9.28", sessions: [], memories: [] };
+ });
+
+ await callTool(sdk, { collections: "memories,lessons" });
+
+ expect(seen).toEqual({ collections: "memories,lessons" });
+ });
+
+ it("keeps an empty allowlist distinguishable from an absent one", async () => {
+ const seen: unknown[] = [];
+ sdk.overrideTrigger("mem::export", (payload: unknown) => {
+ seen.push(payload);
+ return { version: "0.9.28", sessions: [], memories: [] };
+ });
+
+ await callTool(sdk, { collections: "" });
+ await callTool(sdk, {});
+
+ expect(seen).toEqual([{ collections: "" }, {}]);
+ });
+
+ it("still returns a normal export as 200", async () => {
+ sdk.overrideTrigger("mem::export", () => ({
+ version: "0.9.28",
+ sessions: [],
+ memories: [],
+ }));
+
+ const result = await callTool(sdk, {});
+
+ expect(result.status_code).toBe(200);
+ expect(result.body).toHaveProperty("content");
+ });
+});
+
+describe("memory_export MCP tool against mem::export", () => {
+ it("returns the requested page of a real export", async () => {
+ const sdk = mockSdk();
+ const kv = mockKV();
+ registerExportImportFunction(sdk as never, kv as never);
+ registerMcpEndpoints(sdk as never, kv as never);
+ for (let i = 0; i < 7; i++) {
+ await kv.set("mem:memories", `mem_${i}`, { id: `mem_${i}`, title: `m${i}` });
+ }
+
+ const result = await callTool(sdk, { collections: "memories", collectionLimit: 3 });
+ const body = result.body as { content: Array<{ text: string }> };
+ const page = JSON.parse(body.content[0]!.text) as ExportData;
+
+ expect(page.memories).toHaveLength(3);
+ expect(page.collectionPagination).toMatchObject({ limit: 3, hasMore: true });
+ });
+});
diff --git a/test/mcp-standalone-proxy.test.ts b/test/mcp-standalone-proxy.test.ts
index ec5ed4f2..6101e9bd 100644
--- a/test/mcp-standalone-proxy.test.ts
+++ b/test/mcp-standalone-proxy.test.ts
@@ -311,6 +311,54 @@ describe("@agentmemory/mcp standalone — server proxy", () => {
expect(probeCount).toBe(1);
});
+ it("forwards memory_export paging arguments to /agentmemory/export", async () => {
+ const urls: string[] = [];
+ installFetch((url) => {
+ urls.push(url);
+ if (url.endsWith("/agentmemory/livez")) return new Response("ok", { status: 200 });
+ if (url.includes("/agentmemory/export")) {
+ return new Response(JSON.stringify({ version: "0.9.29" }), { status: 200 });
+ }
+ return new Response("", { status: 404 });
+ });
+
+ await handleToolCall("memory_export", {
+ maxSessions: 2,
+ offset: 4,
+ collectionLimit: 10,
+ collectionOffset: 20,
+ collections: "",
+ });
+
+ const exportUrl = new URL(urls.find((u) => u.includes("/agentmemory/export"))!);
+ expect(Object.fromEntries(exportUrl.searchParams)).toEqual({
+ maxSessions: "2",
+ offset: "4",
+ collectionLimit: "10",
+ collectionOffset: "20",
+ collections: "",
+ });
+ });
+
+ it("drops memory_export arguments that are not usable page bounds", async () => {
+ const urls: string[] = [];
+ installFetch((url) => {
+ urls.push(url);
+ if (url.endsWith("/agentmemory/livez")) return new Response("ok", { status: 200 });
+ return new Response(JSON.stringify({ version: "0.9.29" }), { status: 200 });
+ });
+
+ await handleToolCall("memory_export", {
+ maxSessions: 0,
+ offset: -1,
+ collectionLimit: "many",
+ collectionOffset: 1.5,
+ });
+
+ const exportUrl = new URL(urls.find((u) => u.includes("/agentmemory/export"))!);
+ expect(exportUrl.search).toBe("");
+ });
+
it("forwards non-essential tools to /agentmemory/mcp/call", async () => {
const calls: Array<{ url: string; body?: unknown }> = [];
installFetch((url, init) => {