mcp-memory-keeper 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0] - 2026-06-05
+
+### Added
+
+- **Checkpoints now survive an export → import round trip** (#37, follow-up to #36)
+  - `context_export` writes a new `0.5.0` format that includes the `checkpointItems` and `checkpointFiles` join rows (previously only the bare `checkpoints` rows were exported, which made imported checkpoints empty/useless).
+  - `context_import` restores checkpoints and rewires their links: each checkpoint gets a fresh id, and its item/file links are remapped onto the freshly-imported context-item and file-cache ids. Links pointing at a skipped or absent row are dropped rather than aborting the import. The whole restore happens inside the existing atomic transaction.
+  - The import summary now reports `Checkpoints: N (skipped M malformed), links restored: K`.
+  - **Backward compatible:** importing a pre-`0.5.0` export (no join-row arrays) does not error and reports the checkpoints as not imported, preserving the prior explicit-not-imported behaviour.
+  - The entry-count cap from #36 now also bounds checkpoint and join-row arrays.
+  - **Merge safety:** on a key/path collision during `merge` import, the existing row is now UPDATED in place (its id preserved) instead of `INSERT OR REPLACE`, so a pre-existing checkpoint's links to that row are no longer cascade-deleted. Both `context_items` and `file_cache` (which have UNIQUE constraints) are handled this way.
+  - **Fidelity & observability:** `file_cache.size` is restored on import; duplicate-key/path rows that collapse during import are reported (`collapsed N duplicate-key`); dropped dangling checkpoint links are surfaced (`links restored: K (dropped N dangling)`); and `metadata.totalSize` now accounts for the checkpoint join arrays.
+
 ## [0.13.0] - 2026-06-05
 
 ### Fixed

package/dist/__tests__/e2e/checkpoint-round-trip.test.js

@@ -0,0 +1,303 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const globals_1 = require("@jest/globals");
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+/**
+ * E2E tests for GitHub issue #37: checkpoints (and their checkpoint_items /
+ * checkpoint_files join rows) must survive a context_export -> context_import
+ * round trip.
+ *
+ * Before the fix, exports carried the `checkpoints` rows but not the join rows,
+ * and import restored neither — so a re-imported session lost its checkpoints.
+ * The 0.5.0 export format adds `checkpointItems` / `checkpointFiles`, and import
+ * rewires their foreign keys onto the freshly-generated ids.
+ *
+ * The round-trip test imports into a SEPARATE server instance (its own
+ * DATA_DIR), so the only checkpoint named "cp-roundtrip" is the imported one —
+ * otherwise context_restore_checkpoint (which matches by name across all
+ * checkpoints) could resolve the original source checkpoint and mask a broken
+ * import.
+ *
+ * @see https://github.com/mkreyman/mcp-memory-keeper/issues/37
+ */
+const SERVER_ENTRY = path.join(__dirname, '../../../dist/index.js');
+async function startServer() {
+    const dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'mcp-checkpoint-'));
+    const exportsDir = path.join(dataDir, 'exports');
+    const proc = (0, child_process_1.spawn)('node', [SERVER_ENTRY], {
+        env: { ...process.env, DATA_DIR: dataDir },
+        stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    if (global.testProcesses) {
+        global.testProcesses.push(proc);
+    }
+    // A single persistent reader dispatches each response to its pending request
+    // by id, so concurrent calls cannot share/consume each other's buffer.
+    const pending = new Map();
+    let buffer = '';
+    let nextId = 0;
+    proc.stdout?.on('data', (data) => {
+        buffer += data.toString();
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (msg.id != null && pending.has(msg.id)) {
+                const p = pending.get(msg.id);
+                clearTimeout(p.timer);
+                pending.delete(msg.id);
+                p.resolve(msg);
+            }
+        }
+    });
+    const send = (method, params) => new Promise((resolve, reject) => {
+        const reqId = ++nextId;
+        const timer = setTimeout(() => {
+            pending.delete(reqId);
+            reject(new Error(`Timeout waiting for ${method} (id=${reqId})`));
+        }, 5000);
+        pending.set(reqId, { resolve, timer });
+        proc.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method, params, id: reqId }) + '\n');
+    });
+    const init = await send('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'checkpoint-e2e', version: '1.0.0' },
+    });
+    (0, globals_1.expect)(init.result).toHaveProperty('protocolVersion');
+    proc.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+    await new Promise(resolve => setTimeout(resolve, 150));
+    const call = async (name, args) => {
+        const res = await send('tools/call', { name, arguments: args });
+        return res.result?.content?.[0]?.text ?? JSON.stringify(res);
+    };
+    const close = async () => {
+        for (const p of pending.values())
+            clearTimeout(p.timer);
+        pending.clear();
+        if (!proc.killed) {
+            proc.kill('SIGTERM');
+            await new Promise(resolve => {
+                const t = setTimeout(() => {
+                    proc.kill('SIGKILL');
+                    resolve();
+                }, 3000);
+                proc.on('exit', () => {
+                    clearTimeout(t);
+                    resolve();
+                });
+            });
+            proc.removeAllListeners();
+        }
+        try {
+            fs.rmSync(dataDir, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    };
+    return { proc, dataDir, exportsDir, call, close };
+}
+/** Pull the export file path out of a context_export success message. */
+function parseExportPath(exportText) {
+    const match = exportText.match(/to:\s*(.+?\.json)/);
+    if (!match)
+        throw new Error(`Could not parse export path from: ${exportText}`);
+    return match[1];
+}
+(0, globals_1.describe)('E2E: checkpoint export/import round trip (issue #37)', () => {
+    let server;
+    (0, globals_1.beforeAll)(async () => {
+        server = await startServer();
+    }, 15000);
+    (0, globals_1.afterAll)(async () => {
+        await server?.close();
+    });
+    (0, globals_1.it)('restores a checkpoint and its linked items + files into a clean instance', async () => {
+        // --- Source instance: seed, checkpoint, export ---
+        await server.call('context_session_start', { name: 'cp-source' });
+        await server.call('context_save', { key: 'cp_item_a', value: 'value_a', category: 'task' });
+        await server.call('context_save', { key: 'cp_item_b', value: 'value_b', category: 'note' });
+        await server.call('context_cache_file', {
+            filePath: '/tmp/checkpoint-test.ts',
+            content: 'cached file content',
+        });
+        const cpText = await server.call('context_checkpoint', {
+            name: 'cp-roundtrip',
+            description: 'round trip checkpoint',
+            includeFiles: true,
+            includeGitStatus: false,
+        });
+        (0, globals_1.expect)(cpText).toMatch(/Created checkpoint/i);
+        (0, globals_1.expect)(cpText).toMatch(/Context items:\s*2\b/);
+        const exportText = await server.call('context_export', { confirmEmpty: true });
+        const exportPath = parseExportPath(exportText);
+        const exportBytes = fs.readFileSync(exportPath);
+        // --- Fresh instance: import the file, so the imported checkpoint is the
+        // ONLY one named "cp-roundtrip" (unambiguous restore-by-name). ---
+        const importer = await startServer();
+        try {
+            fs.mkdirSync(importer.exportsDir, { recursive: true });
+            const importFile = path.join(importer.exportsDir, 'incoming.json');
+            fs.writeFileSync(importFile, exportBytes);
+            const importText = await importer.call('context_import', { filePath: 'incoming.json' });
+            (0, globals_1.expect)(importText).toMatch(/Import successful/i);
+            (0, globals_1.expect)(importText).toMatch(/Context items:\s*2\b/);
+            // 2 item links + 1 file link = 3, none dropped.
+            (0, globals_1.expect)(importText).toMatch(/Checkpoints:\s*1, links restored:\s*3$/m);
+            // End-to-end proof: restoring reproduces the items AND the file, which can
+            // only be true if the join rows were rewired onto the freshly-imported
+            // rows in THIS instance.
+            const restoreText = await importer.call('context_restore_checkpoint', {
+                name: 'cp-roundtrip',
+                restoreFiles: true,
+            });
+            (0, globals_1.expect)(restoreText).toMatch(/Successfully restored from checkpoint/i);
+            (0, globals_1.expect)(restoreText).toMatch(/Context items:\s*2\b/);
+            (0, globals_1.expect)(restoreText).toMatch(/Files:\s*1\b/);
+        }
+        finally {
+            await importer.close();
+        }
+    }, 20000);
+    (0, globals_1.it)('reports legacy exports (no checkpointItems) as not imported, without error', async () => {
+        const legacy = path.join(server.exportsDir, 'legacy-export.json');
+        fs.mkdirSync(server.exportsDir, { recursive: true });
+        fs.writeFileSync(legacy, JSON.stringify({
+            version: '0.4.0',
+            session: { name: 'legacy', branch: 'main' },
+            contextItems: [{ id: 'old-1', key: 'legacy_key', value: 'legacy_value' }],
+            fileCache: [],
+            checkpoints: [{ id: 'old-cp', session_id: 'old-sess', name: 'legacy-cp' }],
+            // no checkpointItems / checkpointFiles keys
+        }));
+        try {
+            const text = await server.call('context_import', { filePath: 'legacy-export.json' });
+            (0, globals_1.expect)(text).toMatch(/Import successful/i);
+            (0, globals_1.expect)(text).toMatch(/Context items:\s*1\b/);
+            (0, globals_1.expect)(text).toMatch(/Checkpoints in file:\s*1 \(not imported/i);
+        }
+        finally {
+            fs.rmSync(legacy, { force: true });
+        }
+    });
+    (0, globals_1.it)('drops checkpoint links that point at skipped/absent rows and proves DB state', async () => {
+        // 0.5.0 export with a checkpoint whose item link references an id that is
+        // not present in contextItems — the checkpoint imports, the dangling link is
+        // dropped, and a subsequent restore yields exactly the one valid item.
+        const partial = path.join(server.exportsDir, 'partial-cp.json');
+        fs.mkdirSync(server.exportsDir, { recursive: true });
+        fs.writeFileSync(partial, JSON.stringify({
+            version: '0.5.0',
+            session: { name: 'partial', branch: 'main' },
+            contextItems: [{ id: 'item-1', key: 'k1', value: 'v1' }],
+            fileCache: [],
+            checkpoints: [{ id: 'cp-1', session_id: 's', name: 'partial-cp' }],
+            checkpointItems: [
+                { id: 'l1', checkpoint_id: 'cp-1', context_item_id: 'item-1' }, // valid
+                { id: 'l2', checkpoint_id: 'cp-1', context_item_id: 'missing' }, // dangling
+            ],
+            checkpointFiles: [],
+        }));
+        try {
+            const text = await server.call('context_import', { filePath: 'partial-cp.json' });
+            (0, globals_1.expect)(text).toMatch(/Import successful/i);
+            // 1 checkpoint, only the 1 valid link restored, 1 dangling link dropped.
+            (0, globals_1.expect)(text).toMatch(/Checkpoints:\s*1, links restored:\s*1 \(dropped 1 dangling\)/);
+            // "partial-cp" is unique here, so restore-by-name is unambiguous.
+            const restoreText = await server.call('context_restore_checkpoint', {
+                name: 'partial-cp',
+                restoreFiles: true,
+            });
+            (0, globals_1.expect)(restoreText).toMatch(/Context items:\s*1\b/); // not 2 — dangling link was dropped
+        }
+        finally {
+            fs.rmSync(partial, { force: true });
+        }
+    });
+    (0, globals_1.it)('merge import updates a colliding item in place and preserves a pre-existing checkpoint link', async () => {
+        // Regression guard: a merge import whose item key collides with an existing
+        // row must UPDATE in place (preserving the row id) rather than INSERT OR
+        // REPLACE. REPLACE would cascade-delete the existing checkpoint's link.
+        await server.call('context_session_start', { name: 'merge-target' });
+        await server.call('context_save', { key: 'shared_key', value: 'original', category: 'task' });
+        const cp = await server.call('context_checkpoint', {
+            name: 'pre-merge-cp',
+            includeFiles: false,
+            includeGitStatus: false,
+        });
+        (0, globals_1.expect)(cp).toMatch(/Context items:\s*1\b/);
+        const mergeFile = path.join(server.exportsDir, 'merge-in.json');
+        fs.mkdirSync(server.exportsDir, { recursive: true });
+        fs.writeFileSync(mergeFile, JSON.stringify({
+            version: '0.5.0',
+            session: { name: 'incoming', branch: 'main' },
+            contextItems: [{ id: 'x', key: 'shared_key', value: 'updated' }],
+            fileCache: [],
+            checkpoints: [],
+            checkpointItems: [],
+            checkpointFiles: [],
+        }));
+        try {
+            const imp = await server.call('context_import', { filePath: 'merge-in.json', merge: true });
+            (0, globals_1.expect)(imp).toMatch(/Mode:\s*Merged/);
+            // The colliding item was updated in place (value changed).
+            const got = await server.call('context_get', { key: 'shared_key' });
+            (0, globals_1.expect)(got).toContain('updated');
+            // The pre-existing checkpoint still restores its 1 item — the link
+            // survived because the row id was preserved (no REPLACE-cascade).
+            const restore = await server.call('context_restore_checkpoint', {
+                name: 'pre-merge-cp',
+                restoreFiles: false,
+            });
+            (0, globals_1.expect)(restore).toMatch(/Context items:\s*1\b/);
+        }
+        finally {
+            fs.rmSync(mergeFile, { force: true });
+        }
+    });
+});

package/dist/index.js

@@ -145,6 +145,80 @@ function resolveConfinedImportPath(filePath) {
     }
     return resolved;
 }
+/**
+ * Restore checkpoints and their checkpoint_items / checkpoint_files join rows
+ * from a 0.5.0+ import payload. MUST be called inside the import transaction so
+ * its inserts are atomic with the rest of the import.
+ *
+ * Each checkpoint gets a fresh id; join rows are rewired onto the new item/file
+ * ids via the supplied maps. Malformed checkpoints are skipped, and links
+ * pointing at a skipped or absent row are dropped (never inserted — that would
+ * violate a foreign key).
+ */
+function restoreImportedCheckpoints(db, targetSessionId, checkpointEntries, checkpointItemEntries, checkpointFileEntries, itemIdMap, fileIdMap) {
+    let checkpointCount = 0;
+    let skippedCheckpoints = 0;
+    let checkpointLinkCount = 0;
+    let droppedCheckpointLinks = 0;
+    const checkpointIdMap = new Map();
+    const cpStmt = db.prepare(`
+    INSERT INTO checkpoints (id, session_id, name, description, metadata, git_status, git_branch, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+    for (const entry of checkpointEntries) {
+        const cp = entry;
+        if (typeof cp !== 'object' ||
+            cp === null ||
+            typeof cp.id !== 'string' ||
+            typeof cp.name !== 'string') {
+            skippedCheckpoints++;
+            continue;
+        }
+        const newCpId = (0, uuid_1.v4)();
+        checkpointIdMap.set(cp.id, newCpId);
+        cpStmt.run(newCpId, targetSessionId, cp.name, typeof cp.description === 'string' ? cp.description : null, typeof cp.metadata === 'string' ? cp.metadata : null, typeof cp.git_status === 'string' ? cp.git_status : null, typeof cp.git_branch === 'string' ? cp.git_branch : null, typeof cp.created_at === 'string' ? cp.created_at : new Date().toISOString());
+        checkpointCount++;
+    }
+    const cpiStmt = db.prepare('INSERT INTO checkpoint_items (id, checkpoint_id, context_item_id) VALUES (?, ?, ?)');
+    for (const entry of checkpointItemEntries) {
+        const link = entry;
+        if (typeof link !== 'object' ||
+            link === null ||
+            typeof link.checkpoint_id !== 'string' ||
+            typeof link.context_item_id !== 'string') {
+            droppedCheckpointLinks++;
+            continue;
+        }
+        const newCpId = checkpointIdMap.get(link.checkpoint_id);
+        const newItemId = itemIdMap.get(link.context_item_id);
+        if (!newCpId || !newItemId) {
+            droppedCheckpointLinks++;
+            continue;
+        }
+        cpiStmt.run((0, uuid_1.v4)(), newCpId, newItemId);
+        checkpointLinkCount++;
+    }
+    const cpfStmt = db.prepare('INSERT INTO checkpoint_files (id, checkpoint_id, file_cache_id) VALUES (?, ?, ?)');
+    for (const entry of checkpointFileEntries) {
+        const link = entry;
+        if (typeof link !== 'object' ||
+            link === null ||
+            typeof link.checkpoint_id !== 'string' ||
+            typeof link.file_cache_id !== 'string') {
+            droppedCheckpointLinks++;
+            continue;
+        }
+        const newCpId = checkpointIdMap.get(link.checkpoint_id);
+        const newFileId = fileIdMap.get(link.file_cache_id);
+        if (!newCpId || !newFileId) {
+            droppedCheckpointLinks++;
+            continue;
+        }
+        cpfStmt.run((0, uuid_1.v4)(), newCpId, newFileId);
+        checkpointLinkCount++;
+    }
+    return { checkpointCount, skippedCheckpoints, checkpointLinkCount, droppedCheckpointLinks };
+}
 // Warn users whose legacy DB is sitting in CWD
 const legacyDb = path.join(process.cwd(), 'context.db');
 if (process.cwd() !== dataDir && fs.existsSync(legacyDb)) {
@@ -1409,6 +1483,19 @@ Checkpoint: ${autoSave ? `git-commit-${new Date().toISOString()}` : 'None'}`,
             const checkpoints = db
                 .prepare('SELECT * FROM checkpoints WHERE session_id = ?')
                 .all(targetSessionId);
+            // The join rows that link a checkpoint to the context items / files it
+            // captured. Without these, an imported checkpoint would be empty, so they
+            // are part of the export payload (format version 0.5.0+).
+            const checkpointItems = db
+                .prepare(`SELECT cpi.* FROM checkpoint_items cpi
+           JOIN checkpoints cp ON cpi.checkpoint_id = cp.id
+           WHERE cp.session_id = ?`)
+                .all(targetSessionId);
+            const checkpointFiles = db
+                .prepare(`SELECT cpf.* FROM checkpoint_files cpf
+           JOIN checkpoints cp ON cpf.checkpoint_id = cp.id
+           WHERE cp.session_id = ?`)
+                .all(targetSessionId);
             // Check if session is empty
             const isEmpty = contextItems.length === 0 && fileCache.length === 0 && checkpoints.length === 0;
             if (isEmpty && !confirmEmpty) {
@@ -1424,17 +1511,28 @@ Checkpoint: ${autoSave ? `git-commit-${new Date().toISOString()}` : 'None'}`,
                 };
             }
             const exportData = {
-                version: '0.4.0',
+                // 0.5.0 added checkpointItems / checkpointFiles so checkpoints survive
+                // a round trip. Older importers ignore the new keys; newer importers
+                // treat their absence as "legacy export, checkpoints not importable".
+                version: '0.5.0',
                 exported: new Date().toISOString(),
                 session,
                 contextItems,
                 fileCache,
                 checkpoints,
+                checkpointItems,
+                checkpointFiles,
                 metadata: {
                     itemCount: contextItems.length,
                     fileCount: fileCache.length,
                     checkpointCount: checkpoints.length,
-                    totalSize: JSON.stringify({ contextItems, fileCache, checkpoints }).length,
+                    totalSize: JSON.stringify({
+                        contextItems,
+                        fileCache,
+                        checkpoints,
+                        checkpointItems,
+                        checkpointFiles,
+                    }).length,
                 },
             };
             if (format === 'json') {
@@ -1552,10 +1650,28 @@ Files: ${stats.files}`) + sizeWarning,
             // fall back to creating a new session (and report that honestly).
             const merged = merge && !!currentSessionId;
             const fileCacheEntries = Array.isArray(importData.fileCache) ? importData.fileCache : [];
+            const checkpointEntries = Array.isArray(importData.checkpoints) ? importData.checkpoints : [];
+            const checkpointItemEntries = Array.isArray(importData.checkpointItems)
+                ? importData.checkpointItems
+                : [];
+            const checkpointFileEntries = Array.isArray(importData.checkpointFiles)
+                ? importData.checkpointFiles
+                : [];
+            // Presence of the checkpointItems key marks a 0.5.0+ export that carries
+            // the join rows needed to restore checkpoints faithfully. Older exports
+            // lack it, so their checkpoints are reported as not imported.
+            const checkpointFormatSupported = Array.isArray(importData.checkpointItems);
             // Bound the work before opening the (synchronous, event-loop-blocking)
-            // transaction so a huge row count cannot stall the server.
+            // transaction so a huge row count cannot stall the server. The cap is
+            // per-array on purpose: checkpoint_items legitimately scales as
+            // (checkpoints × items), so it routinely exceeds the item count, and an
+            // aggregate sum cap would reject valid many-checkpoint sessions. The
+            // 50 MB MAX_IMPORT_BYTES cap bounds the total payload independently.
             if (importData.contextItems.length > MAX_IMPORT_ITEMS ||
-                fileCacheEntries.length > MAX_IMPORT_ITEMS) {
+                fileCacheEntries.length > MAX_IMPORT_ITEMS ||
+                checkpointEntries.length > MAX_IMPORT_ITEMS ||
+                checkpointItemEntries.length > MAX_IMPORT_ITEMS ||
+                checkpointFileEntries.length > MAX_IMPORT_ITEMS) {
                 return {
                     content: [
                         {
@@ -1586,14 +1702,37 @@ Files: ${stats.files}`) + sizeWarning,
               VALUES (?, ?, ?, ?, ?, ?)
             `).run(targetSessionId, `Imported: ${importedSession.name}`, `Imported from ${safePath} on ${new Date().toISOString()}`, typeof importedSession.branch === 'string' ? importedSession.branch : null, null, new Date().toISOString());
                     }
-                    // Import context items. Restore the channel/is_private/metadata columns
-                    // too so a round trip is faithful, not lossy.
-                    const itemStmt = db.prepare(`
-            INSERT OR REPLACE INTO context_items (id, session_id, key, value, category, priority, size, metadata, is_private, channel, created_at, updated_at)
+                    // Import context items, restoring channel/is_private/metadata so the
+                    // round trip is faithful. On a key collision we UPDATE the existing row
+                    // in place (preserving its id) rather than INSERT OR REPLACE: REPLACE
+                    // would delete the row and ON DELETE CASCADE would silently strip a
+                    // pre-existing checkpoint's link to it. Preserving the id keeps links.
+                    const insertItemStmt = db.prepare(`
+            INSERT INTO context_items (id, session_id, key, value, category, priority, size, metadata, is_private, channel, created_at, updated_at)
             VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
           `);
-                    let itemCount = 0;
+                    const findItemStmt = db.prepare('SELECT id FROM context_items WHERE session_id = ? AND key = ?');
+                    const updateItemStmt = db.prepare(`
+            UPDATE context_items
+            SET value = ?, category = ?, priority = ?, size = ?, metadata = ?, is_private = ?, channel = ?, updated_at = CURRENT_TIMESTAMP
+            WHERE id = ?
+          `);
+                    // Map each exported row's id to the new id we generate, so checkpoint
+                    // join rows can be rewired onto the freshly-imported items/files.
+                    const itemIdMap = new Map();
+                    const fileIdMap = new Map();
+                    // De-duplicate by the natural key (session_id is implied) BEFORE
+                    // inserting. context_items has UNIQUE(session_id, key), so two exported
+                    // items sharing a key would otherwise INSERT OR REPLACE-collapse — the
+                    // first row (still in itemIdMap) would be deleted, leaving the map
+                    // pointing at a row that no longer exists and making a later
+                    // checkpoint_items insert throw an FK error that aborts the whole
+                    // import. Keeping the last occurrence matches INSERT OR REPLACE
+                    // semantics; every exported id for that key is mapped to the survivor.
                     let skippedItems = 0;
+                    let validItems = 0;
+                    const itemsByKey = new Map();
+                    const itemOldIdsByKey = new Map();
                     for (const item of importData.contextItems) {
                         // Skip entries that are not well-formed items rather than letting a
                         // bad row abort the whole transaction with a SQLite binding error.
@@ -1604,22 +1743,66 @@ Files: ${stats.files}`) + sizeWarning,
                             skippedItems++;
                             continue;
                         }
-                        itemStmt.run((0, uuid_1.v4)(), targetSessionId, item.key, item.value, typeof item.category === 'string' ? item.category : null, typeof item.priority === 'string' ? item.priority : null, 
+                        validItems++;
+                        itemsByKey.set(item.key, item);
+                        const oldIds = itemOldIdsByKey.get(item.key) ?? [];
+                        if (typeof item.id === 'string') {
+                            oldIds.push(item.id);
+                        }
+                        itemOldIdsByKey.set(item.key, oldIds);
+                    }
+                    // Valid rows that collapsed onto an earlier duplicate key.
+                    const collapsedItems = validItems - itemsByKey.size;
+                    let itemCount = 0;
+                    for (const [key, item] of itemsByKey) {
+                        const value = item.value;
+                        const category = typeof item.category === 'string' ? item.category : null;
+                        const priority = typeof item.priority === 'string' ? item.priority : null;
                         // Use the stored size only when it is a valid non-negative number;
                         // `|| calculateSize(...)` would wrongly recompute a legitimate 0.
-                        typeof item.size === 'number' && item.size >= 0
-                            ? item.size
-                            : calculateSize(item.value), typeof item.metadata === 'string' ? item.metadata : null, typeof item.is_private === 'number' ? item.is_private : 0, typeof item.channel === 'string' ? item.channel : 'general', typeof item.created_at === 'string' ? item.created_at : new Date().toISOString());
+                        const size = typeof item.size === 'number' && item.size >= 0 ? item.size : calculateSize(value);
+                        const metadata = typeof item.metadata === 'string' ? item.metadata : null;
+                        const isPrivate = typeof item.is_private === 'number' ? item.is_private : 0;
+                        const channel = typeof item.channel === 'string' ? item.channel : 'general';
+                        // In merge mode, reuse the existing row id on a key collision so its
+                        // existing checkpoint links are preserved (no REPLACE-cascade).
+                        const existing = merged
+                            ? findItemStmt.get(targetSessionId, key)
+                            : undefined;
+                        let targetItemId;
+                        if (existing) {
+                            targetItemId = existing.id;
+                            updateItemStmt.run(value, category, priority, size, metadata, isPrivate, channel, targetItemId);
+                        }
+                        else {
+                            targetItemId = (0, uuid_1.v4)();
+                            insertItemStmt.run(targetItemId, targetSessionId, key, value, category, priority, size, metadata, isPrivate, channel, typeof item.created_at === 'string' ? item.created_at : new Date().toISOString());
+                        }
+                        for (const oldId of itemOldIdsByKey.get(key) ?? []) {
+                            itemIdMap.set(oldId, targetItemId);
+                        }
                         itemCount++;
                     }
                     // Import file cache. content is a nullable column, so null is valid and
                     // must NOT be treated as a malformed row (that would drop legit rows).
-                    const fileStmt = db.prepare(`
-            INSERT OR REPLACE INTO file_cache (id, session_id, file_path, content, hash, last_read)
-            VALUES (?, ?, ?, ?, ?, ?)
+                    // size is restored too so the round trip is faithful. Like context
+                    // items, file_cache has UNIQUE(session_id, file_path); de-duplicate by
+                    // file_path and UPDATE-in-place on collision (preserving the id, hence
+                    // any pre-existing checkpoint_files link) rather than INSERT OR REPLACE.
+                    const insertFileStmt = db.prepare(`
+            INSERT INTO file_cache (id, session_id, file_path, content, hash, size, last_read)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+          `);
+                    const findFileStmt = db.prepare('SELECT id FROM file_cache WHERE session_id = ? AND file_path = ?');
+                    const updateFileStmt = db.prepare(`
+            UPDATE file_cache
+            SET content = ?, hash = ?, size = ?, last_read = ?, updated_at = CURRENT_TIMESTAMP
+            WHERE id = ?
           `);
-                    let fileCount = 0;
                     let skippedFiles = 0;
+                    let validFiles = 0;
+                    const filesByPath = new Map();
+                    const fileOldIdsByPath = new Map();
                     for (const file of fileCacheEntries) {
                         if (typeof file !== 'object' ||
                             file === null ||
@@ -1628,10 +1811,66 @@ Files: ${stats.files}`) + sizeWarning,
                             skippedFiles++;
                             continue;
                         }
-                        fileStmt.run((0, uuid_1.v4)(), targetSessionId, file.file_path, file.content ?? null, typeof file.hash === 'string' ? file.hash : null, typeof file.last_read === 'string' ? file.last_read : null);
+                        validFiles++;
+                        filesByPath.set(file.file_path, file);
+                        const oldIds = fileOldIdsByPath.get(file.file_path) ?? [];
+                        if (typeof file.id === 'string') {
+                            oldIds.push(file.id);
+                        }
+                        fileOldIdsByPath.set(file.file_path, oldIds);
+                    }
+                    const collapsedFiles = validFiles - filesByPath.size;
+                    let fileCount = 0;
+                    for (const [filePath, file] of filesByPath) {
+                        const content = file.content ?? null;
+                        const hash = typeof file.hash === 'string' ? file.hash : null;
+                        const size = typeof file.size === 'number' && file.size >= 0
+                            ? file.size
+                            : typeof content === 'string'
+                                ? calculateSize(content)
+                                : 0;
+                        const lastRead = typeof file.last_read === 'string' ? file.last_read : null;
+                        const existing = merged
+                            ? findFileStmt.get(targetSessionId, filePath)
+                            : undefined;
+                        let targetFileId;
+                        if (existing) {
+                            targetFileId = existing.id;
+                            updateFileStmt.run(content, hash, size, lastRead, targetFileId);
+                        }
+                        else {
+                            targetFileId = (0, uuid_1.v4)();
+                            insertFileStmt.run(targetFileId, targetSessionId, filePath, content, hash, size, lastRead);
+                        }
+                        for (const oldId of fileOldIdsByPath.get(filePath) ?? []) {
+                            fileIdMap.set(oldId, targetFileId);
+                        }
                         fileCount++;
                     }
-                    return { targetSessionId, createdNew, itemCount, fileCount, skippedItems, skippedFiles };
+                    // Restore checkpoints + their links (0.5.0+ exports only), within this
+                    // same transaction. Extracted to a helper to keep the handler readable.
+                    const cp = checkpointFormatSupported
+                        ? restoreImportedCheckpoints(db, targetSessionId, checkpointEntries, checkpointItemEntries, checkpointFileEntries, itemIdMap, fileIdMap)
+                        : {
+                            checkpointCount: 0,
+                            skippedCheckpoints: 0,
+                            checkpointLinkCount: 0,
+                            droppedCheckpointLinks: 0,
+                        };
+                    return {
+                        targetSessionId,
+                        createdNew,
+                        itemCount,
+                        fileCount,
+                        skippedItems,
+                        skippedFiles,
+                        checkpointCount: cp.checkpointCount,
+                        skippedCheckpoints: cp.skippedCheckpoints,
+                        checkpointLinkCount: cp.checkpointLinkCount,
+                        droppedCheckpointLinks: cp.droppedCheckpointLinks,
+                        collapsedItems,
+                        collapsedFiles,
+                    };
                 });
                 const result = runImport();
                 // Publish the new current session only after a successful commit.
@@ -1641,17 +1880,25 @@ Files: ${stats.files}`) + sizeWarning,
                 const lines = [
                     'Import successful!',
                     `Session: ${result.targetSessionId.substring(0, 8)}`,
-                    `Context items: ${result.itemCount}${result.skippedItems ? ` (skipped ${result.skippedItems} malformed)` : ''}`,
-                    `Files: ${result.fileCount}${result.skippedFiles ? ` (skipped ${result.skippedFiles} malformed)` : ''}`,
+                    `Context items: ${result.itemCount}${result.skippedItems ? ` (skipped ${result.skippedItems} malformed)` : ''}${result.collapsedItems ? ` (collapsed ${result.collapsedItems} duplicate-key)` : ''}`,
+                    `Files: ${result.fileCount}${result.skippedFiles ? ` (skipped ${result.skippedFiles} malformed)` : ''}${result.collapsedFiles ? ` (collapsed ${result.collapsedFiles} duplicate-path)` : ''}`,
                     `Mode: ${result.createdNew ? 'New session' : 'Merged'}`,
                 ];
-                // Checkpoints are present in exports but not restored by import; say so
-                // explicitly instead of silently dropping them.
-                const checkpointCount = Array.isArray(importData.checkpoints)
-                    ? importData.checkpoints.length
-                    : 0;
-                if (checkpointCount > 0) {
-                    lines.push(`Checkpoints in file: ${checkpointCount} (not imported)`);
+                // Report checkpoints: restored for 0.5.0+ exports, or flagged as not
+                // imported for legacy exports that lack the join rows.
+                if (checkpointFormatSupported) {
+                    if (result.checkpointCount > 0 || checkpointEntries.length > 0) {
+                        const skipNote = result.skippedCheckpoints
+                            ? ` (skipped ${result.skippedCheckpoints} malformed)`
+                            : '';
+                        const dropNote = result.droppedCheckpointLinks
+                            ? ` (dropped ${result.droppedCheckpointLinks} dangling)`
+                            : '';
+                        lines.push(`Checkpoints: ${result.checkpointCount}${skipNote}, links restored: ${result.checkpointLinkCount}${dropNote}`);
+                    }
+                }
+                else if (checkpointEntries.length > 0) {
+                    lines.push(`Checkpoints in file: ${checkpointEntries.length} (not imported — this export predates checkpoint support and does not carry the item/file links)`);
                 }
                 // Warn when the caller asked to merge but there was no active session.
                 if (merge && !merged) {
@@ -3856,7 +4103,8 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
         // Phase 3: Export/Import
         {
             name: 'context_export',
-            description: 'Export session data for backup or sharing. JSON exports are written to the ' +
+            description: 'Export session data (context items, cached files, and checkpoints with their ' +
+                'links) for backup or sharing. JSON exports are written to the ' +
                 "server's exports directory (<DATA_DIR>/exports, overridable via MEMORY_KEEPER_EXPORT_DIR); " +
                 'the response includes the full path, which can be passed back to context_import.',
             inputSchema: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-memory-keeper",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "MCP server for persistent context management in AI coding assistants",
   "main": "dist/index.js",
   "bin": {