cf-memory-mcp 3.31.0 → 3.33.0

package/README.md

@@ -35,6 +35,32 @@ The active runtime is at [src-simplified/index.ts](src-simplified/index.ts). It
 - Coordination and progress with Durable Objects
 - Diagnostics: `health_check` tool + `npx cf-memory-mcp --diagnose` + `CF_MEMORY_TRACE=1`
 
+## Resume Context (cross-chat handoff)
+
+Beyond code retrieval, cf-memory-mcp persists structured "handoff" packets so one chat can hand work off to the next. The next agent calls `get_context_bootstrap({resume:true})` (or the CLI `cf-memory-mcp resume`) and gets back the goal, status, next steps, code anchors with staleness markers, files touched, and a pre-rendered markdown prompt — without re-exploring the repo.
+
+**Measured impact** (`scripts/benchmark-cold-vs-warm.ts`): warm resume is **82-85% faster** with **3-4 fewer tool calls** than cold-start exploration, and the warm path returns the exact next_action the cold agent would have eventually figured out.
+
+```bash
+$ npx cf-memory-mcp resume        # print prior handoff for cwd
+$ npx cf-memory-mcp list          # all recent handoffs (with status counts)
+$ npx cf-memory-mcp checkpoint    # snapshot current state
+$ npx cf-memory-mcp status        # bridge + server health for cwd
+$ npx cf-memory-mcp doctor        # diagnose common setup issues
+$ npx cf-memory-mcp export <id>   # backup a handoff
+$ npx cf-memory-mcp import <file> # cross-machine sync
+$ npx cf-memory-mcp delete <id>   # remove a session
+$ cfm resume                       # short alias
+```
+
+Resume context also surfaces via:
+
+- **MCP tools**: `start_session`, `end_session` (with structured `handoff`), `get_context_bootstrap` (with `resume`, `session_id_hint`, `goal_contains`, `since`, `status_filter`, `max_age_minutes`)
+- **MCP resources**: `cfm://resume/current`, `cfm://resume/recent`, `cfm://resume/session/<id>`
+- **MCP prompts**: `/resume`, `/list_threads` (for clients with slash-command UI)
+
+See [docs/RESUME_CONTEXT_PLAN.md](docs/RESUME_CONTEXT_PLAN.md) for design rationale and [agents.md](agents.md) for the full agent-facing reference.
+
 ## Active Infra
 
 - Workers

package/bin/cf-memory-mcp.js

@@ -411,13 +411,16 @@ const TOOLS_LIST = [
     },
     {
         name: 'delete_session',
-        description: 'Delete a session row and any session_summary memories tied to it. Use to remove test sessions or accidental handoffs. Different from end_session — this physically removes the row. Pass the full UUID (not a prefix).',
+        description: 'Delete session row(s) and any session_summary memories tied to them. Accepts single-id or bulk filters. Different from end_session — this physically removes rows.',
         inputSchema: {
             type: 'object',
             properties: {
-                session_id: { type: 'string', description: 'Full session UUID to delete.' }
-            },
-            required: ['session_id']
+                session_id: { type: 'string', description: 'Full session UUID to delete (not a prefix).' },
+                status: { description: 'Status filter: single string or array of statuses (in_progress, blocked, completed, abandoned).' },
+                older_than_days: { type: 'number', description: 'Delete sessions older than N days.' },
+                repo_path: { type: 'string', description: 'Restrict to a specific repo_path.' },
+                dry_run: { type: 'boolean', description: 'When true, preview what would be deleted without actually deleting.' }
+            }
         }
     }
 ];
@@ -3850,7 +3853,7 @@ For more information, visit: https://github.com/johnlam90/cf-memory-mcp
 }
 
 // Parse positional + flag args for CLI subcommands. Returns
-// { positional: string[], flags: { json, limit, md_path } }.
+// { positional: string[], flags: { json, limit, md_path, older_than_days, status, repo_path, yes } }.
 function parseCliArgs(rest) {
     const positional = [];
     const flags = { json: false };
@@ -3864,10 +3867,40 @@ function parseCliArgs(rest) {
             const n = parseInt(a.slice('--limit='.length), 10);
             if (Number.isFinite(n) && n > 0) flags.limit = Math.min(n, 50);
         } else if (a === '--md') {
-            // Next arg is path; supports `--md=path` too.
             flags.md_path = rest[++i];
         } else if (a.startsWith('--md=')) {
             flags.md_path = a.slice('--md='.length);
+        } else if (a === '--older-than') {
+            // Accept "7d" / "30d" / "12h" / raw number (days).
+            const raw = rest[++i] || '';
+            const m = raw.match(/^(\d+)\s*(d|h|m)?$/);
+            if (m) {
+                const n = parseInt(m[1], 10);
+                const unit = m[2] || 'd';
+                flags.older_than_days = unit === 'd' ? n : unit === 'h' ? n / 24 : n / 1440;
+            }
+        } else if (a.startsWith('--older-than=')) {
+            const raw = a.slice('--older-than='.length);
+            const m = raw.match(/^(\d+)\s*(d|h|m)?$/);
+            if (m) {
+                const n = parseInt(m[1], 10);
+                const unit = m[2] || 'd';
+                flags.older_than_days = unit === 'd' ? n : unit === 'h' ? n / 24 : n / 1440;
+            }
+        } else if (a === '--status') {
+            flags.status = rest[++i];
+        } else if (a.startsWith('--status=')) {
+            flags.status = a.slice('--status='.length);
+        } else if (a === '--repo') {
+            flags.repo_path = rest[++i];
+        } else if (a.startsWith('--repo=')) {
+            flags.repo_path = a.slice('--repo='.length);
+        } else if (a === '--since') {
+            flags.since = rest[++i];
+        } else if (a.startsWith('--since=')) {
+            flags.since = a.slice('--since='.length);
+        } else if (a === '--yes' || a === '-y') {
+            flags.yes = true;
         } else positional.push(a);
     }
     return { positional, flags };
@@ -3978,9 +4011,19 @@ async function runListCli() {
         const args = { resume: true };
         if (meta.repo_path) args.repo_path = meta.repo_path;
         if (meta.branch) args.branch = meta.branch;
-        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;
+        // Pass-through server-side filters when set on the CLI.
+        if (flags.status) args.status_filter = flags.status;
+        if (flags.since) args.since = flags.since;
+        if (flags.repo_path) {
+            // --repo overrides cwd → skip cwd's project_id too. Otherwise
+            // tier-1 project_id_exact would short-circuit the lookup and
+            // return cwd's handoff regardless of repo_path.
+            args.repo_path = flags.repo_path;
+        } 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;
+        }
 
         const response = await server.makeRequest({
             jsonrpc: '2.0',
@@ -3997,8 +4040,10 @@ async function runListCli() {
 
         if (flags.json) {
             process.stdout.write(JSON.stringify({
-                repo_path: meta.repo_path,
-                branch: meta.branch,
+                repo_path: args.repo_path || meta.repo_path,
+                branch: args.branch || meta.branch,
+                status_filter: flags.status,
+                since: flags.since,
                 count: list.length,
                 handoffs: list,
                 empty_hint: list.length === 0 ? payload.empty_hint : undefined,
@@ -4009,8 +4054,20 @@ async function runListCli() {
             process.stderr.write((payload.empty_hint || 'No handoffs for this context.') + '\n');
             process.exit(3);
         }
-        // Render a compact table to terminal.
-        process.stdout.write(`Recent handoffs for ${meta.repo_path || 'this cwd'}:\n\n`);
+        // Status counts header: scan the visible list to give an at-a-glance
+        // summary before the per-row details.
+        const counts = {};
+        for (const h of allList) {
+            const s = h.status || 'unknown';
+            counts[s] = (counts[s] || 0) + 1;
+        }
+        const countSummary = Object.entries(counts)
+            .map(([s, n]) => `${n} ${s}`)
+            .join(', ');
+        // Render a compact table to terminal. Show the actual filter
+        // applied (--repo override, or cwd default).
+        const displayRepo = args.repo_path || 'this cwd';
+        process.stdout.write(`Recent handoffs for ${displayRepo} (${countSummary}):\n\n`);
         const fmtAge = (iso) => {
             if (!iso) return '?';
             const min = Math.round((Date.now() - new Date(iso).getTime()) / 60000);
@@ -4042,15 +4099,79 @@ async function runDeleteCli() {
     }
     const { positional, flags } = parseCliArgs(process.argv.slice(3));
     const idArg = positional[0];
-    if (!idArg) {
-        console.error('Usage: cf-memory-mcp delete <session-id-or-prefix>');
+    const bulkMode = !idArg && (flags.older_than_days !== undefined || flags.status || flags.repo_path);
+    if (!idArg && !bulkMode) {
+        console.error('Usage:');
+        console.error('  cf-memory-mcp delete <session-id-or-prefix>          # single delete');
+        console.error('  cf-memory-mcp delete --older-than 30d                # bulk delete by age');
+        console.error('  cf-memory-mcp delete --status abandoned              # bulk by status');
+        console.error('  cf-memory-mcp delete --repo /path/to/repo            # bulk by repo');
+        console.error('  Combine filters; use --yes to confirm >5 deletions.');
         process.exit(1);
     }
     const server = new CFMemoryMCP();
     server.logDebug = () => {};
     try {
-        // Resolve prefix to full id via get_context_bootstrap. The server's
-        // delete_session requires a full UUID (no implicit prefix).
+        if (bulkMode) {
+            const args = {};
+            if (flags.status) args.status = flags.status;
+            if (flags.older_than_days !== undefined) args.older_than_days = flags.older_than_days;
+            if (flags.repo_path) args.repo_path = flags.repo_path;
+
+            // Dry-run preview when --yes is missing. The server returns
+            // {deleted:false, deleted_count, deleted_session_ids[]} so the
+            // user can see what WOULD be deleted before committing.
+            if (!flags.yes) {
+                const previewRes = await server.makeRequest({
+                    jsonrpc: '2.0', id: `cli-delete-preview-${Date.now()}`,
+                    method: 'tools/call',
+                    params: { name: 'delete_session', arguments: { ...args, dry_run: true } },
+                });
+                const previewText = previewRes?.result?.content?.[0]?.text;
+                const preview = JSON.parse(previewText || '{}');
+                if (flags.json) {
+                    process.stdout.write(JSON.stringify({ ...preview, would_delete: true }, null, 2) + '\n');
+                    process.exit(2);
+                }
+                if (preview.deleted_count === 0) {
+                    process.stderr.write(`No sessions match the filters. Nothing to delete.\n`);
+                    process.exit(3);
+                }
+                process.stderr.write(`Would delete ${preview.deleted_count} session${preview.deleted_count === 1 ? '' : 's'}:\n`);
+                const previewIds = preview.deleted_session_ids || [];
+                for (const id of previewIds.slice(0, 10)) {
+                    process.stderr.write(`  ${id.slice(0, 8)}\n`);
+                }
+                if (previewIds.length > 10) {
+                    process.stderr.write(`  ... and ${preview.deleted_count - 10} more\n`);
+                }
+                process.stderr.write(`\nRe-run with --yes to confirm:\n`);
+                process.stderr.write(`  cf-memory-mcp delete ${process.argv.slice(3).join(' ')} --yes\n`);
+                process.exit(2);
+            }
+
+            const deleteRes = await server.makeRequest({
+                jsonrpc: '2.0', id: `cli-delete-bulk-${Date.now()}`,
+                method: 'tools/call',
+                params: { name: 'delete_session', arguments: args },
+            });
+            const deleteText = deleteRes?.result?.content?.[0]?.text;
+            const payload = JSON.parse(deleteText || '{}');
+            if (flags.json) {
+                process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+                process.exit(payload.deleted ? 0 : 3);
+            }
+            if (payload.deleted) {
+                process.stdout.write(`Deleted ${payload.deleted_count} session${payload.deleted_count === 1 ? '' : 's'} (and ${payload.cleaned_memories || 0} associated memories).\n`);
+                process.exit(0);
+            } else {
+                process.stderr.write(`No sessions matched the filters.\n`);
+                process.exit(3);
+            }
+            return;
+        }
+
+        // Single-delete path (existing).
         let fullId = idArg;
         if (idArg.length < 36) {
             const resolveRes = await server.makeRequest({
@@ -4207,8 +4328,12 @@ const PER_COMMAND_HELP = {
     --md <path>           Write the markdown to a file instead of stdout.
     --json, -j            Emit the full bootstrap payload as JSON for scripts.
   Exit codes: 0 = handoff found, 3 = no handoff found.`,
-    list: `cf-memory-mcp list [--limit N] [--json]
-  List recent handoffs for the current cwd, status-ranked.
+    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.
+    --status S            Restrict to a given status (in_progress, completed, ...).
+    --since ISO           Lower bound on handoff timestamp (ISO 8601).
+    --repo PATH           Override the cwd's repo (peek at another repo).
     --limit N, -n N       Max number of entries (default 5, max 50).
     --json, -j            Emit a JSON array for scripts.`,
     checkpoint: `cf-memory-mcp checkpoint ["<goal>"] [--force] [--json]
@@ -4245,11 +4370,15 @@ const PER_COMMAND_HELP = {
     completion: `cf-memory-mcp completion [bash|zsh|fish]
   Output shell completion script. Pipe to your shell's completion dir.`,
     delete: `cf-memory-mcp delete <session-id-or-prefix> [--json]
-  Delete a session row and its associated session_summary memories.
-    <session-id>          Full UUID or short prefix (>=8 chars). The CLI
-                          resolves prefix to a full id via the server.
-    --json, -j            Emit a JSON status object.
-  Exit codes: 0 = deleted, 3 = not found / could not resolve.`,
+  cf-memory-mcp delete [--status STATUS] [--older-than 30d] [--repo PATH] --yes [--json]
+  Delete session row(s) and any session_summary memories tied to them.
+    <session-id>          Single delete: full UUID or short prefix (>=8 chars).
+    --status STATUS       Bulk filter by status (abandoned, completed, ...).
+    --older-than 30d      Bulk filter by age (suffixes: d, h, m).
+    --repo PATH           Bulk filter by repo_path.
+    --yes, -y             Required for bulk delete to confirm intent.
+    --json, -j            Emit JSON.
+  Exit codes: 0 = deleted, 2 = bulk missing --yes, 3 = nothing matched.`,
     env: `cf-memory-mcp env [--json]
   Print all CF_MEMORY_* env vars the bridge reads, with their current
   values + descriptions. Useful for discovering knobs.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cf-memory-mcp",
-	"version": "3.31.0",
+	"version": "3.33.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": {