cf-memory-mcp 3.35.0 → 3.37.0

package/bin/cf-memory-mcp.js

@@ -217,7 +217,8 @@ const TOOLS_LIST = [
                 max_age_minutes: { type: 'number', description: 'Hard cutoff: hide handoffs older than this many minutes. Without it, older handoffs surface with reduced confidence.' },
                 goal_contains: { type: 'string', description: 'Substring filter on handoff content (goal/notes/decisions). Case-insensitive. Lets agents find a specific thread by what it was about.' },
                 since: { type: 'string', description: 'Lower bound on handoff timestamp (ISO 8601). Scope resume to a time window.' },
-                status_filter: { description: 'Restrict matches to handoffs with this status. Single string or array of strings (e.g., ["in_progress","blocked"]).' }
+                status_filter: { description: 'Restrict matches to handoffs with this status. Single string or array of strings (e.g., ["in_progress","blocked"]).' },
+                recent_handoff_limit: { type: 'number', description: 'Override the default recent_handoffs cap (5). Range 1-50.' }
             }
         }
     },
@@ -3806,7 +3807,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']);
+const SUBCOMMANDS = new Set(['resume', 'list', 'checkpoint', 'status', 'clean', 'export', 'import', 'doctor', 'completion', 'delete', 'env', 'history']);
 const hasSubcommand = process.argv[2] && SUBCOMMANDS.has(process.argv[2]);
 
 if (!hasSubcommand && (process.argv.includes('--help') || process.argv.includes('-h'))) {
@@ -3818,7 +3819,8 @@ A portable MCP (Model Context Protocol) server for AI memory storage using Cloud
 Usage:
   npx cf-memory-mcp                 Start the MCP server
   npx cf-memory-mcp resume [id]     Print the prior resume handoff (markdown)
-  npx cf-memory-mcp list            List recent handoffs for cwd
+  npx cf-memory-mcp list            List recent handoffs for cwd (status-ranked)
+  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 status          Show bridge state + server resume availability
   npx cf-memory-mcp clean           Delete local disk cache for current cwd
@@ -3878,6 +3880,12 @@ function parseCliArgs(rest) {
             flags.files_only = true;
         } else if (a === '--anchors-only') {
             flags.anchors_only = true;
+        } else if (a === '--decisions-only') {
+            flags.decisions_only = true;
+        } else if (a === '--blockers-only') {
+            flags.blockers_only = true;
+        } else if (a === '--chain') {
+            flags.chain = true;
         } else if (a === '--older-than') {
             // Accept "7d" / "30d" / "12h" / raw number (days).
             const raw = rest[++i] || '';
@@ -4014,6 +4022,76 @@ async function runResumeCli() {
             process.exit(0);
         }
 
+        // --decisions-only: list decisions from the handoff, one per line.
+        if (flags.decisions_only) {
+            const decisions = payload.resume_handoff?.handoff?.decisions || [];
+            if (decisions.length === 0) process.exit(3);
+            for (const d of decisions) process.stdout.write(`- ${d}\n`);
+            process.exit(0);
+        }
+
+        // --blockers-only: list open blockers, one per line. Empty list
+        // exits 3 so scripts can branch on "no blockers".
+        if (flags.blockers_only) {
+            const blockers = payload.resume_handoff?.handoff?.blockers || [];
+            if (blockers.length === 0) process.exit(3);
+            for (const b of blockers) process.stdout.write(`- ${b}\n`);
+            process.exit(0);
+        }
+
+        // --chain: walk parent_session_id back through the thread history.
+        // Bounded at 20 iterations to avoid an infinite loop on malformed
+        // data. Prints each handoff as "<id> [age] status — goal".
+        if (flags.chain) {
+            if (!found) {
+                process.stderr.write('No resume handoff available to walk back from.\n');
+                process.exit(3);
+            }
+            const fmtAge = (iso) => {
+                if (!iso) return '?';
+                const min = Math.round((Date.now() - new Date(iso).getTime()) / 60000);
+                if (min < 60) return `${min}m`;
+                if (min < 1440) return `${Math.round(min/60)}h`;
+                return `${Math.round(min/1440)}d`;
+            };
+            const chain = [];
+            let cur = payload.resume_handoff;
+            chain.push(cur);
+            for (let i = 0; i < 20; i++) {
+                const parentId = cur?.handoff?.parent_session_id;
+                if (!parentId) break;
+                // Fetch parent
+                const parentRes = await server.makeRequest({
+                    jsonrpc: '2.0', id: `cli-chain-${i}-${Date.now()}`,
+                    method: 'tools/call',
+                    params: { name: 'get_context_bootstrap', arguments: { resume: true, session_id_hint: parentId } },
+                });
+                const parentText = parentRes?.result?.content?.[0]?.text;
+                const parentPayload = JSON.parse(parentText || '{}');
+                if (!parentPayload.resume_handoff) break;
+                chain.push(parentPayload.resume_handoff);
+                cur = parentPayload.resume_handoff;
+            }
+            if (flags.json) {
+                process.stdout.write(JSON.stringify({ chain }, null, 2) + '\n');
+                process.exit(0);
+            }
+            process.stdout.write(`Thread chain (newest first, ${chain.length} session${chain.length === 1 ? '' : 's'}):\n\n`);
+            for (let i = 0; i < chain.length; i++) {
+                const e = chain[i];
+                const shortId = (e.session_id || '').slice(0, 8);
+                const age = fmtAge(e.ended_at || e.started_at);
+                const status = e.handoff?.status || '?';
+                const goal = e.handoff?.goal || '(no goal)';
+                const prefix = i === 0 ? '→' : ' ';
+                process.stdout.write(`${prefix} ${shortId}  ${status.padEnd(11)}  ${age.padStart(4)} ago  ${goal}\n`);
+            }
+            if (chain[chain.length-1]?.handoff?.parent_session_id) {
+                process.stdout.write(`\n(chain truncated at 20 — increase with multiple --chain calls)\n`);
+            }
+            process.exit(0);
+        }
+
         // --md <path>: write the rendered markdown to a file instead of
         // (or in addition to) stdout. Useful for piping to a markdown
         // viewer or saving to the project.
@@ -4154,6 +4232,71 @@ async function runListCli() {
     }
 }
 
+async function runHistoryCli() {
+    if (!API_KEY) {
+        console.error('Error: CF_MEMORY_API_KEY environment variable is required');
+        process.exit(1);
+    }
+    const { flags } = parseCliArgs(process.argv.slice(3));
+    const limit = flags.limit || 25;
+    const server = new CFMemoryMCP();
+    server.logDebug = () => {};
+    try {
+        const meta = server.getRepoMetadata();
+        const args = { resume: true, recent_handoff_limit: limit };
+        if (meta.repo_path) args.repo_path = meta.repo_path;
+        if (meta.branch) args.branch = meta.branch;
+        if (flags.repo_path) args.repo_path = flags.repo_path;
+        if (flags.since) args.since = flags.since;
+        if (!flags.repo_path) {
+            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;
+        }
+
+        const response = await server.makeRequest({
+            jsonrpc: '2.0',
+            id: `cli-history-${Date.now()}`,
+            method: 'tools/call',
+            params: { name: 'get_context_bootstrap', arguments: args },
+        });
+        const text = response?.result?.content?.[0]?.text;
+        const payload = JSON.parse(text || '{}');
+        const all = (payload.recent_handoffs || []).slice();
+        // Chronological order (oldest first).
+        all.sort((a, b) => {
+            const ta = new Date(a.ended_at || a.started_at).getTime();
+            const tb = new Date(b.ended_at || b.started_at).getTime();
+            return ta - tb;
+        });
+        if (flags.json) {
+            process.stdout.write(JSON.stringify({
+                repo_path: args.repo_path,
+                count: all.length,
+                handoffs: all,
+            }, null, 2) + '\n');
+            process.exit(all.length === 0 ? 3 : 0);
+        }
+        if (all.length === 0) {
+            process.stderr.write((payload.empty_hint || 'No handoffs for this context.') + '\n');
+            process.exit(3);
+        }
+        const fmtDate = (iso) => iso ? new Date(iso).toISOString().slice(0, 16).replace('T', ' ') : '?';
+        process.stdout.write(`History for ${args.repo_path || 'this cwd'} (${all.length} handoff${all.length === 1 ? '' : 's'}, oldest first):\n\n`);
+        for (const h of all) {
+            const shortId = (h.session_id || '').slice(0, 8);
+            const when = fmtDate(h.ended_at || h.started_at);
+            const status = (h.status || 'unknown').padEnd(11);
+            const goal = (h.goal || '(no goal)').slice(0, 70);
+            process.stdout.write(`  ${when}  ${shortId}  ${status}  ${goal}\n`);
+        }
+        process.exit(0);
+    } catch (err) {
+        console.error('history command failed:', err.message);
+        process.exit(1);
+    }
+}
+
 async function runDeleteCli() {
     if (!API_KEY) {
         console.error('Error: CF_MEMORY_API_KEY environment variable is required');
@@ -4346,7 +4489,7 @@ function runEnvCli() {
 
 function runCompletionCli() {
     const shell = process.argv[3] || 'bash';
-    const commands = ['resume', 'list', 'checkpoint', 'status', 'clean', 'export', 'import', 'delete', 'doctor', 'env', 'completion'];
+    const commands = ['resume', 'list', 'history', 'checkpoint', 'status', 'clean', 'export', 'import', 'delete', 'doctor', 'env', 'completion'];
     const flags = ['--json', '-j', '--limit', '-n', '--md', '--all', '--force', '-f', '--version', '-v', '--help', '-h', '--diagnose'];
     if (shell === 'bash') {
         process.stdout.write(`# cf-memory-mcp bash completion
@@ -4412,16 +4555,19 @@ complete -c cf-memory-mcp -l version -s v -d 'Show version'
 
 // Per-command help texts. Used when "cf-memory-mcp <cmd> --help" is invoked.
 const PER_COMMAND_HELP = {
-    resume: `cf-memory-mcp resume [<session-id-prefix>] [--md path] [--next-only|--next-steps|--files-only|--anchors-only] [--json]
+    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).
     --md <path>           Write the markdown to a file instead of stdout.
-    --next-only           Print just the first next_step (for shell prompts).
-    --next-steps          Print ALL next_steps, numbered.
-    --files-only          Print files_touched paths, one per line (xargs-friendly).
-    --anchors-only        Print code_anchors as "file:lines symbol".
-    --json, -j            Emit the full bootstrap payload as JSON for scripts.
-  Exit codes: 0 = handoff found, 3 = no handoff or no data for the flag.`,
+  Extract flags (pick one; each exits 3 if the section is empty):
+    --next-only           First next_step only (for shell prompts).
+    --next-steps          All next_steps, numbered.
+    --files-only          files_touched paths, one per line (xargs-friendly).
+    --anchors-only        code_anchors as "file:lines symbol".
+    --decisions-only      decisions, one per line.
+    --blockers-only       open blockers, one per line.
+    --json, -j            Full bootstrap payload as JSON.
+  Exit codes: 0 = found, 3 = no handoff / no data.`,
     list: `cf-memory-mcp list [--status S] [--since ISO] [--repo PATH] [--limit N] [--json]
   List recent handoffs for the current cwd, status-ranked. Header shows
   a status-count summary.
@@ -4477,6 +4623,14 @@ const PER_COMMAND_HELP = {
   Print all CF_MEMORY_* env vars the bridge reads, with their current
   values + descriptions. Useful for discovering knobs.
     --json, -j            Emit JSON for scripts.`,
+    history: `cf-memory-mcp history [--limit N] [--repo PATH] [--since ISO] [--json]
+  Print all handoffs for the current cwd in chronological order (oldest
+  first). Unlike 'list' (status-ranked, default 5), this is a flat
+  timeline view.
+    --limit N             Max number of handoffs (default 25, max 50).
+    --repo PATH           Override the cwd's repo.
+    --since ISO           Lower bound on handoff timestamp.
+    --json, -j            Emit JSON.`,
 };
 
 function printPerCommandHelp(cmd) {
@@ -4890,11 +5044,14 @@ async function runCheckpointCli() {
         // Optional positional goal argument: `cf-memory-mcp checkpoint "<goal text>"`
         const goalArg = positional.filter(p => p !== '--force' && p !== '-f').join(' ').trim();
 
-        // Duplicate detection: before creating a new implicit session,
-        // check if there's a recent in_progress handoff for the same
-        // repo/branch. If so, suggest resuming it instead of churning a
-        // new one. Skipped with --force.
-        if (!force) {
+        // Duplicate detection + parent linking: before creating a new
+        // implicit session, check if there's a recent in_progress handoff
+        // for the same repo/branch. If so, suggest resuming it instead
+        // of churning a new one. With --force, proceed but record the
+        // existing session id as the new handoff's parent_session_id so
+        // the chain can be traced later.
+        let parentSessionId = null;
+        if (true) { // always probe to capture parent; --force only bypasses the abort
             const meta = server.getRepoMetadata();
             if (meta.repo_path) {
                 const probeArgs = { resume: true, repo_path: meta.repo_path, status_filter: 'in_progress', max_age_minutes: 60 };
@@ -4912,7 +5069,7 @@ async function runCheckpointCli() {
                     // Same-cwd implicit session won't be in the worker yet
                     // unless someone called start_session — we look for
                     // OTHER active threads on the same repo.
-                    if (recent) {
+                    if (recent && !force) {
                         const shortId = (recent.session_id || '').slice(0, 8);
                         const ageMin = recent.handoff_age_minutes ?? '?';
                         const status = recent.handoff?.status || '?';
@@ -4933,6 +5090,9 @@ async function runCheckpointCli() {
                         process.stderr.write(`Resume it: cf-memory-mcp resume ${shortId}\n`);
                         process.stderr.write(`Or re-run with --force to create a new session anyway.\n`);
                         process.exit(4);
+                    } else if (recent && force) {
+                        // --force: proceed, but record the parent link.
+                        parentSessionId = recent.session_id;
                     }
                 } catch (_) { /* probe failure is non-fatal */ }
             }
@@ -4950,6 +5110,7 @@ async function runCheckpointCli() {
         // this is a fresh process).
         const handoff = server.synthesizeMinimalHandoff();
         if (goalArg) handoff.goal = goalArg;
+        if (parentSessionId) handoff.parent_session_id = parentSessionId;
         if (meta.repo_path) handoff.repo_path = meta.repo_path;
         if (meta.branch) handoff.branch = meta.branch;
         const fake = { params: { name: 'retrieve_context', arguments: {} } };
@@ -5059,6 +5220,11 @@ if (process.argv[2] === 'env') {
     return;
 }
 
+if (process.argv[2] === 'history') {
+    runHistoryCli();
+    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.35.0",
+	"version": "3.37.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": {