cf-memory-mcp 3.50.0 → 3.52.0

package/bin/cf-memory-mcp.js

@@ -3919,7 +3919,7 @@ if (process.argv.includes('--version') || process.argv.includes('-v')) {
 
 // Global --help only when no subcommand is present. With a subcommand, fall
 // through to the per-command help dispatch below.
-const SUBCOMMANDS = new Set(['resume', 'list', 'checkpoint', 'status', 'clean', 'export', 'import', 'doctor', 'completion', 'delete', 'env', 'history', 'link']);
+const SUBCOMMANDS = new Set(['resume', 'list', 'checkpoint', 'status', 'clean', 'export', 'import', 'doctor', 'completion', 'delete', 'env', 'history', 'link', 'explain']);
 const hasSubcommand = process.argv[2] && SUBCOMMANDS.has(process.argv[2]);
 
 if (!hasSubcommand && (process.argv.includes('--help') || process.argv.includes('-h'))) {
@@ -3935,6 +3935,7 @@ Usage:
   npx cf-memory-mcp history         List all handoffs for cwd, chronological
   npx cf-memory-mcp checkpoint ["<goal>"]  Snapshot current state (keep_open)
   npx cf-memory-mcp link <child> --parent <id>  Retroactively link a child session to a parent
+  npx cf-memory-mcp explain <id>     Break down the handoff's quality_score
   npx cf-memory-mcp status          Show bridge state + server resume availability
   npx cf-memory-mcp clean           Delete local disk cache for current cwd
   npx cf-memory-mcp clean --all     Delete ALL local disk caches
@@ -4090,6 +4091,10 @@ function parseCliArgs(rest) {
             flags.repo_path = rest[++i];
         } else if (a.startsWith('--repo=')) {
             flags.repo_path = a.slice('--repo='.length);
+        } else if (a === '--project-id') {
+            flags.project_id = rest[++i];
+        } else if (a.startsWith('--project-id=')) {
+            flags.project_id = a.slice('--project-id='.length);
         } else if (a === '--since') {
             flags.since = rest[++i];
         } else if (a.startsWith('--since=')) {
@@ -4120,9 +4125,20 @@ async function runResumeCli() {
         // Optional positional session_id argument.
         const sessionArg = positional[0];
         if (sessionArg) args.session_id_hint = sessionArg;
-        const fake = { params: { name: 'retrieve_context', arguments: {} } };
-        await server.maybeFillProjectId(fake);
-        if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
+        // Cross-laptop overrides: --repo and --project-id let users bypass
+        // cwd-based matching when paths differ across machines. --project-id
+        // is the most reliable cross-machine anchor since it survives
+        // path differences.
+        if (flags.repo_path) {
+            args.repo_path = flags.repo_path;
+            // Don't auto-fill project_id from the local cwd when --repo
+            // overrides (would otherwise short-circuit to a wrong session).
+        } else {
+            const fake = { params: { name: 'retrieve_context', arguments: {} } };
+            await server.maybeFillProjectId(fake);
+            if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
+        }
+        if (flags.project_id) args.project_id = flags.project_id;
 
         const response = await server.makeRequest({
             jsonrpc: '2.0',
@@ -4576,6 +4592,102 @@ async function runResumeCli() {
     }
 }
 
+async function runExplainCli() {
+    if (!API_KEY) {
+        console.error('Error: CF_MEMORY_API_KEY environment variable is required');
+        process.exit(1);
+    }
+    const { positional, flags } = parseCliArgs(process.argv.slice(3));
+    const idArg = positional[0];
+    if (!idArg) {
+        console.error('Usage: cf-memory-mcp explain <session-id-or-prefix>');
+        process.exit(1);
+    }
+    const server = new CFMemoryMCP();
+    server.logDebug = () => {};
+    try {
+        const response = await server.makeRequest({
+            jsonrpc: '2.0', id: `cli-explain-${Date.now()}`,
+            method: 'tools/call',
+            params: { name: 'get_context_bootstrap', arguments: { resume: true, session_id_hint: idArg } },
+        });
+        const text = response?.result?.content?.[0]?.text;
+        const payload = JSON.parse(text || '{}');
+        const envelope = payload.resume_handoff;
+        if (!envelope?.handoff) {
+            process.stderr.write((payload.empty_hint || `No handoff found for "${idArg}".`) + '\n');
+            process.exit(3);
+        }
+        const h = envelope.handoff;
+        const ageMin = envelope.handoff_age_minutes;
+        const sizeBytes = envelope.handoff_size_bytes ?? 0;
+
+        // Mirror the server-side rubric (see computeQualityScore).
+        const components = [];
+        const add = (label, points, present, detail) =>
+            components.push({ label, points, present, detail });
+
+        add('goal present (>=5 chars)', 0.20, !!(h.goal && h.goal.length >= 5), h.goal ? `"${h.goal.slice(0,40)}"` : 'missing');
+        add('next_steps present', 0.20,
+            Array.isArray(h.next_steps) && h.next_steps.length > 0,
+            `${h.next_steps?.length ?? 0} step${(h.next_steps?.length ?? 0) === 1 ? '' : 's'}`);
+        add('code_anchors present', 0.15,
+            Array.isArray(h.code_anchors) && h.code_anchors.length > 0,
+            `${h.code_anchors?.length ?? 0} anchor${(h.code_anchors?.length ?? 0) === 1 ? '' : 's'}`);
+        add('files_touched present', 0.10,
+            Array.isArray(h.files_touched) && h.files_touched.length > 0,
+            `${h.files_touched?.length ?? 0} file${(h.files_touched?.length ?? 0) === 1 ? '' : 's'}`);
+        add('decisions present', 0.10,
+            Array.isArray(h.decisions) && h.decisions.length > 0,
+            `${h.decisions?.length ?? 0} decision${(h.decisions?.length ?? 0) === 1 ? '' : 's'}`);
+
+        // Recency
+        let recency = 0;
+        let recencyDetail = '?';
+        if (ageMin !== undefined) {
+            if (ageMin <= 1440) recency = 0.15;
+            else if (ageMin <= 10080) recency = 0.15 * (1 - (ageMin - 1440) / (10080 - 1440));
+            recencyDetail = `${ageMin}m old`;
+        }
+        components.push({ label: 'recency (decays past 24h)', points: 0.15, present: recency > 0, detail: `${recencyDetail} → +${recency.toFixed(3)}` });
+
+        // Size in target band
+        let sizeBonus = 0;
+        let sizeDetail;
+        if (sizeBytes >= 500 && sizeBytes <= 8000) { sizeBonus = 0.10; sizeDetail = 'in target 500-8000 byte range'; }
+        else if (sizeBytes >= 200 && sizeBytes <= 16000) { sizeBonus = 0.05; sizeDetail = 'in extended 200-16000 byte range'; }
+        else { sizeDetail = sizeBytes < 200 ? 'too small (<200 bytes)' : 'too large (>16000 bytes)'; }
+        components.push({ label: 'size sweet spot', points: 0.10, present: sizeBonus > 0, detail: `${sizeBytes} bytes — ${sizeDetail}` });
+
+        if (flags.json) {
+            process.stdout.write(JSON.stringify({
+                session_id: envelope.session_id,
+                quality_score: envelope.quality_score,
+                components,
+            }, null, 2) + '\n');
+            process.exit(0);
+        }
+        const shortId = (envelope.session_id || '').slice(0, 8);
+        process.stdout.write(`Quality breakdown for ${shortId} (final score: ${envelope.quality_score}):\n\n`);
+        let earned = 0;
+        for (const c of components) {
+            const mark = c.present ? '✓' : '✗';
+            const earned_pts = c.present ? c.points : 0;
+            earned += earned_pts;
+            process.stdout.write(`  ${mark} ${c.label.padEnd(32)} +${c.points.toFixed(2)}  ${c.detail || ''}\n`);
+        }
+        process.stdout.write(`\n  Total earned: ${earned.toFixed(2)} / 1.00\n`);
+        const missing = components.filter(c => !c.present);
+        if (missing.length > 0) {
+            process.stdout.write(`\n  To improve: add ${missing.map(m => m.label).join(', ')}\n`);
+        }
+        process.exit(0);
+    } catch (err) {
+        console.error('explain command failed:', err.message);
+        process.exit(1);
+    }
+}
+
 async function runListCli() {
     if (!API_KEY) {
         console.error('Error: CF_MEMORY_API_KEY environment variable is required');
@@ -4603,6 +4715,8 @@ async function runListCli() {
             await server.maybeFillProjectId(fake);
             if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
         }
+        // --project-id explicit override (overrides any auto-fill above).
+        if (flags.project_id) args.project_id = flags.project_id;
 
         const response = await server.makeRequest({
             jsonrpc: '2.0',
@@ -4782,6 +4896,9 @@ async function runHistoryCli() {
             await server.maybeFillProjectId(fake);
             if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
         }
+        // --project-id overrides cwd-derived project_id. Useful when
+        // resuming a project you haven't indexed on this machine.
+        if (flags.project_id) args.project_id = flags.project_id;
 
         const response = await server.makeRequest({
             jsonrpc: '2.0',
@@ -5019,7 +5136,8 @@ function runEnvCli() {
 function runCompletionCli() {
     const shell = process.argv[3] || 'bash';
     const install = process.argv.includes('--install');
-    const commands = ['resume', 'list', 'history', 'checkpoint', 'link', 'status', 'clean', 'export', 'import', 'delete', 'doctor', 'env', 'completion'];
+    const uninstall = process.argv.includes('--uninstall');
+    const commands = ['resume', 'list', 'history', 'checkpoint', 'link', 'explain', 'status', 'clean', 'export', 'import', 'delete', 'doctor', 'env', 'completion'];
     const flags = ['--json', '-j', '--limit', '-n', '--md', '--all', '--force', '-f', '--version', '-v', '--help', '-h', '--diagnose'];
 
     // Determine the install target for each shell. Use user-local paths
@@ -5047,6 +5165,27 @@ function runCompletionCli() {
         }
         return null;
     })();
+    // --uninstall: delete the previously-installed completion file. No
+    // need to generate the script. Idempotent.
+    if (uninstall) {
+        if (!installTarget) {
+            process.stderr.write(`No uninstall target for shell ${shell}.\n`);
+            process.exit(1);
+        }
+        try {
+            if (fs.existsSync(installTarget)) {
+                fs.unlinkSync(installTarget);
+                process.stderr.write(`Uninstalled ${shell} completion from ${installTarget}\n`);
+            } else {
+                process.stderr.write(`Nothing to uninstall (no file at ${installTarget}).\n`);
+            }
+            process.exit(0);
+        } catch (err) {
+            process.stderr.write(`Failed to uninstall: ${err.message}\n`);
+            process.exit(1);
+        }
+    }
+
     // Buffer the output so we can either print or write-to-disk.
     let output = '';
     const emit = (chunk) => { output += chunk; };
@@ -5163,6 +5302,8 @@ const PER_COMMAND_HELP = {
     resume: `cf-memory-mcp resume [<session-id-prefix>] [--md path] [<extract-flag>] [--json]
   Print the prior resume handoff (markdown by default).
     <session-id-prefix>   Optional: pick a specific session (>=8 char prefix or full UUID).
+    --repo <path>         Override cwd's repo (for cross-laptop or workspace-switch).
+    --project-id <id>     Override cwd's project_id (best for cross-laptop continuity).
     --md <path>           Write the markdown to a file instead of stdout.
     --copy                Pipe the markdown to the platform clipboard (pbcopy/xclip/wl-copy/clip).
     --card                Compact 2-3 line status card (for terminal status widgets).
@@ -5260,6 +5401,11 @@ const PER_COMMAND_HELP = {
   a parent in the chain. Useful when you forgot --force on checkpoint
   or want to manually chain sessions across repos.
     --json, -j            Emit a JSON status object.`,
+    explain: `cf-memory-mcp explain <session-id-or-prefix> [--json]
+  Break down the handoff's quality_score into its rubric components,
+  showing what's earned + what's missing. Lets users see why a handoff
+  scored 0.5 vs 0.9 — and how to improve it.
+    --json, -j            Emit the breakdown as JSON.`,
 };
 
 function printPerCommandHelp(cmd) {
@@ -6045,6 +6191,11 @@ if (process.argv[2] === 'link') {
     return;
 }
 
+if (process.argv[2] === 'explain') {
+    runExplainCli();
+    return;
+}
+
 if (process.argv.includes('--diagnose')) {
     (async () => {
         console.log(`CF Memory MCP v${PACKAGE_VERSION} - Diagnostics`);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cf-memory-mcp",
-	"version": "3.50.0",
+	"version": "3.52.0",
 	"description": "Cloudflare-hosted MCP server for code indexing, retrieval, and assistant memory with a direct remote MCP endpoint and local stdio bridge.",
 	"main": "bin/cf-memory-mcp.js",
 	"bin": {