From f0b20da1953680ab058f3e0904477c2f1de2d857 Mon Sep 17 00:00:00 2001 From: Dmitrii Zhukov Date: Sat, 3 Oct 2026 13:37:05 +0800 Subject: [PATCH 1/5] feat(export): page the collections the export budget refuses The export refuses a store that does not fit one transport frame, and its hint said the non-session collections "are not yet paginated". They are now: ?collectionLimit / ?collectionOffset window memories, summaries and the sixteen top-level collections, and ?collections= returns only the named ones. Sessions and their observations come back only when the list names sessions, so a client after lessons does not pull every session. Access logs follow the memories on the page, because import keeps a log only next to its memory. A paged or selected export carries collectionPagination (totals for every collection, the selection, hasMore over the selected ones), and import refuses strategy replace for such a file instead of wiping everything the file does not hold. Without these parameters the response is unchanged. Signed-off-by: Dmitrii Zhukov --- README.md | 2 +- src/functions/export-import.ts | 97 ++++++++++- src/triggers/api.ts | 22 ++- src/types.ts | 9 + test/export-import.test.ts | 253 +++++++++++++++++++++++++++++ test/export-refusal-status.test.ts | 29 ++++ 6 files changed, 404 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1c22f8af8e..5183c2602a 100644 --- a/README.md +++ b/README.md @@ -1356,7 +1356,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/src/functions/export-import.ts b/src/functions/export-import.ts index eb49f01233..0ba8861a0b 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -67,7 +67,7 @@ async function runChunked( } 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 = [ ["graphNodes", KV.graphNodes], @@ -88,6 +88,23 @@ const EXPORT_COLLECTIONS: ReadonlyArray = [ ["accessLogs", KV.accessLog], ]; +const EXPORT_COLLECTION_NAMES: ReadonlySet = new Set([ + "sessions", + "memories", + "summaries", + ...EXPORT_COLLECTIONS.map(([field]) => field), +]); + +function parseCollections(raw: unknown): ReadonlySet | 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; @@ -105,11 +122,39 @@ export class ExportBudget { export function registerExportImportFunction(sdk: IIIClient, kv: 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 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 = {}; + const sliceCollection = (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) => { @@ -126,15 +171,19 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void kv.list(scope).catch(() => [] as T[]); const allSessions = await kv.list(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(KV.memories); + const memories = sliceCollection("memories", await kv.list(KV.memories)); if (!budget.fits(memories)) return refuse("memories"); - const summaries = await kv.list(KV.summaries); + const summaries = sliceCollection( + "summaries", + await kv.list(KV.summaries), + ); if (!budget.fits(summaries)) return refuse("summaries"); const observations: Record = {}; @@ -159,9 +208,20 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void } 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 = {}; for (const [field, scope] of EXPORT_COLLECTIONS) { - const items = await optional(scope); + const rows = await optional(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)[field] = items; @@ -187,6 +247,23 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void }; } + 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", { @@ -205,6 +282,7 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void observations: totalObs, memories: memories.length, summaries: summaries.length, + collections: selection && [...selection], }); return exportData; @@ -233,6 +311,13 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void error: `Unsupported export version: ${importData.version}`, }; } + if (strategy === "replace" && importData.collectionPagination) { + 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/triggers/api.ts b/src/triggers/api.ts index 80885c8fdd..512ce52391 100644 --- a/src/triggers/api.ts +++ b/src/triggers/api.ts @@ -1870,9 +1870,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; @@ -1881,6 +1890,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 02c1b52098..f6ed0813a5 100644 --- a/src/types.ts +++ b/src/types.ts @@ -355,6 +355,14 @@ export interface ExportPagination { hasMore: boolean; } +export interface ExportCollectionPagination { + offset: number; + limit?: number; + collections?: string[]; + totals: Record; + 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"; exportedAt: string; @@ -380,6 +388,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 8dfe5fbb40..a82b4745f3 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -368,3 +368,256 @@ describe("import bounds graph provenance", () => { expect(e!.sourceObservationIds).toEqual(bloatedIds("eobs", 100).slice(-32)); }); }); + +describe("Export collection pagination", () => { + let sdk: ReturnType; + let kv: ReturnType; + + 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; + let kv: ReturnType; + 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); + }); +}); + +describe("Export collection allowlist", () => { + let sdk: ReturnType; + let kv: ReturnType; + + 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 () => { + 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("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?.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-refusal-status.test.ts b/test/export-refusal-status.test.ts index f1b65d11c6..058277c6fd 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"], + }); + }); +}); From 83ba43c7f8b54563873b52a4aae0db9ddf191971 Mon Sep 17 00:00:00 2001 From: Dmitrii Zhukov Date: Sat, 3 Oct 2026 13:37:05 +0800 Subject: [PATCH 2/5] feat(mcp): let memory_export reach the export paging arguments The tool declared no properties and always exported with an empty payload, both through the server's /mcp/call and through the @agentmemory/mcp shim the plugin launches, so the paging the REST endpoint offers was out of reach from MCP. Both now forward maxSessions, offset, collectionLimit, collectionOffset and collections; the shim passes them as the query string of /agentmemory/export. collections is forwarded raw, empty value included: an empty selection means no collections, and that only stays distinguishable from an absent argument if this layer does not drop it. Signed-off-by: Dmitrii Zhukov --- .../skills/agentmemory-mcp-tools/REFERENCE.md | 2 +- src/mcp/server.ts | 20 ++- src/mcp/standalone.ts | 17 +- src/mcp/tools-registry.ts | 28 +++- test/mcp-export-tool.test.ts | 152 ++++++++++++++++++ test/mcp-standalone-proxy.test.ts | 48 ++++++ 6 files changed, 261 insertions(+), 6 deletions(-) create mode 100644 test/mcp-export-tool.test.ts diff --git a/plugin/skills/agentmemory-mcp-tools/REFERENCE.md b/plugin/skills/agentmemory-mcp-tools/REFERENCE.md index fc01a8dd75..f55bf297d1 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/mcp/server.ts b/src/mcp/server.ts index be5ad36551..b02215200b 100644 --- a/src/mcp/server.ts +++ b/src/mcp/server.ts @@ -352,7 +352,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 b173934a60..868d7f5a6d 100644 --- a/src/mcp/standalone.ts +++ b/src/mcp/standalone.ts @@ -115,6 +115,7 @@ interface Validated { tokenBudget?: number; memoryIds?: string[]; reason?: string; + exportQuery?: string; } function validate(toolName: string, args: Record): Validated { @@ -175,8 +176,17 @@ function validate(toolName: string, args: Record): 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; @@ -244,7 +254,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 17b658de29..571e05d5a2 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -200,8 +200,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", + }, + 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. Unknown names are ignored. Omit for everything. A paged or selected export cannot be imported with strategy replace.", + }, + }, + }, }, { name: "memory_relations", diff --git a/test/mcp-export-tool.test.ts b/test/mcp-export-tool.test.ts new file mode 100644 index 0000000000..d0775d648b --- /dev/null +++ b/test/mcp-export-tool.test.ts @@ -0,0 +1,152 @@ +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"; + +function mockKV() { + const store = new Map>(); + return { + get: async (scope: string, key: string): Promise => + (store.get(scope)?.get(key) as T) ?? null, + set: async (scope: string, key: string, data: T): Promise => { + if (!store.has(scope)) store.set(scope, new Map()); + store.get(scope)!.set(key, data); + return data; + }, + delete: async (scope: string, key: string): Promise => { + store.get(scope)?.delete(key); + }, + list: async (scope: string): Promise => { + const entries = store.get(scope); + return entries ? (Array.from(entries.values()) as T[]) : []; + }, + }; +} + +function mockSdk() { + const functions = new Map(); + const overrides = new Map(); + 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, 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; + + 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"); + }); +}); diff --git a/test/mcp-standalone-proxy.test.ts b/test/mcp-standalone-proxy.test.ts index fa0dbcf50e..6daa4791dc 100644 --- a/test/mcp-standalone-proxy.test.ts +++ b/test/mcp-standalone-proxy.test.ts @@ -269,6 +269,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) => { From a691dc3c89f05108adf406ea26a661c00c96dead Mon Sep 17 00:00:00 2001 From: Dmitrii Zhukov Date: Tue, 13 Oct 2026 11:50:40 +0000 Subject: [PATCH 3/5] test(export): cover summaries past the frame limit and the selection edges A store whose summaries alone exceed the frame limit is refused whole and exported in pages with collections=summaries and collectionLimit. Unknown collection names stay out of the echoed selection, access logs stay out unless memories are selected, an access-log selection reports no further page, and memory_export pages a real export end to end. Signed-off-by: Dmitrii Zhukov --- test/export-import.test.ts | 13 ++++++++ test/export-incremental-budget.test.ts | 44 ++++++++++++++++++++++++++ test/mcp-export-tool.test.ts | 21 ++++++++++++ 3 files changed, 78 insertions(+) diff --git a/test/export-import.test.ts b/test/export-import.test.ts index a82b4745f3..7e575f6651 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -498,6 +498,16 @@ describe("Export collection pages and import", () => { expect(result.success).toBe(false); expect((await kv.list("mem:access")).length).toBe(5); }); + + + 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", () => { @@ -520,6 +530,7 @@ describe("Export collection allowlist", () => { }); 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; @@ -527,6 +538,7 @@ describe("Export collection allowlist", () => { 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 () => { @@ -571,6 +583,7 @@ describe("Export collection allowlist", () => { expect(result.memories.length).toBe(7); expect(result.graphNodes).toBeUndefined(); + expect(result.collectionPagination?.collections).toEqual(["memories"]); expect(result.collectionPagination?.hasMore).toBe(false); }); diff --git a/test/export-incremental-budget.test.ts b/test/export-incremental-budget.test.ts index e7ac00e88c..aeb71f19ad 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) => + sdk.fns.get("api::export")!({ + headers: { authorization: `Bearer ${BEARER}` }, + query_params, + }) as Promise; + + 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/mcp-export-tool.test.ts b/test/mcp-export-tool.test.ts index d0775d648b..534e6eedfe 100644 --- a/test/mcp-export-tool.test.ts +++ b/test/mcp-export-tool.test.ts @@ -5,6 +5,8 @@ vi.mock("../src/logger.js", () => ({ })); 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>(); @@ -150,3 +152,22 @@ describe("memory_export MCP tool", () => { 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 }); + }); +}); From a99475c68c75ffee44ae91182720e6690d27694a Mon Sep 17 00:00:00 2001 From: Dmitrii Zhukov Date: Tue, 13 Oct 2026 12:14:16 +0000 Subject: [PATCH 4/5] fix(import): refuse replace for a page of sessions too replace already refused a collection page or selection, but an export taken with maxSessions that stops short of the last session, or starts past the first, went through and wiped the store down to that page. A window that covers every session is still accepted. Signed-off-by: Dmitrii Zhukov --- src/functions/export-import.ts | 6 +++++- test/export-import.test.ts | 26 ++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/src/functions/export-import.ts b/src/functions/export-import.ts index e5660a43a3..85d682ef10 100644 --- a/src/functions/export-import.ts +++ b/src/functions/export-import.ts @@ -314,7 +314,11 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo error: `Unsupported export version: ${importData.version}`, }; } - if (strategy === "replace" && importData.collectionPagination) { + 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: diff --git a/test/export-import.test.ts b/test/export-import.test.ts index 7e575f6651..b9dbf2b068 100644 --- a/test/export-import.test.ts +++ b/test/export-import.test.ts @@ -499,6 +499,32 @@ describe("Export collection pages and import", () => { 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", { From e1ef98b3a0a3c29405e07e77e4dcf3c1ac3a4152 Mon Sep 17 00:00:00 2001 From: Dmitrii Zhukov Date: Tue, 13 Oct 2026 12:14:16 +0000 Subject: [PATCH 5/5] docs(export): say what each page carries collectionLimit leaves sessions and their observations whole unless collections leaves them out, and access logs come only with memories. Signed-off-by: Dmitrii Zhukov --- README.md | 2 +- src/mcp/tools-registry.ts | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 7cf46a3647..f530eca914 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 | diff --git a/src/mcp/tools-registry.ts b/src/mcp/tools-registry.ts index de4c94f15f..22ffa04715 100644 --- a/src/mcp/tools-registry.ts +++ b/src/mcp/tools-registry.ts @@ -236,7 +236,7 @@ export const CORE_TOOLS: McpToolDef[] = [ 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", + "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", @@ -245,7 +245,7 @@ export const CORE_TOOLS: McpToolDef[] = [ 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. Unknown names are ignored. Omit for everything. A paged or selected export cannot be imported with strategy replace.", + "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.", }, }, },