mcp-memory-keeper 0.12.2 → 0.14.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ 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
+
+- Server-reported version is now read from `package.json` at runtime instead of a hardcoded string, which had drifted to `0.10.0`. Added an E2E test asserting the reported version matches `package.json` so it can't fall out of sync again.
+
+### Security
+
+- **Arbitrary local file read via unvalidated `context_import` filePath** (#35)
+  - `context_import` passed the caller-supplied `filePath` straight to `fs.readFileSync`, with no path confinement. A malicious MCP client — or a prompt-injected agent — could point it at any file the server process could read: full contents for any JSON file (imported into the session, then retrievable via `context_get`/`context_export`), and the leading bytes of any other file (echoed back inside the `JSON.parse` error message)
+  - Imports are now confined to a server-owned exports directory (`<DATA_DIR>/exports`, overridable via `MEMORY_KEEPER_EXPORT_DIR`). Relative paths resolve against that directory; absolute paths are accepted only if they resolve — after following symlinks via `realpath` — to a location inside it. Traversal (`../`) and absolute paths outside the directory are rejected
+  - `context_export` now writes to that same exports directory (previously the OS temp dir), so the export → import round trip stays within the confined location
+  - Import failures no longer echo raw exception messages — at every stage (read, JSON parse, and the database write) a generic message is returned and the detail is logged server-side, so no file bytes or inserted values can leak back to the caller
+  - Import is hardened further: the resolved path must be a regular file (directories are rejected), capped at 50 MB and 100k entries to avoid memory/CPU exhaustion, and the whole import runs in a single transaction so a malformed row can never leave an orphaned or partially-populated session. Per-item and session-name shape are validated; `merge` only merges when a current session actually exists (and the result is reported honestly)
+  - The "not found" and "outside the exports directory" cases now return an identical generic message, removing a file-existence oracle, and the resolved absolute path is never echoed back to the caller
+  - `context_export`'s tool description and the import path resolution now guard the exports-directory startup (graceful FATAL on an unreadable directory)
+  - **Round-trip fidelity fixes** surfaced by review of the above: imported items now restore their `channel`, `is_private`, and `metadata` columns (previously dropped); file-cache rows with `NULL` content are preserved (previously dropped); a stored `size` of `0` is no longer wrongly recomputed; skipped-malformed counts and "checkpoints present but not imported" are reported instead of being silently lost; and `context_export` warns when a produced file is too large to be re-imported. The new current session is published only after the import transaction commits, so a failed import can no longer leave `currentSessionId` pointing at a rolled-back session
+  - Added an E2E security regression test suite that reproduces the issue #35 PoC (arbitrary JSON read, `/etc/passwd` byte leak, `..` traversal) and covers symlink escape, the `exports-dir`-prefix sibling boundary, the no-existence-oracle guarantee, empty/non-string paths, directory paths, valid-JSON-but-not-an-export, malformed-item skipping, and a data-preserving round trip
+  - Reported by Zhihao Zhang (@mcfly-zzh)
+
 ## [0.12.2] - 2026-04-07
 
 ### Fixed

package/README.md

@@ -814,7 +814,8 @@ mcp_context_search({
 Share context or backup your work:
 
 ```javascript
-// Export current session
+// Export current session — writes into the exports directory
+// (<DATA_DIR>/exports/, overridable via MEMORY_KEEPER_EXPORT_DIR)
 mcp_context_export(); // Creates memory-keeper-export-xxx.json
 
 // Export specific session
@@ -823,7 +824,9 @@ mcp_context_export({
   format: 'json',
 });
 
-// Import from file
+// Import from a file inside the exports directory.
+// A bare filename resolves against that directory; the absolute path
+// returned by context_export also works.
 mcp_context_import({
   filePath: 'memory-keeper-export-xxx.json',
 });
@@ -835,6 +838,17 @@ mcp_context_import({
 });
 ```
 
+> **Security note:** For safety, `context_import` only reads files inside the
+> server-owned exports directory (`<DATA_DIR>/exports/`, or
+> `MEMORY_KEEPER_EXPORT_DIR` if set). Absolute paths outside that directory and
+> `../` traversal are rejected, so the tool cannot be steered at arbitrary
+> files on disk. Drop any file you want to import into that directory first.
+> Point `MEMORY_KEEPER_EXPORT_DIR` at a dedicated directory — not at a home
+> folder or a tree containing secrets — since any JSON file inside it becomes
+> importable. (Prior to this change, exports were written to the OS temp
+> directory; existing exports there must be moved into the exports directory to
+> be re-imported.)
+
 ### Knowledge Graph (Phase 4)
 
 Automatically extract entities and relationships from your context:

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 });
+        }
+    });
+});