@cachly-dev/mcp-server 0.10.27 → 0.10.41

package/src/handlers/brain.ts

@@ -12,13 +12,15 @@ import { computeEmbedding, hasEmbedProvider, embedProviderHint, EMBED_PROVIDER }
 import { detectNamespace } from '../namespace.js';
 
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.10';
+const MCP_VERSION = '0.10.0';
 const WHATS_NEW: Record<string, string[]> = {
-  '0.10.10': [
+  '0.10.0': [
     `🆕 **What's new in v${MCP_VERSION}:**`,
-    `  📌 **pin_lesson / unpin_lesson** — Pin critical lessons to always show in session_start`,
-    `  📊 **brain_stats** — At-a-glance health dashboard (lessons, streak, roadmap, pinned, top topics)`,
-    `  ✅ Pinned lessons appear at top of every session briefing — never decay, never forgotten`,
+    `  ✅ Zero-friction setup — auto-provisions your Brain, no manual config needed`,
+    `  ✅ 10× faster briefings — batch Redis fetches replace per-key loops`,
+    `  ✅ Crash-proof data reads — corrupted cache entries no longer break tools`,
+    `  ✅ \`session_end\` warns when called without an active session`,
+    `  ✅ \`get_api_status\` now shows live Redis ping + all instance statuses`,
   ],
 };
 
@@ -340,20 +342,6 @@ export async function handleBrainTool(
         }
       } catch { /* CKG updates are non-critical */ }
 
-      // ── Auto-pin critical lessons ──────────────────────────────────────────
-      // severity=critical → always pin automatically so the lesson
-      // appears in every session_start without the user ever calling pin_lesson.
-      let autoPinNote = '';
-      if (severity === 'critical' && (outcome === 'success' || outcome === 'partial')) {
-        try {
-          const alreadyPinned = await redis.exists(`cachly:lesson:pin:${topic}`);
-          if (!alreadyPinned) {
-            await redis.set(`cachly:lesson:pin:${topic}`, '1');
-            autoPinNote = `📌 Auto-pinned (critical severity) — will appear in every session_start.`;
-          }
-        } catch { /* non-critical */ }
-      }
-
       const emoji = outcome === 'success' ? '✅' : outcome === 'partial' ? '⚠️' : '❌';
       const sevEmoji = severity === 'critical' ? '🔴' : severity === 'major' ? '🟡' : '🟢';
       const action = isUpdate ? 'updated' : 'stored';
@@ -374,7 +362,6 @@ export async function handleBrainTool(
         depends_on.length > 0
           ? `🔗 Depends on: ${depends_on.map(d => `\`${d}\``).join(', ')} → trace with \`trace_dependency\``
           : '',
-        autoPinNote,
         ...templateWarnings,
         ...iWasWrongWarning,
       ].filter(l => l !== '').join('\n');
@@ -430,8 +417,27 @@ export async function handleBrainTool(
           ? `📌 **You've looked this up 3 times.** Consider pinning it for instant access: add \`pinned: true\` via \`learn_from_attempts\` to always surface it first.`
           : '';
 
+        // ── Trust signal (today-safe consensus layer) ───────────────────────
+        // A lesson recalled many times — or confirmed by multiple distinct
+        // authors — has proven its value. Surface that as social proof.
+        const lessonAuthors = (lesson as { authors?: string[]; author?: string }).authors
+          ?? ((lesson as { author?: string }).author ? [(lesson as { author?: string }).author!] : []);
+        const distinctAuthors = [...new Set(lessonAuthors.filter(Boolean))];
+        const rc = updatedLesson.recall_count;
+        let trustBadge = '';
+        if (distinctAuthors.length >= 2 && rc >= 5) {
+          trustBadge = `🏆 **Battle-tested** — recalled ${rc}× · verified by ${distinctAuthors.length} developers. Trust this.`;
+        } else if (rc >= 10) {
+          trustBadge = `🏆 **Battle-tested** — recalled ${rc}×. This is one of your most-proven solutions.`;
+        } else if (distinctAuthors.length >= 2) {
+          trustBadge = `✅ **Team-verified** — confirmed by ${distinctAuthors.length} developers.`;
+        } else if (rc >= 5) {
+          trustBadge = `✅ **Proven** — recalled ${rc}× without contradiction.`;
+        }
+
         return [
           rememberWhen,
+          trustBadge,
           `${badge} **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}×`,
           ``,
           `**What worked:** ${lesson.what_worked}`,
@@ -747,20 +753,69 @@ export async function handleBrainTool(
       const isFirstSession = !lastSession && lessons.length === 0 && ctxCount === 0;
       if (isFirstSession) {
         lines.push('🎉 **Welcome! Your AI Brain is live.**', '');
-        lines.push('It learns from your work automatically. After your first session it will look like this:', '');
-        lines.push('  ✅ `api:auth` — Bearer token in header, not cookie; 401 on missing scope');
-        lines.push('  ✅ `database:migrations` — always run migrations before deploy');
-        lines.push('  ⚠️ `docker:build` — ARG changes bust all subsequent cache layers');
-        lines.push('');
-        lines.push('**3 steps to grow your brain:**');
-        lines.push('  1. Fix something → `learn_from_attempts(topic="bug:name", outcome="success", what_worked="...")`');
-        lines.push('  2. Save context → `remember_context(key="arch", value="...")`');
-        lines.push('  3. End session → `session_end(summary="What I did")`');
+        if (workspace_path) {
+          lines.push(`🚀 **Auto-bootstrapping from your git history...** (this takes a few seconds)`);
+          lines.push(`   Your brain will learn from your recent commits — no setup needed.`, '');
+        } else {
+          lines.push('It learns from your work automatically. After your first session it will look like this:', '');
+          lines.push('  ✅ `api:auth` — Bearer token in header, not cookie; 401 on missing scope');
+          lines.push('  ✅ `database:migrations` — always run migrations before deploy');
+          lines.push('  ⚠️ `docker:build` — ARG changes bust all subsequent cache layers');
+          lines.push('');
+          lines.push('**Tip:** Pass `workspace_path` to `session_start` to auto-learn from git history instantly.');
+          lines.push('');
+        }
+        lines.push('**Your brain grows automatically:**');
+        lines.push('  • End each session → `session_end(summary="What I did")` — auto-learns from git commits');
+        lines.push('  • After fixing bugs → `learn_from_attempts(topic="...", outcome="success", what_worked="...")`');
         lines.push('');
-        lines.push('💡 Run `brain_doctor` for a setup health-check and personalised tips.');
+        lines.push('💡 Run `brain_doctor` for a health-check and personalised tips.');
         lines.push('');
       }
 
+      // ── Team-virality: first-team-briefing wow moment ────────────────────
+      // When a user joins a team brain (has team lessons from colleagues but
+      // has never been briefed on them), show a dedicated "Welcome to your
+      // team's brain" section. Only fires once per user.
+      if (author && !isFirstSession) {
+        try {
+          const briefingKey = `cachly:team:first_briefing:${author}`;
+          const alreadyBriefed = await redis.get(briefingKey);
+          if (!alreadyBriefed) {
+            type LessonAny = typeof lessons[0] & { author?: string };
+            const teamLessons = (lessons as LessonAny[]).filter(l => l.author && l.author !== author);
+            if (teamLessons.length > 0) {
+              // Mark briefed so this only fires once
+              await redis.set(briefingKey, '1', 'EX', 365 * 86400);
+              const byAuthor = new Map<string, LessonAny[]>();
+              for (const l of teamLessons) {
+                const a = l.author!;
+                if (!byAuthor.has(a)) byAuthor.set(a, []);
+                byAuthor.get(a)!.push(l);
+              }
+              lines.push('');
+              lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+              lines.push('🤝 **Your team\'s AI brain has been briefing you.**');
+              lines.push('');
+              lines.push(`Your teammates have already solved problems you\'re about to hit:`);
+              lines.push('');
+              for (const [teamAuthor, tls] of byAuthor) {
+                lines.push(`  👤 **${teamAuthor}** fixed ${tls.length} thing${tls.length > 1 ? 's' : ''}:`);
+                for (const l of tls.slice(0, 2)) {
+                  const emoji = l.outcome === 'success' ? '✅' : '⚠️';
+                  lines.push(`    ${emoji} \`${l.topic}\` — ${l.what_worked.slice(0, 90)}`);
+                }
+                if (tls.length > 2) lines.push(`    … and ${tls.length - 2} more lessons`);
+              }
+              lines.push('');
+              lines.push(`💡 Use \`team_learn\` after your next fix to pay it forward.`);
+              lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+              lines.push('');
+            }
+          }
+        } catch { /* team briefing errors must never break session_start */ }
+      }
+
       // Handoff from previous window (if any)
       const handoffRaw = await redis.get('cachly:session:handoff');
       if (handoffRaw) {
@@ -946,45 +1001,42 @@ export async function handleBrainTool(
         lines.push('');
       }
 
-      // ── Pinned lessons — always shown regardless of age/confidence ───────────
-      try {
-        const pinKeys: string[] = [];
-        const pinStream = redis.scanStream({ match: 'cachly:lesson:pin:*', count: 100 });
-        await new Promise<void>((res, rej) => {
-          pinStream.on('data', (b: string[]) => pinKeys.push(...b));
-          pinStream.on('end', res);
-          pinStream.on('error', rej);
-        });
-        if (pinKeys.length > 0) {
-          const pinnedTopics = pinKeys.map(k => k.replace('cachly:lesson:pin:', ''));
-          const pinLessonRaws = await redis.mget(...pinnedTopics.map(t => `cachly:lesson:best:${t}`));
-          const pinLines: string[] = [];
-          for (const raw of pinLessonRaws) {
-            if (!raw) continue;
-            const l = safeJsonParse<{ topic: string; outcome: string; what_worked: string; severity?: string } | null>(raw, null);
-            if (!l) continue;
+      // Top lessons — sorted by recall_count desc (most-used = most proven value).
+      // If focus is set, focus-matched lessons already shown above; show remaining here.
+      if (lessons.length > 0) {
+        const byRecall = [...lessons].sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0));
+        const topRecalled = byRecall.filter(l => (l.recall_count ?? 0) > 0).slice(0, 3);
+        const remaining   = (focusLessons.length > 0 ? lessons.filter(l => !focusLessons.includes(l)) : lessons)
+          .filter(l => !topRecalled.includes(l))
+          .slice(0, focusLessons.length > 0 ? 3 : 4);
+
+        if (topRecalled.length > 0) {
+          lines.push(`🏆 **Most valuable** (recalled ${topRecalled[0]!.recall_count}× before):`);
+          for (const l of topRecalled) {
             const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
-            const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
-            pinLines.push(`  📌${emoji}${sev} \`${l.topic}\` — ${l.what_worked.slice(0, 100)}`);
-          }
-          if (pinLines.length > 0) {
-            lines.push(`📌 **Pinned lessons (always shown):**`);
-            lines.push(...pinLines);
-            lines.push('');
+            const sev   = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
+            const rc    = l.recall_count ?? 0;
+            const la     = (l as { authors?: string[]; author?: string }).authors
+              ?? ((l as { author?: string }).author ? [(l as { author?: string }).author!] : []);
+            const nAuthors = new Set(la.filter(Boolean)).size;
+            const trust  = (nAuthors >= 2 && rc >= 5) || rc >= 10 ? ' 🏆'
+              : nAuthors >= 2 || rc >= 5 ? ' ✅' : '';
+            const rct   = rc > 1 ? ` _(${rc}× recalled)_` : '';
+            lines.push(`  ${emoji}${sev}${trust} \`${l.topic}\`${rct} — ${l.what_worked.slice(0, 100)}`);
           }
+          lines.push('');
         }
-      } catch { /* non-critical */ }
 
-      // Recent lessons
-      if (lessons.length > 0) {
-        lines.push(`🕐 **Recent lessons:**`);
-        const toShow = focusLessons.length > 0 ? lessons.filter(l => !focusLessons.includes(l)).slice(0, 4) : lessons.slice(0, 5);
-        for (const l of toShow) {
-          const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
-          const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
-          lines.push(`  ${emoji}${sev} \`${l.topic}\` — ${l.what_worked.slice(0, 90)}`);
+        if (remaining.length > 0) {
+          const header = topRecalled.length > 0 ? `🕐 **Recent:**` : `🕐 **Recent lessons:**`;
+          lines.push(header);
+          for (const l of remaining) {
+            const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+            const sev   = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
+            lines.push(`  ${emoji}${sev} \`${l.topic}\` — ${l.what_worked.slice(0, 100)}`);
+          }
+          lines.push('');
         }
-        lines.push('');
       } else {
         lines.push('📭 No lessons yet. Use `learn_from_attempts` after solving tasks.', '');
       }
@@ -1461,19 +1513,32 @@ export async function handleBrainTool(
       }
 
       const durationStr = durationMin !== undefined ? ` · ${durationMin} min` : '';
-
-      // ── Mini brain-stats snapshot at session end ───────────────────────────
-      let miniStatsLines: string[] = [];
-      try {
-        const totalLessons = await redis.keys('cachly:lesson:best:*').then(k => k.length).catch(() => 0);
-        const pinCount = await redis.keys('cachly:lesson:pin:*').then(k => k.length).catch(() => 0);
-        const streakRaw = await redis.get('cachly:streak:current');
-        const streak = streakRaw ? (JSON.parse(streakRaw) as { days: number }).days : 0;
-        const parts: string[] = [`📚 ${totalLessons} lesson${totalLessons !== 1 ? 's' : ''} total`];
-        if (pinCount > 0) parts.push(`📌 ${pinCount} pinned`);
-        if (streak > 1) parts.push(`🔥 ${streak}-day streak`);
-        miniStatsLines = [`🧠 **Brain:** ${parts.join(' · ')}`];
-      } catch { /* non-critical */ }
+      const totalAutoLearned = autoLearned.length + ambientLearned.length;
+
+      // ── Shareable Session Summary Card ────────────────────────────────────────
+      // Generated after each session so the user can share their progress.
+      const tweetLines: string[] = [];
+      if (durationMin !== undefined && durationMin > 0) tweetLines.push(`⏱ ${durationMin} min session`);
+      if (totalAutoLearned > 0) tweetLines.push(`🧠 ${totalAutoLearned} lessons saved to Brain`);
+      if (files_changed.length > 0) tweetLines.push(`📁 ${files_changed.length} file${files_changed.length > 1 ? 's' : ''} changed`);
+      const tweetBody = tweetLines.length > 0
+        ? `${tweetLines.join(' · ')}\n\nMy AI Brain remembers this so I never repeat it. @cachlydev\ncachly.dev`
+        : `Session saved to my AI Brain. No more re-explaining this tomorrow. @cachlydev\ncachly.dev`;
+      const tweetURL = `https://twitter.com/intent/tweet?text=${encodeURIComponent(tweetBody)}`;
+
+      const sessionCard = [
+        ``,
+        `┌─────────────────────────────────────────────┐`,
+        `│  🧠 Session Summary Card                    │`,
+        `│  Share your progress — cached forever       │`,
+        `├─────────────────────────────────────────────┤`,
+        durationMin !== undefined ? `│  ⏱  Duration   : ${String(durationMin + ' min').padEnd(26)}│` : '',
+        totalAutoLearned > 0     ? `│  📚 Learned    : ${String(totalAutoLearned + ' lessons').padEnd(26)}│` : '',
+        files_changed.length > 0 ? `│  📁 Changed    : ${String(files_changed.length + ' file' + (files_changed.length > 1 ? 's' : '')).padEnd(26)}│` : '',
+        `├─────────────────────────────────────────────┤`,
+        `│  📣 Share: ${tweetURL.slice(0, 34).padEnd(34)}│`,
+        `└─────────────────────────────────────────────┘`,
+      ].filter(l => l !== '').join('\n');
 
       return [
         `✅ **Session saved**${durationStr}`,
@@ -1483,7 +1548,7 @@ export async function handleBrainTool(
         lessons_learned !== undefined ? `🧠 **Lessons stored:** ${lessons_learned}` : '',
         autoLearned.length > 0 ? `🤖 **Auto-learned:** ${autoLearned.length} lessons extracted from summary (${autoLearned.slice(0, 3).map(t => `\`${t}\``).join(', ')}${autoLearned.length > 3 ? '…' : ''})` : '',
         ambientLearned.length > 0 ? `🌿 **Ambient git learning:** ${ambientLearned.length} commit${ambientLearned.length > 1 ? 's' : ''} auto-learned (${ambientLearned.slice(0, 3).map(t => `\`${t}\``).join(', ')}${ambientLearned.length > 3 ? '…' : ''})` : '',
-        ...miniStatsLines,
+        sessionCard,
         ``,
         `💡 Next session: \`session_start(focus="...")\` to see this summary.`,
       ].filter(l => l !== '').join('\n');

package/src/handlers/fedbrain.ts

@@ -6,6 +6,7 @@ import { calculateConfidence, confidenceBadge, CONFIDENCE_WARN_VALUE, CONFIDENCE
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize } from '../search.js';
+import { safeJsonParse } from '../utils.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
 // Git concurrency semaphore (for brain_from_git parallel workers)
@@ -397,7 +398,8 @@ export async function handleFedbrainTool(
       const raw = await redis.get(`cachly:lesson:best:${lesson_key}`);
       if (!raw) return `❌ Lesson \`${lesson_key}\` not found. Store it first with \`learn_from_attempts\`.`;
 
-      const lesson = JSON.parse(raw) as { topic: string; outcome: string; what_worked: string; what_failed?: string; tags?: string[]; commands?: string[]; severity?: string; ts?: string };
+      const lesson = safeJsonParse(raw, null as null | { topic: string; outcome: string; what_worked: string; what_failed?: string; tags?: string[]; commands?: string[]; severity?: string; ts?: string });
+      if (!lesson) return `❌ Lesson \`${lesson_key}\` data is corrupted. Re-store with \`learn_from_attempts\`.`;
 
       const domainTokens = [lesson.topic.split(':')[0], ...(lesson.tags ?? [])].filter(Boolean);
       const domainFingerprint = [...new Set(domainTokens)].sort().join(',');
@@ -747,7 +749,8 @@ export async function handleFedbrainTool(
       }
 
       type Crystal = { label: string; ts: string; session_count: number; lesson_count: number; top_patterns: Array<{ category: string; insight: string; count: number }>; categories: string[]; created_from: string };
-      const crystal: Crystal = JSON.parse(raw);
+      const crystal = safeJsonParse<Crystal | null>(raw, null);
+      if (!crystal) return `❌ Memory Crystal data is corrupted. Re-create with \`memory_crystalize()\`.`;
       const age = Math.floor((Date.now() - new Date(crystal.ts).getTime()) / 86400000);
       const freshEmoji = age <= 7 ? '🟢' : age <= 30 ? '🟡' : '🔴';
 
@@ -784,49 +787,55 @@ export async function handleFedbrainTool(
       const crystalRaw = await redis.get('cachly:crystal:latest');
       if (crystalRaw) {
         type Crystal = { label: string; ts: string; session_count: number; lesson_count: number; top_patterns: Array<{ category: string; insight: string; count: number }> };
-        const crystal: Crystal = JSON.parse(crystalRaw);
-        lines.push(`### 💎 Memory Crystal: ${crystal.label}`);
-        lines.push(`Compressed from ${crystal.session_count} sessions, ${crystal.lesson_count} lessons.`);
-        const topN = focus
-          ? crystal.top_patterns.filter(p => p.category.toLowerCase().includes(focus.toLowerCase()) || p.insight.toLowerCase().includes(focus.toLowerCase())).slice(0, 4)
-          : crystal.top_patterns.slice(0, 4);
-        for (const p of topN) lines.push(`  • **${p.category}**: ${p.insight.slice(0, 100)}`);
-        lines.push('');
+        const crystal = safeJsonParse<Crystal | null>(crystalRaw, null);
+        if (crystal) {
+          lines.push(`### 💎 Memory Crystal: ${crystal.label}`);
+          lines.push(`Compressed from ${crystal.session_count} sessions, ${crystal.lesson_count} lessons.`);
+          const topN = focus
+            ? crystal.top_patterns.filter(p => p.category.toLowerCase().includes(focus.toLowerCase()) || p.insight.toLowerCase().includes(focus.toLowerCase())).slice(0, 4)
+            : crystal.top_patterns.slice(0, 4);
+          for (const p of topN) lines.push(`  • **${p.category}**: ${p.insight.slice(0, 100)}`);
+          lines.push('');
+        }
       }
 
       // 2. Last session summary
       const lastSession = await redis.get('cachly:session:last');
       if (lastSession) {
         type Session = { summary?: string; ts?: string; focus?: string };
-        const sess: Session = JSON.parse(lastSession);
-        lines.push(`### 🕐 Last Session`);
-        if (sess.focus) lines.push(`Focus: _${sess.focus}_`);
-        if (sess.summary) lines.push(`Summary: ${sess.summary.slice(0, 300)}`);
-        lines.push('');
+        const sess = safeJsonParse<Session | null>(lastSession, null);
+        if (sess) {
+          lines.push(`### 🕐 Last Session`);
+          if (sess.focus) lines.push(`Focus: _${sess.focus}_`);
+          if (sess.summary) lines.push(`Summary: ${sess.summary.slice(0, 300)}`);
+          lines.push('');
+        }
       }
 
       // 3. Session handoff
       const handoff = await redis.get('cachly:session:handoff');
       if (handoff) {
         type Handoff = { remaining_tasks?: string[]; instructions?: string; context_summary?: string; blocked_on?: string };
-        const h: Handoff = JSON.parse(handoff);
-        lines.push(`### 📋 Handoff (from last window)`);
-        if (h.context_summary) lines.push(`Context: ${h.context_summary.slice(0, 200)}`);
-        if (h.remaining_tasks?.length) {
-          lines.push(`Remaining tasks:`);
-          for (const t of h.remaining_tasks.slice(0, 5)) lines.push(`  • ${t}`);
+        const h = safeJsonParse<Handoff | null>(handoff, null);
+        if (h) {
+          lines.push(`### 📋 Handoff (from last window)`);
+          if (h.context_summary) lines.push(`Context: ${h.context_summary.slice(0, 200)}`);
+          if (h.remaining_tasks?.length) {
+            lines.push(`Remaining tasks:`);
+            for (const t of h.remaining_tasks.slice(0, 5)) lines.push(`  • ${t}`);
+          }
+          if (h.instructions) lines.push(`⚠️ Instructions: ${h.instructions.slice(0, 200)}`);
+          if (h.blocked_on) lines.push(`🚧 Blocked on: ${h.blocked_on}`);
+          lines.push('');
         }
-        if (h.instructions) lines.push(`⚠️ Instructions: ${h.instructions.slice(0, 200)}`);
-        if (h.blocked_on) lines.push(`🚧 Blocked on: ${h.blocked_on}`);
-        lines.push('');
       }
 
       // 4. WIP registry
       const wipRaw = await redis.get('cachly:ctx:wip-registry');
       if (wipRaw) {
         type Ctx = { content?: string };
-        const wip: Ctx = JSON.parse(wipRaw);
-        if (wip.content) {
+        const wip = safeJsonParse<Ctx | null>(wipRaw, null);
+        if (wip?.content) {
           lines.push(`### 🔧 WIP Registry`);
           lines.push(wip.content.slice(0, 400));
           lines.push('');
@@ -884,8 +893,8 @@ export async function handleFedbrainTool(
 
     // ── brain_from_git ────────────────────────────────────────────────────────
     case 'brain_from_git': {
-      const { instance_id, repo_path = '.', limit = 100, branch = 'HEAD', since = '' } = args as {
-        instance_id: string; repo_path?: string; limit?: number; branch?: string; since?: string;
+      const { instance_id, repo_path = '.', limit = 100, branch = 'HEAD', since = '', incremental = true } = args as {
+        instance_id: string; repo_path?: string; limit?: number; branch?: string; since?: string; incremental?: boolean;
       };
       const redis = await getConnection(instance_id);
       const { execSync } = await import('node:child_process');
@@ -904,9 +913,21 @@ export async function handleFedbrainTool(
         return `❌ Not a git repository: \`${repoDir}\`. Pass \`repo_path\` pointing to a git checkout.`;
       }
 
+      // Incremental mode: resume from last processed commit SHA
+      const lastShaKey = `cachly:brain_from_git:last_sha:${Buffer.from(repoDir).toString('base64').slice(0, 32)}`;
+      let lastSha = '';
+      let isIncremental = false;
+      if (incremental !== false && !since) {
+        lastSha = (await redis.get(lastShaKey)) ?? '';
+        isIncremental = Boolean(lastSha);
+      }
+
       // Build git log command
+      // In incremental mode, only fetch commits after the last processed SHA
       const sinceFlag = since ? `--since="${since}"` : '';
-      const logCmd = `git log ${branch} ${sinceFlag} --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n ${maxCommits}`;
+      const afterFlag = isIncremental ? `${lastSha}..HEAD` : '';
+      const revRange = afterFlag || branch;
+      const logCmd = `git log ${revRange} ${sinceFlag} --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n ${maxCommits}`;
 
       let logOutput = '';
       try {
@@ -921,6 +942,9 @@ export async function handleFedbrainTool(
       });
 
       if (commits.length === 0) {
+        if (isIncremental) {
+          return `✅ brain_from_git: Brain is up to date — no new commits since last run (last SHA: \`${lastSha.slice(0, 8)}\`).`;
+        }
         return `⚠️ No commits found in \`${repoDir}\` on branch \`${branch}\`${since ? ` since ${since}` : ''}.`;
       }
 
@@ -951,8 +975,21 @@ export async function handleFedbrainTool(
       let ingested = 0;
       let skipped = 0;
       const categoryCount = new Map<string, number>();
+      const total = commits.length;
+      const progressInterval = Math.max(1, Math.floor(total / 10)); // emit ~10 progress updates
+      let lastProgressAt = 0;
+
+      process.stderr.write(`\n🧠 brain_from_git: processing ${total} commits from ${repoDir}...\n`);
+
+      for (let i = 0; i < commits.length; i++) {
+        const commit = commits[i]!;
+
+        // Emit progress to stderr so editors can display it in MCP logs
+        if (i - lastProgressAt >= progressInterval) {
+          process.stderr.write(`   ⏳ Processing ${i}/${total} commits (${ingested} lessons so far)...\n`);
+          lastProgressAt = i;
+        }
 
-      for (const commit of commits) {
         if (!commit.subject) { skipped++; continue; }
         const { category, outcome, severity } = classifyCommit(commit.subject);
         const domain = extractDomain(commit.subject);
@@ -987,11 +1024,20 @@ export async function handleFedbrainTool(
         ingested++;
       }
 
+      process.stderr.write(`   ✅ brain_from_git complete: ${ingested}/${total} commits ingested\n\n`);
+
+      // Save the latest commit SHA for incremental runs
+      if (commits.length > 0 && commits[0]?.sha) {
+        await redis.set(lastShaKey, commits[0].sha, 'EX', 90 * 24 * 3600); // expire after 90 days
+      }
+
       const categoryBreakdown = [...categoryCount.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `  • **${k}** (${v})`).join('\n');
 
       return [
-        `🔁 **brain_from_git: ${repoDir}**`, '',
-        `📂 Branch: \`${branch}\`  |  Processed: **${commits.length}** commits  |  Ingested: **${ingested}** lessons  |  Skipped: ${skipped}`,
+        `🔁 **brain_from_git: ${repoDir}**`,
+        isIncremental ? `🔄 Incremental mode — only new commits since \`${lastSha.slice(0, 8)}\` were processed` : '',
+        ``,
+        `📂 Branch: \`${revRange}\`  |  Processed: **${commits.length}** commits  |  Ingested: **${ingested}** lessons  |  Skipped: ${skipped}`,
         ``,
         `**Breakdown by category:**`,
         categoryBreakdown,
@@ -999,7 +1045,8 @@ export async function handleFedbrainTool(
         `💡 New lessons are stored with confidence 0.55 (auto-inferred).`,
         `💡 As you confirm them via \`learn_from_attempts\`, confidence rises automatically.`,
         `🔍 Explore: \`brain_search(query="fix")\`  |  \`ckg_inspect(concept="deploy")\``,
-      ].join('\n');
+        `💾 Next run will automatically continue from the latest commit (incremental mode).`,
+      ].filter(Boolean).join('\n');
       } finally {
         _gitSemRelease();
       }
@@ -1026,12 +1073,14 @@ export async function handleFedbrainTool(
         for (const nk of nodeKeys.slice(0, 5)) {
           const nodeRaw = await redis.get(nk);
           if (!nodeRaw) continue;
-          const node: CKGNode = JSON.parse(nodeRaw);
+          const node = safeJsonParse<CKGNode | null>(nodeRaw, null);
+          if (!node) continue;
           const edgeKeys = await redis.smembers(`cachly:ckg:idx:from:${node.id}`);
           for (const ek of edgeKeys.slice(0, 20)) {
             const edgeRaw = await redis.get(ek);
             if (!edgeRaw) continue;
-            const edge: CKGEdge = JSON.parse(edgeRaw);
+            const edge = safeJsonParse<CKGEdge | null>(edgeRaw, null);
+            if (!edge) continue;
             if (edge.edgeType !== 'causes' && edge.edgeType !== 'degrades_under') continue;
 
             // Look up fix for this failure from CKG 'fixes' edges
@@ -1040,12 +1089,13 @@ export async function handleFedbrainTool(
             for (const fek of fixEdgeKeys.slice(0, 10)) {
               const feRaw = await redis.get(fek);
               if (!feRaw) continue;
-              const fe: CKGEdge = JSON.parse(feRaw);
+              const fe = safeJsonParse<CKGEdge | null>(feRaw, null);
+              if (!fe) continue;
               if (fe.edgeType === 'fixes') {
                 const lessonRaw = await redis.get(`cachly:lesson:best:${fe.from}`);
                 if (lessonRaw) {
-                  const lesson = JSON.parse(lessonRaw) as { what_worked?: string };
-                  fix = lesson.what_worked?.slice(0, 120);
+                  const lesson = safeJsonParse(lessonRaw, null as null | { what_worked?: string });
+                  fix = lesson?.what_worked?.slice(0, 120);
                   break;
                 }
               }

package/src/handlers/roadmap.ts

@@ -1,4 +1,5 @@
 import type { Redis } from 'ioredis';
+import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
@@ -67,7 +68,8 @@ export async function handleRoadmapTool(
       const redis = await getConnection(rid);
       const raw = await redis.hget(`cachly:roadmap:${rid}`, itemId);
       if (!raw) return `⚠️ **roadmap_update** – Item \`${itemId}\` not found. Use \`roadmap_list\` to see all items.`;
-      const item = JSON.parse(raw) as Record<string, unknown>;
+      const item = safeJsonParse<Record<string, unknown> | null>(raw, null);
+      if (!item) return `⚠️ **roadmap_update** – Item \`${itemId}\` data is corrupted. Re-add with \`roadmap_add\`.`;
       const oldStatus = item.status as string;
       if (newStatus) item.status = newStatus;
       if (newPriority) item.priority = newPriority;
@@ -106,7 +108,10 @@ export async function handleRoadmapTool(
       const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
       const STATUS_ICON: Record<string, string> = { planned: '📋', 'in-progress': '⚡', done: '✅', blocked: '🚫', cancelled: '🗑️' };
       const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
-      let items = Object.values(all).map(v => JSON.parse(v as string) as Record<string, string | string[]>);
+      let items = Object.values(all).flatMap(v => {
+        const item = safeJsonParse<Record<string, string | string[]> | null>(v as string, null);
+        return item ? [item] : [];
+      });
       // Filter
       if (filterStatus === 'open') items = items.filter(i => openStatuses.has(i.status as string));
       else if (filterStatus) items = items.filter(i => i.status === filterStatus);

package/src/handlers/syndicate.ts

@@ -4,6 +4,7 @@ import { calculateConfidence } from '../confidence.js';
 import { ckgSlug, ckgUpdateEdge } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize } from '../search.js';
+import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
@@ -292,7 +293,8 @@ export async function handleSyndicateTool(
         for (const ek of [...fromKeys, ...toKeys].slice(0, 50)) {
           const raw = await redis.get(ek);
           if (!raw) continue;
-          const edge: CKGEdge = JSON.parse(raw);
+          const edge = safeJsonParse<CKGEdge | null>(raw, null);
+          if (!edge) continue;
           allEdges.push(edge);
           if (hop < max_hops) {
             if (!visited.has(edge.from)) queue.push({ id: edge.from, hop: hop + 1 });
@@ -366,16 +368,18 @@ export async function handleSyndicateTool(
         for (const nk of nodeKeys.slice(0, 5)) {
           const nodeRaw = await redis.get(nk);
           if (!nodeRaw) continue;
-          const node: CKGNode = JSON.parse(nodeRaw);
+          const node = safeJsonParse<CKGNode | null>(nodeRaw, null);
+          if (!node) continue;
           const edgeKeys = await redis.smembers(`cachly:ckg:idx:from:${node.id}`);
           for (const ek of edgeKeys.slice(0, 20)) {
             const edgeRaw = await redis.get(ek);
             if (!edgeRaw) continue;
-            const edge: CKGEdge = JSON.parse(edgeRaw);
+            const edge = safeJsonParse<CKGEdge | null>(edgeRaw, null);
+            if (!edge) continue;
             // Only interested in fixes and co-occurs for prediction
             if (edge.edgeType !== 'fixes' && edge.edgeType !== 'co-occurs' && edge.edgeType !== 'causes') continue;
             const lessonRaw = await redis.get(`cachly:lesson:best:${edge.from}`);
-            const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
+            const lesson = lessonRaw ? safeJsonParse<{ what_worked?: string; topic: string } | null>(lessonRaw, null) ?? undefined : undefined;
             predictions.push({ concept: node.id, edgeType: edge.edgeType, target: edge.to, confidence: edge.confidence, lesson });
           }
         }
@@ -389,15 +393,17 @@ export async function handleSyndicateTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        try {
-          const l = JSON.parse(raw) as { topic: string; what_worked?: string; what_failed?: string; outcome: string; severity?: string; ts: string; verified_at?: string; recall_count?: number };
+        {
+          type PredLesson = { topic: string; what_worked?: string; what_failed?: string; outcome: string; severity?: string; ts: string; verified_at?: string; recall_count?: number };
+          const l = safeJsonParse<PredLesson | null>(raw, null);
+          if (!l) continue;
           const haystack = [l.topic, l.what_failed ?? '', l.what_worked ?? ''].join(' ').toLowerCase();
           const score = ctxTokens.reduce((s, t) => s + (haystack.includes(t) ? 1 : 0), 0);
           if (score >= 1 && l.outcome !== 'failure') {
             const conf = calculateConfidence(l);
             textPredictions.push({ ...l, confidence: conf });
           }
-        } catch { /* skip */ }
+        }
       }
       textPredictions.sort((a, b) => b.confidence - a.confidence);