Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion plugin/skills/agentmemory-mcp-tools/REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down
101 changes: 95 additions & 6 deletions src/functions/export-import.ts
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,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],
Expand All @@ -89,6 +89,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;

Expand All @@ -106,12 +123,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) => {
Expand All @@ -128,15 +173,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[]> = {};
Expand All @@ -161,9 +210,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;
Expand All @@ -189,6 +249,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", {
Expand All @@ -207,6 +284,7 @@ export function registerExportImportFunction(sdk: IIIClient, state: StateKV): vo
observations: totalObs,
memories: memories.length,
summaries: summaries.length,
collections: selection && [...selection],
});

return exportData;
Expand Down Expand Up @@ -236,6 +314,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;
Expand Down
20 changes: 19 additions & 1 deletion src/mcp/server.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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: {
Expand Down
17 changes: 15 additions & 2 deletions src/mcp/standalone.ts
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,7 @@ interface Validated {
includeLessons?: boolean;
memoryIds?: string[];
reason?: string;
exportQuery?: string;
sessionQuery?: Record<string, string>;
}

Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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 (
Expand Down
28 changes: 26 additions & 2 deletions src/mcp/tools-registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
22 changes: 21 additions & 1 deletion src/triggers/api.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1940,9 +1940,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;
Expand All @@ -1951,6 +1960,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,
Expand Down
9 changes: 9 additions & 0 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,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;
Expand All @@ -385,6 +393,7 @@ export interface ExportData {
insights?: Insight[];
accessLogs?: AccessLogExport[];
pagination?: ExportPagination;
collectionPagination?: ExportCollectionPagination;
}

export interface AccessLogExport {
Expand Down
Loading
Loading