cf-memory-mcp 3.49.0 → 3.51.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
@@ -4399,21 +4400,34 @@ async function runResumeCli() {
         // --diff <other-id>: compare two handoffs. Shows added/removed
         // next_steps, branch shift, status change, files diff. Useful
         // for "what changed between yesterday's session and today's?".
+        // Special value "--parent" diffs against the chain parent.
         if (flags.diff) {
             if (!found) {
                 process.stderr.write('No source handoff available to diff against.\n');
                 process.exit(3);
             }
+            let diffTarget = flags.diff;
+            // --diff --parent: resolve to the parent_session_id from the
+            // current handoff so users can do "what's new since the
+            // last checkpoint" without typing the parent's id.
+            if (diffTarget === '--parent' || diffTarget === 'parent') {
+                const parentId = payload.resume_handoff.handoff?.parent_session_id;
+                if (!parentId) {
+                    process.stderr.write('This handoff has no parent_session_id to diff against.\n');
+                    process.exit(3);
+                }
+                diffTarget = parentId;
+            }
             const otherRes = await server.makeRequest({
                 jsonrpc: '2.0', id: `cli-diff-${Date.now()}`,
                 method: 'tools/call',
-                params: { name: 'get_context_bootstrap', arguments: { resume: true, session_id_hint: flags.diff } },
+                params: { name: 'get_context_bootstrap', arguments: { resume: true, session_id_hint: diffTarget } },
             });
             const otherText = otherRes?.result?.content?.[0]?.text;
             const otherPayload = JSON.parse(otherText || '{}');
             const otherHandoff = otherPayload.resume_handoff?.handoff;
             if (!otherHandoff) {
-                process.stderr.write(`Could not fetch handoff "${flags.diff}" to diff against.\n`);
+                process.stderr.write(`Could not fetch handoff "${diffTarget}" to diff against.\n`);
                 process.exit(3);
             }
             const h = payload.resume_handoff.handoff;
@@ -4563,6 +4577,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');
@@ -5006,7 +5116,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
@@ -5034,6 +5145,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; };
@@ -5247,6 +5379,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) {
@@ -5359,8 +5496,25 @@ async function runDoctorCli() {
         }
     }
 
+    // Optional: handoff stats summary at the bottom (visibility into
+    // how much resume context is captured for the current user).
+    let handoffStats = null;
+    if (API_KEY) {
+        try {
+            const statsRes = await server.makeRequestOnce({
+                jsonrpc: '2.0', id: `doctor-stats-${Date.now()}`,
+                method: 'tools/call', params: { name: 'get_stats', arguments: {} },
+            });
+            const statsText = statsRes?.result?.content?.[0]?.text;
+            if (statsText) {
+                const statsPayload = JSON.parse(statsText);
+                if (statsPayload?.handoffs) handoffStats = statsPayload.handoffs;
+            }
+        } catch (_) { /* skip on failure */ }
+    }
+
     if (flags.json) {
-        process.stdout.write(JSON.stringify({ checks }, null, 2) + '\n');
+        process.stdout.write(JSON.stringify({ checks, ...(handoffStats ? { handoffs: handoffStats } : {}) }, null, 2) + '\n');
         process.exit(checks.every(c => c.ok) ? 0 : 1);
     }
     process.stdout.write(`cf-memory-mcp v${PACKAGE_VERSION} — doctor\n\n`);
@@ -5373,6 +5527,23 @@ async function runDoctorCli() {
             process.stdout.write(`      → ${c.fix}\n`);
         }
     }
+    if (handoffStats) {
+        process.stdout.write('\nHandoff stats:\n');
+        process.stdout.write(`  total:              ${handoffStats.total}\n`);
+        if (handoffStats.by_status) {
+            const byStatus = Object.entries(handoffStats.by_status)
+                .map(([s, n]) => `${s}=${n}`).join(', ');
+            process.stdout.write(`  by_status:          ${byStatus}\n`);
+        }
+        if (handoffStats.oldest_in_progress) {
+            const o = handoffStats.oldest_in_progress;
+            const shortId = (o.session_id || '').slice(0, 8);
+            process.stdout.write(`  oldest in_progress: ${shortId} (${o.age_minutes}m ago)\n`);
+        }
+        if (handoffStats.by_repo && handoffStats.by_repo.length > 0) {
+            process.stdout.write(`  top repos:          ${handoffStats.by_repo.slice(0, 3).map(r => `${r.repo_path.split('/').pop()}=${r.count}`).join(', ')}\n`);
+        }
+    }
     process.stdout.write('\n');
     process.stdout.write(anyFailed ? 'Some checks failed. See suggestions above.\n' : 'All checks passed.\n');
     process.exit(anyFailed ? 1 : 0);
@@ -5998,6 +6169,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.49.0",
+	"version": "3.51.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": {