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
6 changes: 6 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,12 @@ Auto-forget and retention release a Memory's image reference after its indexed d
A failed release is logged without blocking deletion bookkeeping; it may leave an unused image.
Concurrent deletion locking is outside this contract.

### Replace import
`mem::import` validates section shapes, size limits and keyed fields used by import indexing
before any store mutation. Rows without string keys are dropped and counted in `invalid`, so
legacy keyless Session stubs do not prevent restoring the rest. Access logs and legacy Memory
session IDs retain their normal normalization. This preflight does not make replacement transactional.

### Graph Eviction
Every path that hard-deletes Observations or Memories (`mem::evict`, `mem::observe` session-cap
eviction, `mem::auto-forget`, `mem::forget`, `mem::retention-evict`, `mem::governance-delete`,
Expand Down
123 changes: 113 additions & 10 deletions src/functions/export-import.ts
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,113 @@ function nonEmpty<T>(rows: T[] | undefined): T[] | undefined {
return rows && rows.length > 0 ? rows : undefined;
}

const MAX_ACCESS_LOGS = 50_000;

const KEYED_SECTIONS = [
["sessions", "id"],
["memories", "id"],
["summaries", "sessionId"],
["graphNodes", "id"],
["graphEdges", "id"],
["semanticMemories", "id"],
["proceduralMemories", "id"],
["profiles", "project"],
["signals", "id"],
["facets", "id"],
["lessons", "id"],
["insights", "id"],
] as const;

function isKeyedRow(row: unknown, key: string): boolean {
return (
typeof row === "object" &&
row !== null &&
typeof (row as Record<string, unknown>)[key] === "string"
);
}

// A replace import deletes every store before it writes, so a malformed
// section must fail first, leaving the store untouched.
function invalidImportSection(importData: ExportData): string | null {
for (const [section] of KEYED_SECTIONS) {
const rows: unknown = importData[section];
if (rows != null && !Array.isArray(rows)) return `${section} must be an array`;
}
const accessLogs: unknown = importData.accessLogs;
if (accessLogs != null && !Array.isArray(accessLogs)) return "accessLogs must be an array";
if (Array.isArray(accessLogs) && accessLogs.length > MAX_ACCESS_LOGS) {
return `Too many access logs (max ${MAX_ACCESS_LOGS})`;
}
return null;
}

// A row without its key cannot be written (SQLite refuses an undefined key),
// so it is dropped rather than failing the import part way through.
function dropUnkeyedRows(importData: ExportData): number {
let dropped = 0;
const keep = <T>(rows: T[], key: string): T[] => {
const kept = rows.filter((row) => isKeyedRow(row, key));
dropped += rows.length - kept.length;
return kept;
};
const sections = importData as unknown as Record<string, unknown[] | undefined>;
for (const [section, key] of KEYED_SECTIONS) {
const rows = sections[section];
if (rows) sections[section] = keep(rows, key);
}
for (const [sessionId, rows] of Object.entries(importData.observations)) {
importData.observations[sessionId] = keep(rows, "id");
}
if (importData.accessLogs) {
const kept = importData.accessLogs.filter((row) => typeof row === "object" && row !== null);
dropped += importData.accessLogs.length - kept.length;
importData.accessLogs = kept;
}
return dropped;
}

function invalidImportRow(data: ExportData): string | null {
const strings = (value: unknown) => Array.isArray(value) && value.every((item) => typeof item === "string");
const optionalString = (value: unknown) => value == null || typeof value === "string";
const checkIndexFields = (row: Record<string, unknown>, fields: string[]): boolean =>
fields.every((field) => strings(row[field]));

for (const memory of data.memories) {
if (!isKeyedRow(memory, "id")) continue;
if (Array.isArray(memory.sessionIds) && !strings(memory.sessionIds)) return "memories.sessionIds must contain strings";
if (memory.isLatest === false || !memory.title || !memory.content) continue;
if (typeof memory.title !== "string" || typeof memory.content !== "string" ||
!optionalString(memory.createdAt) || !checkIndexFields(memory as unknown as Record<string, unknown>, ["concepts", "files"])) {
return "memories contain invalid indexing fields";
}
}
for (const rows of Object.values(data.observations)) {
for (const obs of rows) {
if (!isKeyedRow(obs, "id") || !obs.title || !obs.narrative) continue;
if (typeof obs.title !== "string" || typeof obs.narrative !== "string" ||
!optionalString(obs.sessionId) || !optionalString(obs.timestamp) ||
!optionalString(obs.subtitle) || !optionalString(obs.userPrompt) ||
!checkIndexFields(obs as unknown as Record<string, unknown>, ["facts", "concepts", "files"])) {
return "observations contain invalid indexing fields";
}
}
}
for (const node of data.graphNodes ?? []) {
if (!isKeyedRow(node, "id")) continue;
if (!optionalString(node.name) || (node.sourceObservationIds != null && !strings(node.sourceObservationIds))) {
return "graphNodes contain invalid indexing fields";
}
}
for (const edge of data.graphEdges ?? []) {
if (!isKeyedRow(edge, "id")) continue;
if (!optionalString(edge.sourceNodeId) || !optionalString(edge.targetNodeId) ||
(edge.sourceObservationIds != null && !strings(edge.sourceObservationIds))) {
return "graphEdges contain invalid indexing fields";
}
}
return null;
}

function oversizedExport(bytes: number): OversizedPayload {
return {
success: false,
Expand Down Expand Up @@ -235,7 +342,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
const MAX_SUMMARIES = 10_000;
const MAX_OBS_PER_SESSION = 5_000;
const MAX_TOTAL_OBSERVATIONS = 500_000;
const MAX_ACCESS_LOGS = 50_000;

if (!Array.isArray(importData.sessions)) {
return { success: false, error: "sessions must be an array" };
Expand Down Expand Up @@ -300,13 +406,19 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
error: `Too many total observations (max ${MAX_TOTAL_OBSERVATIONS})`,
};
}
const invalidSection = invalidImportSection(importData);
if (invalidSection) return { success: false, error: invalidSection };
const invalidRow = invalidImportRow(importData);
if (invalidRow) return { success: false, error: invalidRow };
const invalid = dropUnkeyedRows(importData);

const stats = {
sessions: 0,
observations: 0,
memories: 0,
summaries: 0,
skipped: 0,
invalid,
};

if (strategy === "replace") {
Expand Down Expand Up @@ -553,15 +665,6 @@ export function registerExportImportFunction(sdk: ISdk, kv: StateKV): void {
});
}
if (importData.accessLogs) {
if (!Array.isArray(importData.accessLogs)) {
return { success: false, error: "accessLogs must be an array" };
}
if (importData.accessLogs.length > MAX_ACCESS_LOGS) {
return {
success: false,
error: `Too many access logs (max ${MAX_ACCESS_LOGS})`,
};
}
const memoryIds = new Set<string>(
importData.memories.map((m) => m.id),
);
Expand Down
81 changes: 81 additions & 0 deletions test/export-import.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -412,4 +412,85 @@ describe("Export/Import Functions", () => {
expect(result.success).toBe(false);
expect(result.error).toContain("Unsupported export version");
});

describe("replace leaves the store untouched when the file is invalid (#436)", () => {
const base = (): ExportData => ({
version: VERSION,
exportedAt: "2026-03-01T00:00:00Z",
sessions: [],
observations: {},
memories: [],
summaries: [],
});

it.each([
["accessLogs is not an array", { accessLogs: {} }],
["lessons is not an array", { lessons: {} }],
["insights is not an array", { insights: "x" }],
["accessLogs exceeds its limit", { accessLogs: Array(50_001).fill({}) }],
["memory content is not text", { memories: [{ ...testMemory, content: 42 }] }],
["memory concepts contain a non-string", { memories: [{ ...testMemory, concepts: [null] }] }],
["memory sessionIds contain a non-string", { memories: [{ ...testMemory, sessionIds: [3] }] }],
["observation facts are not an array", { observations: { ses_2: [{ ...testObs, facts: {} }] } }],
["observation narrative is not text", { observations: { ses_2: [{ ...testObs, narrative: 42 }] } }],
["graph node provenance is malformed", { graphNodes: [{ id: "node", name: "Node", sourceObservationIds: [3] }] }],
["graph edge endpoint is malformed", { graphEdges: [{ id: "edge", sourceNodeId: {}, targetNodeId: "node" }] }],
])("%s", async (_label, patch) => {
const result = (await sdk.trigger("mem::import", {
exportData: { ...base(), ...patch },
strategy: "replace",
})) as { success: boolean; error?: string };

expect(result.success).toBe(false);
expect(await kv.get("mem:sessions", "ses_1")).toEqual(testSession);
expect(await kv.get("mem:obs:ses_1", "obs_1")).not.toBeNull();
expect(await kv.get("mem:memories", "mem_1")).not.toBeNull();
expect(await kv.get("mem:summaries", "ses_1")).toEqual(testSummary);
});

it.each(["merge", "skip"] as const)("validates before writes with %s", async (strategy) => {
const result = await sdk.trigger("mem::import", {
exportData: { ...base(), sessions: [{ ...testSession, id: "new" }], memories: [{ ...testMemory, files: 5 }] },
strategy,
});
expect(result).toMatchObject({ success: false });
expect(await kv.get("mem:sessions", "new")).toBeNull();
expect(await kv.get("mem:memories", "mem_1")).toEqual(testMemory);
});

it.each(["merge", "skip", "replace"] as const)("keeps legacy normalization with %s", async (strategy) => {
const result = await sdk.trigger("mem::import", {
exportData: {
...base(),
sessions: [{ status: "completed" }],
memories: [{ ...testMemory, id: "legacy", sessionIds: "old" }],
accessLogs: [{ memoryId: "legacy", count: "old", recent: [1, "old"] }],
},
strategy,
});
expect(result).toMatchObject({ success: true, invalid: 1 });
expect(await kv.get("mem:memories", "legacy")).toMatchObject({ sessionIds: [] });
expect(await kv.get("mem:access", "legacy")).toMatchObject({ count: 1, recent: [1] });
});

it("drops rows without their key and restores the rest", async () => {
const keyless = { endedAt: "2026-09-22T01:02:26.889Z", status: "completed" };
const result = (await sdk.trigger("mem::import", {
exportData: {
...base(),
sessions: [keyless, { ...testSession, id: "ses_2" }],
observations: { ses_2: ["oops", { ...testObs, id: "obs_2", sessionId: "ses_2" }] },
memories: [null, { ...testMemory, id: "mem_2" }],
lessons: [{ content: "no id" }],
},
strategy: "replace",
})) as { success: boolean; invalid: number; sessions: number };

expect(result).toMatchObject({ success: true, invalid: 4, sessions: 1 });
expect(await kv.get("mem:sessions", "ses_1")).toBeNull();
expect(await kv.get("mem:sessions", "ses_2")).not.toBeNull();
expect(await kv.get("mem:obs:ses_2", "obs_2")).not.toBeNull();
expect(await kv.get("mem:memories", "mem_2")).not.toBeNull();
});
});
});