mcp-memory-keeper 0.12.2 → 0.14.0

package/dist/index.js

@@ -69,6 +69,156 @@ catch (err) {
         `Set DATA_DIR to a writable location or create the directory manually.`);
     process.exit(1);
 }
+// Server-owned directory for session exports/imports. Both context_export
+// (writes) and context_import (reads) are confined to this directory so that
+// context_import can never be steered at an arbitrary file on disk. Override
+// with MEMORY_KEEPER_EXPORT_DIR; defaults to a subdirectory of the data dir.
+const exportsDir = process.env.MEMORY_KEEPER_EXPORT_DIR
+    ? path.resolve(process.env.MEMORY_KEEPER_EXPORT_DIR)
+    : path.join(dataDir, 'exports');
+try {
+    fs.mkdirSync(exportsDir, { recursive: true });
+}
+catch (err) {
+    console.error(`[memory-keeper] FATAL: Cannot create exports directory "${exportsDir}": ${err.message}\n` +
+        `Set MEMORY_KEEPER_EXPORT_DIR to a writable location or create the directory manually.`);
+    process.exit(1);
+}
+// Resolve symlinks once so confinement checks compare real paths on both sides.
+let exportsDirReal;
+try {
+    exportsDirReal = fs.realpathSync(exportsDir);
+}
+catch (err) {
+    console.error(`[memory-keeper] FATAL: Cannot resolve exports directory "${exportsDir}": ${err.message}\n` +
+        `Set MEMORY_KEEPER_EXPORT_DIR to a readable location or create the directory manually.`);
+    process.exit(1);
+}
+// Upper bound on the size of a file context_import will read into memory. The
+// exports directory is server-owned, but context_export can write arbitrarily
+// large session dumps there, so cap the read to avoid memory exhaustion.
+const MAX_IMPORT_BYTES = 50 * 1024 * 1024;
+// Upper bound on how many context items / file-cache entries a single import
+// will process. better-sqlite3 transactions run synchronously and block the
+// event loop, so an export crafted with millions of tiny rows (still under the
+// byte cap) must not be allowed to stall the server.
+const MAX_IMPORT_ITEMS = 100_000;
+/**
+ * Resolve a caller-supplied import path and confine it to the exports
+ * directory. Relative paths are resolved against the exports directory;
+ * absolute paths are accepted only if they resolve (after following symlinks)
+ * to a location inside the exports directory.
+ *
+ * Throws an Error whose message is safe to surface to the caller — it never
+ * contains any bytes read from the target file.
+ */
+function resolveConfinedImportPath(filePath) {
+    if (typeof filePath !== 'string' || filePath.length === 0) {
+        throw new Error('filePath is required and must be a non-empty string');
+    }
+    // Resolve relative paths against the exports directory; leave absolute as-is.
+    const candidate = path.resolve(exportsDirReal, filePath);
+    // realpathSync follows symlinks and requires the file to exist; an attacker
+    // cannot use a symlink inside the exports dir to escape it. statSync on the
+    // resolved path then tells us it is a regular file of acceptable size.
+    let resolved;
+    let stats;
+    try {
+        resolved = fs.realpathSync(candidate);
+        stats = fs.statSync(resolved);
+    }
+    catch {
+        throw new Error('import file not found in the exports directory');
+    }
+    // Use the SAME message as the not-found case so a file that exists outside
+    // the exports directory is indistinguishable from a missing one (no
+    // existence oracle), and never echo the resolved absolute path.
+    const withinExports = resolved === exportsDirReal || resolved.startsWith(exportsDirReal + path.sep);
+    if (!withinExports) {
+        throw new Error('import file not found in the exports directory');
+    }
+    if (!stats.isFile()) {
+        throw new Error('import path must be a regular file');
+    }
+    if (stats.size > MAX_IMPORT_BYTES) {
+        throw new Error(`import file exceeds the maximum allowed size (${MAX_IMPORT_BYTES} bytes)`);
+    }
+    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)) {
@@ -327,10 +477,23 @@ function createSummary(items, options) {
     }
     return summary;
 }
+// Read the package version at runtime so the server-reported version can never
+// drift from package.json. The compiled entry (dist/index.js) sits one level
+// below the package root, so package.json is at ../package.json.
+function readPackageVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+const SERVER_VERSION = readPackageVersion();
 // Create MCP server
 const server = new index_js_1.Server({
     name: 'memory-keeper',
-    version: '0.10.0',
+    version: SERVER_VERSION,
 }, {
     capabilities: {
         tools: {},
@@ -1320,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) {
@@ -1335,21 +1511,32 @@ 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') {
-                const exportPath = path.join(os.tmpdir(), `memory-keeper-export-${targetSessionId.substring(0, 8)}.json`);
+                const exportPath = path.join(exportsDir, `memory-keeper-export-${targetSessionId.substring(0, 8)}.json`);
                 // Check write permissions
                 try {
                     fs.writeFileSync(exportPath, JSON.stringify(exportData, null, 2));
@@ -1366,11 +1553,16 @@ Checkpoint: ${autoSave ? `git-commit-${new Date().toISOString()}` : 'None'}`,
                     checkpoints: checkpoints.length,
                     size: fs.statSync(exportPath).size,
                 };
+                // context_import caps reads at MAX_IMPORT_BYTES; warn if this export is
+                // too large to be re-imported, so the round trip never breaks silently.
+                const sizeWarning = stats.size > MAX_IMPORT_BYTES
+                    ? `\n⚠️  This export is ${(stats.size / (1024 * 1024)).toFixed(1)} MB and exceeds the ${MAX_IMPORT_BYTES / (1024 * 1024)} MB import limit; context_import will reject it.`
+                    : '';
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: includeStats
+                            text: (includeStats
                                 ? `✅ Successfully exported session "${session.name}" to: ${exportPath}
 
 📊 Export Statistics:
@@ -1382,7 +1574,7 @@ Checkpoint: ${autoSave ? `git-commit-${new Date().toISOString()}` : 'None'}`,
 Session ID: ${targetSessionId}`
                                 : `Exported session to: ${exportPath}
 Items: ${stats.items}
-Files: ${stats.files}`,
+Files: ${stats.files}`) + sizeWarning,
                         },
                     ],
                     exportPath,
@@ -1406,61 +1598,328 @@ Files: ${stats.files}`,
         }
         case 'context_import': {
             const { filePath, merge = false } = args;
+            // Confine the path to the server-owned exports directory BEFORE touching
+            // the filesystem. A failure here is a path/permission problem, never file
+            // content, so the message is safe to return verbatim.
+            let safePath;
             try {
-                const importData = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-                // Create new session or merge
-                let targetSessionId;
-                if (merge && currentSessionId) {
-                    targetSessionId = currentSessionId;
-                }
-                else {
-                    targetSessionId = (0, uuid_1.v4)();
-                    const importedSession = importData.session;
-                    db.prepare(`
-            INSERT INTO sessions (id, name, description, branch, working_directory, created_at)
-            VALUES (?, ?, ?, ?, ?, ?)
-          `).run(targetSessionId, `Imported: ${importedSession.name}`, `Imported from ${filePath} on ${new Date().toISOString()}`, importedSession.branch, null, new Date().toISOString());
-                    currentSessionId = targetSessionId;
-                }
-                // Import context items
-                const itemStmt = db.prepare(`
-          INSERT OR REPLACE INTO context_items (id, session_id, key, value, category, priority, size, created_at, updated_at)
-          VALUES (?, ?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
-        `);
-                let itemCount = 0;
-                for (const item of importData.contextItems) {
-                    itemStmt.run((0, uuid_1.v4)(), targetSessionId, item.key, item.value, item.category, item.priority, item.size || calculateSize(item.value), item.created_at);
-                    itemCount++;
+                safePath = resolveConfinedImportPath(filePath);
+            }
+            catch (error) {
+                return {
+                    content: [{ type: 'text', text: `Import failed: ${error.message}` }],
+                };
+            }
+            // Read and parse separately so a JSON.parse error can never echo file
+            // bytes back to the caller (V8 includes the offending input in its
+            // SyntaxError message).
+            let importData;
+            try {
+                const raw = fs.readFileSync(safePath, 'utf8');
+                try {
+                    importData = JSON.parse(raw);
                 }
-                // Import file cache
-                const fileStmt = db.prepare(`
-          INSERT OR REPLACE INTO file_cache (id, session_id, file_path, content, hash, last_read)
-          VALUES (?, ?, ?, ?, ?, ?)
-        `);
-                let fileCount = 0;
-                for (const file of importData.fileCache || []) {
-                    fileStmt.run((0, uuid_1.v4)(), targetSessionId, file.file_path, file.content, file.hash, file.last_read);
-                    fileCount++;
+                catch {
+                    return {
+                        content: [{ type: 'text', text: 'Import failed: file is not valid JSON export data' }],
+                    };
                 }
+            }
+            catch {
+                return {
+                    content: [{ type: 'text', text: 'Import failed: could not read import file' }],
+                };
+            }
+            // Validate the import has the expected shape before using it.
+            if (typeof importData !== 'object' ||
+                importData === null ||
+                typeof importData.session !== 'object' ||
+                importData.session === null ||
+                typeof importData.session.name !== 'string' ||
+                !Array.isArray(importData.contextItems)) {
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `Import successful!
-Session: ${targetSessionId.substring(0, 8)}
-Context items: ${itemCount}
-Files: ${fileCount}
-Mode: ${merge ? 'Merged' : 'New session'}`,
+                            text: 'Import failed: file is not a valid memory-keeper export (missing session or contextItems)',
                         },
                     ],
                 };
             }
+            // Merge only when there is actually a session to merge into; otherwise
+            // 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. 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 ||
+                checkpointEntries.length > MAX_IMPORT_ITEMS ||
+                checkpointItemEntries.length > MAX_IMPORT_ITEMS ||
+                checkpointFileEntries.length > MAX_IMPORT_ITEMS) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Import failed: file exceeds the maximum allowed entry count (${MAX_IMPORT_ITEMS})`,
+                        },
+                    ],
+                };
+            }
+            try {
+                // Apply the whole import atomically so a malformed row cannot leave an
+                // orphaned session or a partially-populated one behind. We do NOT mutate
+                // the module-level currentSessionId inside the transaction: better-sqlite3
+                // rolls back the database on error but cannot revert a JS assignment, so a
+                // post-assignment failure would leave currentSessionId dangling. Instead we
+                // return the new id and publish it only after the transaction commits.
+                const runImport = db.transaction(() => {
+                    let targetSessionId;
+                    const createdNew = !merged;
+                    if (merged) {
+                        targetSessionId = currentSessionId;
+                    }
+                    else {
+                        targetSessionId = (0, uuid_1.v4)();
+                        const importedSession = importData.session;
+                        db.prepare(`
+              INSERT INTO sessions (id, name, description, branch, working_directory, created_at)
+              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, 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)
+          `);
+                    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.
+                        if (typeof item !== 'object' ||
+                            item === null ||
+                            typeof item.key !== 'string' ||
+                            typeof item.value !== 'string') {
+                            skippedItems++;
+                            continue;
+                        }
+                        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.
+                        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).
+                    // 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 skippedFiles = 0;
+                    let validFiles = 0;
+                    const filesByPath = new Map();
+                    const fileOldIdsByPath = new Map();
+                    for (const file of fileCacheEntries) {
+                        if (typeof file !== 'object' ||
+                            file === null ||
+                            typeof file.file_path !== 'string' ||
+                            (file.content !== null && typeof file.content !== 'string')) {
+                            skippedFiles++;
+                            continue;
+                        }
+                        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++;
+                    }
+                    // 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.
+                if (result.createdNew) {
+                    currentSessionId = result.targetSessionId;
+                }
+                const lines = [
+                    'Import successful!',
+                    `Session: ${result.targetSessionId.substring(0, 8)}`,
+                    `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'}`,
+                ];
+                // 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) {
+                    lines.push('Note: merge requested but no active session existed; created a new session.');
+                }
+                if (result.itemCount === 0 && importData.contextItems.length > 0) {
+                    lines.push('Warning: no valid context items were found; nothing was imported.');
+                }
+                return {
+                    content: [{ type: 'text', text: lines.join('\n') }],
+                };
+            }
             catch (error) {
+                // The error here comes from the DB layer and may echo the values being
+                // inserted; keep the caller-facing message generic and log the detail.
+                console.error(`[memory-keeper] context_import failed: ${error?.message ?? error}`);
                 return {
                     content: [
                         {
                             type: 'text',
-                            text: `Import failed: ${error.message}`,
+                            text: 'Import failed: could not write imported data to the database',
                         },
                     ],
                 };
@@ -3644,7 +4103,10 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
         // Phase 3: Export/Import
         {
             name: 'context_export',
-            description: 'Export session data for backup or sharing',
+            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: {
                 type: 'object',
                 properties: {
@@ -3660,11 +4122,16 @@ server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
         },
         {
             name: 'context_import',
-            description: 'Import previously exported session data',
+            description: 'Import previously exported session data. For security, imports are confined to the ' +
+                "server's exports directory (where context_export writes); arbitrary filesystem paths are rejected.",
             inputSchema: {
                 type: 'object',
                 properties: {
-                    filePath: { type: 'string', description: 'Path to import file' },
+                    filePath: {
+                        type: 'string',
+                        description: 'Path to an export file inside the exports directory. Relative paths resolve ' +
+                            'against that directory; absolute paths must point inside it.',
+                    },
                     merge: {
                         type: 'boolean',
                         description: 'Merge with current session instead of creating new',