cf-memory-mcp 3.13.0 → 3.14.0

package/bin/cf-memory-mcp.js

@@ -201,37 +201,74 @@ const TOOLS_LIST = [
     },
     {
         name: 'get_context_bootstrap',
-        description: 'Get the most important memories to load at session start. Returns user preferences, ongoing tasks, and relevant facts within the token budget. Includes an empty_hint pointing at store_memory when nothing is stored yet.',
+        description: 'Bootstrap a new chat with relevant memories. Pass {resume:true, repo_path, branch} to recover the latest handoff for this repo — returns resume_handoff (goal/status/files/next_steps/anchors), durable_context, active_code_context (with stale markers + refresh_hint), next_actions, and recent_handoffs alternates. Bridge auto-fills repo_path/branch/project_id from cwd + git so {resume:true} alone usually works.',
         inputSchema: {
             type: 'object',
             properties: {
-                max_tokens: { type: 'number', description: 'Token budget for bootstrap context (default: 1000)' },
-                current_context: { type: 'string', description: 'Current conversation context to bias relevance' }
+                max_tokens: { type: 'number', description: 'Token budget for bootstrap context (default: 4000)' },
+                priority_tags: { type: 'array', items: { type: 'string' }, description: 'Tags to prioritize when picking memories' },
+                recent_sessions: { type: 'number', description: 'Number of recent session summaries to include' },
+                current_context: { type: 'string', description: 'Current conversation context to bias relevance' },
+                resume: { type: 'boolean', description: 'When true, look up the prior matching handoff for repo_path/project_id and surface it under resume_handoff. Status-preferred (in_progress > completed) and time-decayed (older handoffs lose match_confidence).' },
+                repo_path: { type: 'string', description: 'Absolute project root path. Bridge auto-fills from cwd if omitted.' },
+                project_id: { type: 'string', description: 'Canonical project id (proj_...). Used before repo_path when set.' },
+                branch: { type: 'string', description: 'Current git branch. Mismatch downgrades match_confidence but does not hide. Bridge auto-fills from git.' },
+                session_id_hint: { type: 'string', description: 'Resume a specific session by id (overrides repo/branch matching). Useful after seeing recent_handoffs.' },
+                max_age_minutes: { type: 'number', description: 'Hard cutoff: hide handoffs older than this many minutes. Without it, older handoffs surface with reduced confidence.' }
             }
         }
     },
     {
         name: 'start_session',
-        description: 'Begin a new tracked conversation session. Returns a session_id used by end_session for summarization.',
+        description: 'Begin a new tracked session. Returns session_id. Optionally pass {include_prior_handoff:true} to also get the prior matching handoff inline (one-shot resume). Bridge auto-fills repo_path/branch/project_id from cwd + git.',
         inputSchema: {
             type: 'object',
             properties: {
                 context: { type: 'string', enum: ['main', 'group', 'background'], description: 'Session context type' },
-                platform: { type: 'string', description: 'Client platform (e.g., "claude-code", "claude-desktop")' }
+                platform: { type: 'string', description: 'Client platform (e.g., "claude-code", "claude-desktop")' },
+                repo_path: { type: 'string', description: 'Absolute project root path. Bridge auto-fills from cwd if omitted.' },
+                project_id: { type: 'string', description: 'Canonical project id (proj_...). Bridge auto-fills if known.' },
+                branch: { type: 'string', description: 'Current git branch. Bridge auto-fills from git if omitted.' },
+                goal: { type: 'string', description: 'One-sentence high-level goal for the session.' },
+                include_prior_handoff: { type: 'boolean', description: 'When true, also fetch the most-recent matching handoff and return it under prior_handoff. One round-trip resume.' }
             },
             required: ['context']
         }
     },
     {
         name: 'end_session',
-        description: 'End a tracked session and optionally extract memories from the summary.',
+        description: 'End a session and (optionally) persist a structured handoff so the next chat can resume via get_context_bootstrap({resume:true}). Pass {keep_open:true} to checkpoint mid-session (handoff written but ended_at stays null). The bridge auto-fills session_id from the implicit per-cwd cache when omitted, and synthesizes a minimal handoff from tracked tool activity when none provided.',
         inputSchema: {
             type: 'object',
             properties: {
-                session_id: { type: 'string', description: 'Session ID returned by start_session' },
-                summary: { type: 'string', description: 'Optional summary of what was discussed' }
-            },
-            required: ['session_id']
+                session_id: { type: 'string', description: 'Session ID returned by start_session. Bridge auto-fills from the implicit-per-cwd cache when omitted.' },
+                summary: { type: 'string', description: 'Free-form summary of what was discussed (separate from the structured handoff).' },
+                extract_memories: { type: 'boolean', description: 'Extract summary as a session_summary memory.' },
+                keep_open: { type: 'boolean', description: 'Mid-session checkpoint: persist the handoff but keep the session active (do not set ended_at). Call multiple times to update; final end_session without keep_open finalizes.' },
+                handoff: {
+                    type: 'object',
+                    description: 'Structured resume packet for the next chat window. Target 600-1500 tokens. Fields: goal (required), status (required), repo_path, project_id, branch, files_touched, files_read, decisions, blockers, commands_run, next_steps, code_anchors, notes. Bridge auto-fills repo_path/branch/project_id from cwd + git, and files_read from tracked tool activity.',
+                    properties: {
+                        goal: { type: 'string', description: 'What the user is trying to accomplish (one sentence).' },
+                        status: { type: 'string', enum: ['in_progress', 'blocked', 'completed', 'abandoned'], description: 'Current state of the work.' },
+                        repo_path: { type: 'string' },
+                        project_id: { type: 'string' },
+                        branch: { type: 'string' },
+                        files_touched: { type: 'array', description: 'Files materially edited.', items: { type: 'object', properties: { path: { type: 'string' }, why: { type: 'string' } }, required: ['path'] } },
+                        files_read: { type: 'array', description: 'Files read for context but not modified. Auto-filled by bridge if omitted.', items: { type: 'object', properties: { path: { type: 'string' }, why: { type: 'string' } }, required: ['path'] } },
+                        decisions: { type: 'array', items: { type: 'string' }, description: 'Decisions made and reasoning behind them.' },
+                        blockers: { type: 'array', items: { type: 'string' }, description: 'Open blockers preventing progress.' },
+                        commands_run: { type: 'array', items: { type: 'object', properties: { cmd: { type: 'string' }, result: { type: 'string', enum: ['pass', 'fail', 'unknown'] }, notes: { type: 'string' } }, required: ['cmd'] } },
+                        next_steps: { type: 'array', items: { type: 'string' }, description: 'Recommended next steps in priority order.' },
+                        code_anchors: { type: 'array', description: 'File/symbol anchors future agents should jump to first.', items: { type: 'object', properties: { file_path: { type: 'string' }, name: { type: 'string' }, lines: { type: 'string' }, why: { type: 'string' } }, required: ['file_path'] } },
+                        notes: { type: 'string', description: 'Free-form notes that did not fit elsewhere.' }
+                    },
+                    required: ['goal', 'status']
+                }
+            }
+            // No required fields: bridge auto-fills session_id from the
+            // implicit per-cwd cache, so an agent can call end_session({})
+            // and the bridge does the right thing.
         }
     },
     {
@@ -431,6 +468,15 @@ class CFMemoryMCP {
             // retrieve_context arrives, the cache is hot — no extra roundtrip.
             this.prewarmProjectIdCache();
 
+            // Background-fetch the resume handoff for this cwd. If the
+            // agent's first call is get_context_bootstrap({resume:true}),
+            // we serve from the warm cache instead of paying the round-trip.
+            // Opt out via CF_MEMORY_PREWARM_RESUME=off.
+            const prewarmResumeOpt = process.env.CF_MEMORY_PREWARM_RESUME;
+            if (!(prewarmResumeOpt === '0' || prewarmResumeOpt === 'false' || prewarmResumeOpt === 'off')) {
+                this.prewarmResumeContext();
+            }
+
             // Start auto-watcher if CF_MEMORY_AUTO_WATCH is set
             if (process.env.CF_MEMORY_AUTO_WATCH === '1' || process.env.CF_MEMORY_AUTO_WATCH === 'true') {
                 this.startAutoWatcher();
@@ -792,6 +838,20 @@ class CFMemoryMCP {
                 await this.maybeAttachResumeMetadata(message);
             }
 
+            // Resume prewarm: when the agent's first call is
+            // get_context_bootstrap({resume:true}), try to serve from the
+            // background-fetched cache instead of paying a real round-trip.
+            if (message.method === 'tools/call' &&
+                message.params?.name === 'get_context_bootstrap' &&
+                message.params.arguments?.resume) {
+                const cached = this.maybeServePrewarmedResume(message);
+                if (cached) {
+                    _mcpTrace('RESUME_PREWARM', `served get_context_bootstrap id=${message.id} from cache`);
+                    process.stdout.write(JSON.stringify(cached) + '\n');
+                    return;
+                }
+            }
+
             // Record which files the agent is touching so end_session can
             // auto-populate handoff.files_read. Cheap (in-memory Map), safe
             // (try/catch'd), and the agent's hand-written list always wins.
@@ -2152,6 +2212,19 @@ class CFMemoryMCP {
                         _mcpTrace('IMPLICIT_SESSION', `end_session using implicit session=${implicit}`);
                     }
                 }
+                // Auto-synthesize a minimal handoff when the agent didn't
+                // provide one but the bridge has observed file activity.
+                // Means even agents that don't follow the protocol leave
+                // useful resume state behind. Opt out with
+                // CF_MEMORY_AUTO_HANDOFF=off if the silent synthesis is
+                // surprising in a particular environment.
+                const autoHandoffEnv = process.env.CF_MEMORY_AUTO_HANDOFF;
+                const autoHandoffEnabled = !(autoHandoffEnv === '0' || autoHandoffEnv === 'false' || autoHandoffEnv === 'off');
+                if (autoHandoffEnabled && !args.handoff &&
+                    this._activityFiles && this._activityFiles.size > 0) {
+                    args.handoff = this.synthesizeMinimalHandoff();
+                    _mcpTrace('AUTO_HANDOFF', `synthesized for end_session session=${args.session_id||'?'} files=${this._activityFiles.size}`);
+                }
                 if (args.handoff && typeof args.handoff === 'object') {
                     const meta = this.getRepoMetadata();
                     if (!args.handoff.repo_path && meta.repo_path) args.handoff.repo_path = meta.repo_path;
@@ -2324,6 +2397,118 @@ class CFMemoryMCP {
         }
     }
 
+    /**
+     * Build a minimal handoff packet from observed bridge activity. Used by
+     * end_session auto-synthesis and the periodic auto-checkpoint. Returns
+     * just the fields the bridge can credibly populate — agent-supplied
+     * fields like decisions/blockers are intentionally omitted so a future
+     * resume reader can tell the difference between "agent wrote this" and
+     * "bridge synthesized this".
+     */
+    synthesizeMinimalHandoff() {
+        const handoff = {
+            // The status is necessarily a guess. We use 'in_progress' as the
+            // default because a synthesized handoff usually means "agent
+            // didn't explicitly finish" — agents who finish properly will
+            // provide their own handoff.
+            status: 'in_progress',
+        };
+        if (this._lastRetrieveQuery) {
+            handoff.goal = `Recent activity: ${this._lastRetrieveQuery.slice(0, 160)}`;
+        } else if (this._activityFiles && this._activityFiles.size > 0) {
+            const topFile = Array.from(this._activityFiles.entries())
+                .sort((a, b) => b[1].count - a[1].count)[0];
+            handoff.goal = topFile
+                ? `Bridge-synthesized: most-touched file was ${topFile[0]}`
+                : 'Bridge-synthesized handoff (no explicit goal)';
+        } else {
+            handoff.goal = 'Bridge-synthesized handoff (no explicit goal)';
+        }
+        handoff.notes = `Auto-synthesized by cf-memory-mcp bridge. Agent did not provide a handoff. Tool calls observed: ${this._toolCallCount || 0}. Set CF_MEMORY_AUTO_HANDOFF=off to disable.`;
+        return handoff;
+    }
+
+    /**
+     * Pre-fetch the resume handoff for the current cwd at bridge startup.
+     * The result is cached and surfaced when the agent's first call is
+     * get_context_bootstrap({resume:true}). Reduces first-call latency
+     * from one full bootstrap round-trip to nearly zero.
+     *
+     * Failures are silent — this is purely an optimization. If pre-warming
+     * fails (no handoff, network error), the regular bootstrap path still
+     * works.
+     */
+    async prewarmResumeContext() {
+        try {
+            const meta = this.getRepoMetadata();
+            if (!meta.repo_path) return;
+            const args = { resume: true, repo_path: meta.repo_path };
+            if (meta.branch) args.branch = meta.branch;
+            const fake = { params: { name: 'retrieve_context', arguments: {} } };
+            await this.maybeFillProjectId(fake);
+            if (fake.params.arguments.project_id) args.project_id = fake.params.arguments.project_id;
+
+            const t0 = Date.now();
+            const response = await this.makeRequest({
+                jsonrpc: '2.0',
+                id: `prewarm-resume-${Date.now()}`,
+                method: 'tools/call',
+                params: { name: 'get_context_bootstrap', arguments: args },
+            });
+            const elapsed = Date.now() - t0;
+            // Cache the response keyed by the args it was made for so we
+            // can serve a subsequent identical request directly.
+            this._prewarmedResume = {
+                args,
+                response,
+                fetched_at: Date.now(),
+            };
+            const text = response?.result?.content?.[0]?.text;
+            let handoff_present = false;
+            try {
+                const parsed = JSON.parse(text || '{}');
+                handoff_present = !!parsed.resume_handoff;
+            } catch (_) { /* ignore */ }
+            _mcpTrace('RESUME_PREWARM', `elapsed=${elapsed}ms handoff_present=${handoff_present}`);
+        } catch (err) {
+            this.logDebug(`prewarmResumeContext failed: ${err && err.message}`);
+        }
+    }
+
+    /**
+     * Serve a get_context_bootstrap call from the prewarm cache when the
+     * args match. Cache is dropped on first use so a stale prewarm never
+     * masks a real change. Returns the cached response or null.
+     */
+    maybeServePrewarmedResume(message) {
+        try {
+            if (!this._prewarmedResume) return null;
+            if (message?.params?.name !== 'get_context_bootstrap') return null;
+            const args = message.params.arguments || {};
+            if (!args.resume) return null;
+            // Stale cutoff: prewarm older than 30s is too stale to trust.
+            const ageMs = Date.now() - this._prewarmedResume.fetched_at;
+            if (ageMs > 30_000) {
+                this._prewarmedResume = null;
+                return null;
+            }
+            // Match on the resume-defining fields. Different repo_path or
+            // session_id_hint means different question — re-fetch.
+            const cached = this._prewarmedResume.args;
+            if ((args.repo_path || cached.repo_path) && args.repo_path !== cached.repo_path) return null;
+            if (args.project_id && args.project_id !== cached.project_id) return null;
+            if (args.session_id_hint) return null; // never serve a specific-session ask from cache
+            const cachedResp = this._prewarmedResume.response;
+            this._prewarmedResume = null; // single-use
+            // Rebind the response id to match the actual request id so the
+            // client can correlate it.
+            return { ...cachedResp, id: message.id };
+        } catch (err) {
+            this.logDebug(`maybeServePrewarmedResume failed: ${err && err.message}`);
+            return null;
+        }
+    }
+
     /**
      * Fire-and-forget auto-checkpoint. Every N tool calls, if there's an
      * active implicit session AND there's been meaningful activity, send a

package/package.json

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