cf-memory-mcp 3.17.0 → 3.19.0

package/bin/cf-memory-mcp.js

@@ -213,8 +213,10 @@ const TOOLS_LIST = [
                 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.' }
+                session_id_hint: { type: 'string', description: 'Resume a specific session by id (overrides repo/branch matching). Full UUID or short prefix (>=8 chars). 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.' },
+                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.' }
             }
         }
     },
@@ -944,7 +946,27 @@ class CFMemoryMCP {
             // (try/catch'd), and the agent's hand-written list always wins.
             this.trackToolActivity(message);
 
-            let response = await this.makeRequest(message);
+            let response;
+            try {
+                response = await this.makeRequest(message);
+            } catch (err) {
+                // Network failure / worker unreachable. For resume bootstrap
+                // calls, serve from local disk so the agent isn't stuck
+                // when Cloudflare is down or the user is offline.
+                if (message.method === 'tools/call' &&
+                    message.params?.name === 'get_context_bootstrap' &&
+                    message.params.arguments?.resume) {
+                    const fallback = this.loadResumeFromDisk(message.id);
+                    if (fallback) {
+                        _mcpTrace('DISPATCH_DONE', `id=${message.id} method=${message.method} fallback=disk elapsed=${Date.now()-_t0}ms`);
+                        process.stdout.write(JSON.stringify(fallback) + '\n');
+                        return;
+                    }
+                }
+                // Not a resume call, or no disk fallback available: surface
+                // the original error to the client.
+                throw err;
+            }
             _mcpTrace('DISPATCH_DONE', `id=${message.id} method=${message.method} elapsed=${Date.now()-_t0}ms`);
 
             // Annotate retrieve_context results with local staleness when
@@ -987,14 +1009,21 @@ class CFMemoryMCP {
                 this.cacheImplicitSessionFromResponse(response);
             }
 
-            // Inject bridge-side git diff into resume responses. Lets the
-            // agent see what's changed in the repo since the handoff was
-            // written — files modified, commits added, branch moves —
-            // without having to call git themselves.
+            // Resume bootstrap: if the server returned an error envelope
+            // (not just a fetch failure), try the disk fallback. Then
+            // run the normal diff injection + disk persist for success.
             if (message.method === 'tools/call' &&
                 message.params?.name === 'get_context_bootstrap' &&
                 message.params.arguments?.resume) {
+                if (response?.error) {
+                    const fallback = this.loadResumeFromDisk(message.id);
+                    if (fallback) {
+                        response = fallback;
+                    }
+                }
                 this.injectRepoDiffIntoResume(response);
+                // Persist to disk for offline fallback on the next call.
+                this.saveResumeToDisk(response);
             }
 
             // Send response to stdout
@@ -2637,10 +2666,63 @@ class CFMemoryMCP {
         // sees the recent trajectory ("what was I doing").
         const timelineNote = this.formatActivityTimeline();
         const baseNote = `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.`;
-        handoff.notes = timelineNote ? `${baseNote}\n\nRecent activity:\n${timelineNote}` : baseNote;
+
+        // Workspace state: uncommitted changes + recent commits give the
+        // next chat real signal about what's been happening in the repo,
+        // not just what tools the agent called.
+        const workspaceState = this.getGitWorkspaceState();
+        const sections = [baseNote];
+        if (timelineNote) sections.push(`Recent activity:\n${timelineNote}`);
+        if (workspaceState) sections.push(`Workspace state:\n${workspaceState}`);
+        handoff.notes = sections.join('\n\n');
         return handoff;
     }
 
+    /**
+     * Snapshot the local git workspace: uncommitted file count, top
+     * changed files, last 3 commit messages. Used by auto-synthesized
+     * handoffs so the next chat sees real workspace state, not just
+     * tool-call activity. Best-effort: returns "" when git unavailable.
+     */
+    getGitWorkspaceState() {
+        try {
+            const meta = this.getRepoMetadata();
+            if (!meta.repo_path) return '';
+            const { execSync } = require('child_process');
+            const run = (cmd) => execSync(cmd, {
+                cwd: meta.repo_path,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: 500,
+            });
+            const lines = [];
+            // Uncommitted: `git status --porcelain` is one line per changed file.
+            try {
+                const status = run('git status --porcelain').trim();
+                if (status) {
+                    const files = status.split('\n').slice(0, 8);
+                    const more = status.split('\n').length > 8 ? ` (+ ${status.split('\n').length - 8} more)` : '';
+                    lines.push(`  Uncommitted changes:${more}`);
+                    files.forEach(f => lines.push(`    ${f}`));
+                } else {
+                    lines.push('  Working tree clean.');
+                }
+            } catch (_) { /* git status failed */ }
+            // Last 3 commits — short hash + subject only.
+            try {
+                const log = run('git log -3 --pretty=format:%h\\ %s').trim();
+                if (log) {
+                    lines.push('  Recent commits:');
+                    log.split('\n').forEach(c => lines.push(`    ${c}`));
+                }
+            } catch (_) { /* git log failed */ }
+            return lines.join('\n');
+        } catch (err) {
+            this.logDebug(`getGitWorkspaceState failed: ${err && err.message}`);
+            return '';
+        }
+    }
+
     /**
      * Condense an MCP tool call into a single-line summary. Used for the
      * activity timeline so the synthesized handoff includes "what was I
@@ -2690,6 +2772,92 @@ class CFMemoryMCP {
             .join('\n');
     }
 
+    /**
+     * Local-disk cache for the resume packet. Path is
+     *   ~/.cf-memory/handoff-<sha256-prefix-of-cwd>.json
+     * Used as a fallback when the worker is unreachable (network down,
+     * Cloudflare outage). Refreshed on every successful resume fetch.
+     */
+    getDiskCachePath() {
+        try {
+            const cwd = process.env.CF_MEMORY_WATCH_PATH || process.cwd();
+            const crypto = require('crypto');
+            const hash = crypto.createHash('sha256').update(cwd).digest('hex').slice(0, 16);
+            const dir = path.join(os.homedir(), '.cf-memory');
+            return path.join(dir, `handoff-${hash}.json`);
+        } catch (_) { return null; }
+    }
+
+    /**
+     * Persist a resume bootstrap response to local disk. Called after
+     * a successful resume fetch (prewarm or live). Fire-and-forget;
+     * disk errors are non-fatal.
+     */
+    saveResumeToDisk(response) {
+        try {
+            const optOut = process.env.CF_MEMORY_DISK_CACHE;
+            if (optOut === '0' || optOut === 'false' || optOut === 'off') return;
+            const p = this.getDiskCachePath();
+            if (!p) return;
+            const text = response?.result?.content?.[0]?.text;
+            if (!text) return;
+            // Only persist when there's actually a handoff to cache.
+            try {
+                const parsed = JSON.parse(text);
+                if (!parsed?.resume_handoff) return;
+            } catch (_) { return; }
+            const dir = path.dirname(p);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const entry = {
+                cached_at: new Date().toISOString(),
+                cwd: process.env.CF_MEMORY_WATCH_PATH || process.cwd(),
+                response_text: text,
+            };
+            fs.writeFileSync(p, JSON.stringify(entry, null, 2));
+            _mcpTrace('DISK_CACHE', `saved resume packet to ${p}`);
+        } catch (err) {
+            this.logDebug(`saveResumeToDisk failed: ${err && err.message}`);
+        }
+    }
+
+    /**
+     * Load the most-recent disk-cached resume packet for the current cwd.
+     * Returns a response-shaped object the bridge can write to stdout, or
+     * null when nothing cached / disk unreadable. The returned envelope
+     * is tagged with a `from_disk_cache:true` marker + `disk_cache_age`
+     * so the agent knows this is a fallback, not a fresh fetch.
+     */
+    loadResumeFromDisk(messageId) {
+        try {
+            const p = this.getDiskCachePath();
+            if (!p || !fs.existsSync(p)) return null;
+            const entry = JSON.parse(fs.readFileSync(p, 'utf8'));
+            const parsed = JSON.parse(entry.response_text);
+            const cachedAt = entry.cached_at;
+            const ageMinutes = Math.round((Date.now() - new Date(cachedAt).getTime()) / 60000);
+            // Annotate the envelope so the agent knows it's fallback.
+            if (parsed.resume_handoff) {
+                parsed.resume_handoff.from_disk_cache = true;
+                parsed.resume_handoff.disk_cache_age_minutes = ageMinutes;
+                parsed.resume_handoff.disk_cache_cached_at = cachedAt;
+            }
+            // Replace empty_hint with one that explains the fallback.
+            parsed.empty_hint = `Worker unreachable; served from local disk cache (cached ${ageMinutes} min ago at ${cachedAt}). Refresh by calling get_context_bootstrap when the worker is back online.`;
+            const response = {
+                jsonrpc: '2.0',
+                id: messageId,
+                result: { content: [{ type: 'text', text: JSON.stringify(parsed) }] },
+            };
+            _mcpTrace('DISK_CACHE', `served resume from disk (age=${ageMinutes}min)`);
+            return response;
+        } catch (err) {
+            this.logDebug(`loadResumeFromDisk failed: ${err && err.message}`);
+            return null;
+        }
+    }
+
     /**
      * 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
@@ -2731,6 +2899,8 @@ class CFMemoryMCP {
                 const parsed = JSON.parse(text || '{}');
                 handoff_present = !!parsed.resume_handoff;
             } catch (_) { /* ignore */ }
+            // Persist to disk for offline fallback. Best-effort.
+            if (handoff_present) this.saveResumeToDisk(response);
             _mcpTrace('RESUME_PREWARM', `elapsed=${elapsed}ms handoff_present=${handoff_present}`);
         } catch (err) {
             this.logDebug(`prewarmResumeContext failed: ${err && err.message}`);

package/package.json

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