@cachly-dev/mcp-server 0.10.4 → 0.10.6

package/src/handlers/advanced.ts

@@ -4,6 +4,7 @@ import { calculateConfidence, confidenceBadge, CONFIDENCE_STALE_VALUE, CONFIDENC
 import { ckgSlug, ckgUpdateEdge } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch } from '../search.js';
+import { safeJsonParse } from '../utils.js';
 
 type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
@@ -45,7 +46,8 @@ export async function handleAdvancedTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        try { lessons.set(k, JSON.parse(raw) as Lesson); } catch { /* skip malformed */ }
+        const lesson = safeJsonParse<Lesson | null>(raw, null);
+        if (lesson) lessons.set(k, lesson);
       }
 
       // Detect duplicates: same topic prefix (e.g. deploy:api vs deploy:api-v2)
@@ -166,8 +168,9 @@ export async function handleAdvancedTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        try {
-          const l = JSON.parse(raw) as Lesson;
+        {
+          const l = safeJsonParse<Lesson | null>(raw, null);
+          if (!l) continue;
           const ts = new Date(l.ts).getTime();
           if (ts >= sinceMs) {
             // Check history to determine add vs update
@@ -181,7 +184,7 @@ export async function handleAdvancedTool(
             // lessons with recalls as "active"
             recalled.push(l);
           }
-        } catch { /* skip */ }
+        }
       }
 
       const sinceLabel = match ? `last ${since}` : new Date(sinceMs).toLocaleDateString('de-DE');
@@ -215,10 +218,10 @@ export async function handleAdvancedTool(
       for (const rk of resolutionKeys) {
         const rr = await redis.get(rk);
         if (!rr) continue;
-        try {
-          const rn = JSON.parse(rr) as { topic?: string; resolution?: string; ts?: string };
-          if (rn.ts && new Date(rn.ts).getTime() >= sinceMs) recentResolutions.push({ topic: rn.topic ?? rk, resolution: rn.resolution ?? 'unknown', ts: rn.ts });
-        } catch { /* skip */ }
+        {
+          const rn = safeJsonParse<{ topic?: string; resolution?: string; ts?: string } | null>(rr, null);
+          if (rn?.ts && new Date(rn.ts).getTime() >= sinceMs) recentResolutions.push({ topic: rn.topic ?? rk, resolution: rn.resolution ?? 'unknown', ts: rn.ts });
+        }
       }
       if (recentResolutions.length > 0) {
         lines.push(`🗳️ **MADC Resolutions** (${recentResolutions.length} contested beliefs resolved):`);
@@ -238,8 +241,10 @@ export async function handleAdvancedTool(
 
       // 3. FedBrain transfers received in window
       const fedHistRaw = await redis.lrange('cachly:fedbrain:federations', -20, -1);
-      const recentFeds = fedHistRaw.map(r => { try { return JSON.parse(r) as { source: string; domain: string; transferred_at: string; nodes: number; edges: number }; } catch { return null; } })
-        .filter(f => f && new Date(f!.transferred_at).getTime() >= sinceMs) as Array<{ source: string; domain: string; transferred_at: string; nodes: number; edges: number }>;
+      type FedEntry = { source: string; domain: string; transferred_at: string; nodes: number; edges: number };
+      const recentFeds = fedHistRaw
+        .map(r => safeJsonParse<FedEntry | null>(r, null))
+        .filter((f): f is FedEntry => f !== null && new Date(f.transferred_at).getTime() >= sinceMs);
       if (recentFeds.length > 0) {
         lines.push(`🧠 **FedBrain transfers received (${recentFeds.length}):**`);
         for (const f of recentFeds.slice(0, 3)) {
@@ -282,27 +287,30 @@ export async function handleAdvancedTool(
           for (const nodeKey of nodeKeys.slice(0, 10)) {
             const nodeRaw = await redis.get(nodeKey);
             if (!nodeRaw) continue;
-            const node: CKGNode = JSON.parse(nodeRaw);
+            const node = safeJsonParse<CKGNode | null>(nodeRaw, null);
+            if (!node) continue;
             // Get edges from this node
             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 !== 'fixes' && edge.edgeType !== 'requires') continue;
               // Find lesson for this concept
               const lessonRaw = await redis.get(`cachly:lesson:best:${edge.from.replace(/-/g, ':').replace(/^fix:/, 'fix:')}`);
-              const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
-              ckgResults.push({ conceptId: node.id, edge, lesson });
+              const lesson = lessonRaw ? safeJsonParse<{ topic: string; what_worked?: string; ts: string; outcome: string; recall_count?: number; severity?: string } | null>(lessonRaw, null) ?? undefined : undefined;
+              ckgResults.push({ conceptId: node.id, edge, lesson: lesson ?? undefined });
             }
           }
           for (const ek of [...fromKeys, ...toKeys].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;
             const lessonRaw = await redis.get(`cachly:lesson:best:${edge.from}`);
-            const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
-            ckgResults.push({ conceptId: edge.from, edge, lesson });
+            const lesson = lessonRaw ? safeJsonParse<{ topic: string; what_worked?: string; ts: string; outcome: string; recall_count?: number; severity?: string } | null>(lessonRaw, null) ?? undefined : undefined;
+            ckgResults.push({ conceptId: edge.from, edge, lesson: lesson ?? undefined });
           }
         }
       } catch { /* CKG traversal non-critical */ }
@@ -336,14 +344,15 @@ export async function handleAdvancedTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        try {
-          const l = JSON.parse(raw) as Lesson;
+        {
+          const l = safeJsonParse<Lesson | null>(raw, null);
+          if (!l) continue;
           if (filterTags.length > 0 && !(l.tags ?? []).some((t: string) => filterTags.includes(t))) continue;
           const haystack = [l.topic, l.what_failed ?? '', l.what_worked ?? '', l.context ?? '']
             .join(' ').toLowerCase();
           const score = tokens.reduce((s, t) => s + (haystack.includes(t) ? 1 : 0), 0);
           if (score > 0) scored.push({ score, lesson: l, key: k });
-        } catch { /* skip */ }
+        }
       }
       scored.sort((a, b) => b.score - a.score);
       const chain = scored.slice(0, max_depth);
@@ -420,6 +429,10 @@ export async function handleAdvancedTool(
           lines.push(topSolution.what_worked.slice(0, 500));
           lines.push(`\`\`\``);
           lines.push('');
+
+          // Track estimated time saved — causal_trace finding a known fix is worth 1-4h
+          const savedMins = topSolution.severity === 'critical' ? 240 : topSolution.severity === 'major' ? 120 : 60;
+          redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => {});
         }
       }
 
@@ -452,8 +465,9 @@ export async function handleAdvancedTool(
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        try {
-          const l = JSON.parse(raw) as Lesson;
+        {
+          const l = safeJsonParse<Lesson | null>(raw, null);
+          if (!l) continue;
           const ageMs = now - new Date(l.ts).getTime();
           if (ageMs < minAgeMs) continue;
           const age_days = Math.floor(ageMs / 86400000);
@@ -470,7 +484,7 @@ export async function handleAdvancedTool(
           const confidence = Math.min(100, Math.max(0, base + recallBoost + outcomePenalty));
 
           scores.push({ topic: l.topic, confidence, age_days, recalls, outcome: l.outcome });
-        } catch { /* skip */ }
+        }
       }
 
       // Sort by lowest confidence first

package/src/handlers/brain.ts

@@ -3,6 +3,7 @@ import type { Redis } from 'ioredis';
 import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES,
          CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS } from '../confidence.js';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
+import { safeJsonParse } from '../utils.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein,
          ZERO_RESULTS_LOG, zeroResultsTotal, indexVocab as _indexVocab } from '../search.js';
@@ -10,6 +11,19 @@ import type { KeywordMatch } from '../search.js';
 import { computeEmbedding, hasEmbedProvider, embedProviderHint, EMBED_PROVIDER } from '../embeddings.js';
 import { detectNamespace } from '../namespace.js';
 
+// ── Changelog (shown once per version in session_start) ──────────────────────
+const MCP_VERSION = '0.10.0';
+const WHATS_NEW: Record<string, string[]> = {
+  '0.10.0': [
+    `🆕 **What's new in v${MCP_VERSION}:**`,
+    `  ✅ 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`,
+  ],
+};
+
 // Shared types used in brain handlers
 export interface Instance {
   id: string; name: string; tier: string; status: string; region: string;
@@ -167,7 +181,7 @@ export async function handleBrainTool(
       for (const dep of depends_on) {
         const depKey = `cachly:dep:${dep}`;
         const existing = await redis.get(depKey);
-        const depTopics: string[] = existing ? JSON.parse(existing) : [];
+        const depTopics: string[] = safeJsonParse<string[]>(existing, []);
         if (!depTopics.includes(topic)) depTopics.push(topic);
         await redis.set(depKey, JSON.stringify(depTopics));
       }
@@ -266,7 +280,8 @@ export async function handleBrainTool(
           for (const ek of existingEdgeKeys) {
             const er = await redis.get(ek);
             if (!er) continue;
-            const existEdge: CKGEdge = JSON.parse(er);
+            const existEdge = safeJsonParse<CKGEdge | null>(er, null);
+            if (!existEdge) continue;
             if (existEdge.edgeType === 'fixes' && existEdge.confidence > 0.7 && existEdge.trials >= 3) {
               beliefConflict = `⚠️ **belief_conflict** on \`${topic}\`: previously confirmed fix (confidence ${existEdge.confidence.toFixed(2)}, n=${existEdge.trials}) now reports failure. Both beliefs retained as \`contested\`. Use \`ckg_inspect(concept="${conceptId}")\` to review.`;
               // Store conflict marker
@@ -274,7 +289,7 @@ export async function handleBrainTool(
               await redis.set(conflictKey, JSON.stringify({ topic, detected_at: new Date().toISOString(), fix_confidence: existEdge.confidence, fix_trials: existEdge.trials, failure_outcome: outcome }), 'EX', 60 * 60 * 24 * 90);
               // Auto-trigger MADC deliberation in background — never blocks learn_from_attempts
               // Note: fire-and-forget; madc_deliberate is handled elsewhere in the switch
-              apiFetch(`/api/v1/instances/${instance_id}`).catch(() => undefined); // keep apiFetch warm
+              // (conflict marker stored above — no warm-up call needed)
             }
           }
         }
@@ -286,14 +301,16 @@ export async function handleBrainTool(
           for (const ek of fromEdgeKeys.slice(0, 10)) {
             const er = await redis.get(ek);
             if (!er) continue;
-            const e2: CKGEdge = JSON.parse(er);
+            const e2 = safeJsonParse<CKGEdge | null>(er, null);
+            if (!e2) continue;
             if (e2.edgeType !== 'fixes') continue;
             // Boost second-degree: edges from e2.to get a small fractional success
             const secondKeys = await redis.smembers(`cachly:ckg:idx:from:${e2.to}`);
             for (const sk of secondKeys.slice(0, 5)) {
               const sr = await redis.get(sk);
               if (!sr) continue;
-              const se: CKGEdge = JSON.parse(sr);
+              const se = safeJsonParse<CKGEdge | null>(sr, null);
+              if (!se) continue;
               if (se.edgeType !== 'co-occurs') continue;
               // Add 0.1 fractional success (second-degree signal)
               se.successes = (se.successes || 0) + 0.1;
@@ -314,7 +331,8 @@ export async function handleBrainTool(
           for (const ek of fromEdgeKeys) {
             const er = await redis.get(ek);
             if (!er) continue;
-            const de: CKGEdge = JSON.parse(er);
+            const de = safeJsonParse<CKGEdge | null>(er, null);
+            if (!de) continue;
             if (de.trials < 3 && de.last_updated && new Date(de.last_updated).getTime() < decayCutoff) {
               de.confidence = de.confidence * 0.9;
               de.last_updated = new Date().toISOString();
@@ -356,12 +374,13 @@ export async function handleBrainTool(
       // Try exact best-solution key first
       const best = await redis.get(`cachly:lesson:best:${topic}`);
       if (best) {
-        const lesson = JSON.parse(best) as {
+        const lesson = safeJsonParse(best, null as null | {
           topic: string; outcome: string; what_worked: string; what_failed?: string;
           context?: string; ts: string; verified_at?: string; severity?: string;
           file_paths?: string[]; commands?: string[]; tags?: string[];
           recall_count?: number; audit_trail?: unknown[];
-        };
+        });
+        if (!lesson) return `⚠️ Lesson data for \`${topic}\` is corrupted. Re-store it with \`learn_from_attempts\`.`;
 
         // ── Confidence decay check ───────────────────────────────────────────
         const confidence = calculateConfidence(lesson);
@@ -378,6 +397,10 @@ export async function handleBrainTool(
         };
         await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(updatedLesson));
 
+        // Track estimated time saved (30m minor · 60m major · 240m critical)
+        const savedMins = lesson.severity === 'critical' ? 240 : lesson.severity === 'major' ? 60 : 30;
+        redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => {});
+
         const sevEmoji = lesson.severity === 'critical' ? '🔴' : lesson.severity === 'major' ? '🟡' : lesson.severity ? '🟢' : '';
         const auditSummary = (lesson.audit_trail ?? []).length > 1
           ? `_Audit: ${(lesson.audit_trail ?? []).length} changes · stored ${new Date(lesson.ts).toLocaleDateString('de-DE')}_`
@@ -424,7 +447,7 @@ export async function handleBrainTool(
         const histKey = `cachly:lessons:${topic}`;
         const all = await redis.lrange(histKey, -3, -1);
         if (all.length > 0) {
-          const parsed = all.map(e => JSON.parse(e) as { outcome: string; what_worked: string; ts: string });
+          const parsed = all.map(e => safeJsonParse(e, null as null | { outcome: string; what_worked: string; ts: string })).filter(Boolean) as Array<{ outcome: string; what_worked: string; ts: string }>;
           const lines = parsed.map(p => `- ${p.outcome === 'success' ? '✅' : '❌'} ${p.what_worked.slice(0, 120)} (${new Date(p.ts).toLocaleDateString('de-DE')})`);
           return `⚠️ No successful solution for \`${topic}\` yet. Last attempts:\n\n${lines.join('\n')}`;
         }
@@ -436,7 +459,8 @@ export async function handleBrainTool(
       for (const k of matching.slice(0, 5)) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        const lesson = JSON.parse(raw) as { topic: string; what_worked: string; context?: string; ts: string };
+        const lesson = safeJsonParse(raw, null as null | { topic: string; what_worked: string; context?: string; ts: string });
+        if (!lesson) continue;
         results.push(`**\`${lesson.topic}\`** — ${lesson.what_worked.slice(0, 200)}`);
       }
       return `🔍 **Partial matches for \`${topic}\`:**\n\n${results.join('\n\n')}`;
@@ -597,10 +621,12 @@ export async function handleBrainTool(
         tags?: string[]; confidence?: number; audit_trail?: unknown[];
       };
       const lessons: Lesson[] = [];
-      for (const k of lessonKeys) {
-        const raw = await redis.get(k);
-        if (!raw) continue;
-        try { lessons.push(JSON.parse(raw) as Lesson); } catch { /* skip corrupt */ }
+      if (lessonKeys.length > 0) {
+        const raws = await redis.mget(...lessonKeys);
+        for (const raw of raws) {
+          const l = safeJsonParse<Lesson | null>(raw ?? null, null);
+          if (l) lessons.push(l);
+        }
       }
       lessons.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
 
@@ -617,10 +643,8 @@ export async function handleBrainTool(
 
       // 4. Last session
       const lastSessionRaw = await redis.get('cachly:session:last');
-      let lastSession: { summary: string; ts: string; files_changed?: string[]; duration_min?: number } | null = null;
-      if (lastSessionRaw) {
-        try { lastSession = JSON.parse(lastSessionRaw); } catch { /* ignore */ }
-      }
+      type LastSession = { summary: string; ts: string; files_changed?: string[]; duration_min?: number };
+      const lastSession = safeJsonParse<LastSession | null>(lastSessionRaw, null);
 
       // 5. Focus filtering
       const focusTerms = focus.toLowerCase().split(/\s+/).filter(Boolean);
@@ -639,7 +663,7 @@ export async function handleBrainTool(
       let streakMessage = '';
       try {
         const streakRaw = await redis.get('cachly:streak:current');
-        const streak = streakRaw ? JSON.parse(streakRaw) as { days: number; last_date: string; record: number } : null;
+        const streak = safeJsonParse<{ days: number; last_date: string; record: number } | null>(streakRaw, null);
         const today = new Date().toISOString().slice(0, 10);
         if (streak) {
           const lastDate = streak.last_date;
@@ -676,11 +700,54 @@ export async function handleBrainTool(
         provider,
       }), 'EX', 86400); // auto-expire after 24h if session_end never called
 
+      // 8. Time saved counter
+      let timeSavedMins = 0;
+      try {
+        const raw = await redis.get(`cachly:stats:time_saved_mins:${instance_id}`);
+        timeSavedMins = parseFloat(raw ?? '0');
+      } catch { /* non-critical */ }
+
       // ── Build briefing ──────────────────────────────────────────────────────
       const providerLabel = provider ? ` · ${provider}` : '';
       const lines: string[] = [`🧠 **Session Briefing**${providerLabel}`, ''];
       if (streakMessage) lines.push(streakMessage, '');
 
+      // Time saved (only show when meaningful — 30+ minutes)
+      if (timeSavedMins >= 30) {
+        const h = Math.floor(timeSavedMins / 60);
+        const m = Math.round(timeSavedMins % 60);
+        const timeStr = h > 0 ? `${h}h${m > 0 ? ` ${m}m` : ''}` : `${m}m`;
+        lines.push(`⏱️ **Brain saved you ~${timeStr} total** (time not re-researching known fixes)`, '');
+      }
+
+      // ── What's New (shown once per version update) ──────────────────────────
+      try {
+        const seenVersion = await redis.get('cachly:mcp:version:last_seen');
+        if (seenVersion !== MCP_VERSION) {
+          await redis.set('cachly:mcp:version:last_seen', MCP_VERSION, 'EX', 365 * 86400);
+          const changelog = WHATS_NEW[MCP_VERSION];
+          if (changelog) { lines.push(...changelog, ''); }
+        }
+      } catch { /* non-critical */ }
+
+      // ── First-time welcome (empty brain) ───────────────────────────────────
+      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")`');
+        lines.push('');
+        lines.push('💡 Run `brain_doctor` for a setup health-check and personalised tips.');
+        lines.push('');
+      }
+
       // Handoff from previous window (if any)
       const handoffRaw = await redis.get('cachly:session:handoff');
       if (handoffRaw) {
@@ -820,7 +887,8 @@ export async function handleBrainTool(
           for (const ck of conflictKeys.slice(0, 3)) {
             const cr = await redis.get(ck);
             if (!cr) continue;
-            const cf = JSON.parse(cr) as { topic: string; fix_confidence: number; fix_trials: number };
+            const cf = safeJsonParse<{ topic: string; fix_confidence: number; fix_trials: number } | null>(cr, null);
+            if (!cf) continue;
             lines.push(`  ⚠️ \`${cf.topic}\` — previously confirmed fix (${(cf.fix_confidence * 100).toFixed(0)}%, n=${cf.fix_trials}) now contradicted. Use \`ckg_inspect(concept="${ckgSlug(cf.topic)}")\``);
           }
           lines.push('');
@@ -879,6 +947,15 @@ export async function handleBrainTool(
         lines.push('📭 No lessons yet. Use `learn_from_attempts` after solving tasks.', '');
       }
 
+      // Team invite prompt — fires once after 10th lesson if no team use yet
+      if (lessons.length >= 10) {
+        const hasTeamUse = lessons.some(l => (l as typeof l & { author?: string }).author);
+        if (!hasTeamUse) {
+          lines.push(`🤝 **Your Brain has ${lessons.length} lessons — your team could benefit instantly.**`);
+          lines.push(`   Share: **cachly.dev/team** · or run \`team_learn\` after the next fix.`, '');
+        }
+      }
+
       // Open failures (lessons whose best-key has outcome != success)
       const openFailures = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial');
       if (openFailures.length > 0) {
@@ -975,17 +1052,17 @@ export async function handleBrainTool(
       try {
         const crystalRaw = await redis.get('cachly:crystal:latest');
         if (crystalRaw) {
-          const crystal = JSON.parse(crystalRaw) as {
-            label: string; ts: string; session_count: number;
-            top_patterns: Array<{ category: string; insight: string; count: number }>;
-          };
-          const crystalAge = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
-          if (crystalAge <= 90) {
-            lines.push(`💎 **Memory Crystal** (${crystal.label} · ${crystal.session_count} sessions compressed):`);
-            for (const p of crystal.top_patterns.slice(0, 3)) {
-              lines.push(`  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 90)}`);
+          type CrystalData = { label: string; ts: string; session_count: number; top_patterns: Array<{ category: string; insight: string; count: number }> };
+          const crystal = safeJsonParse<CrystalData | null>(crystalRaw, null);
+          if (crystal) {
+            const crystalAge = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
+            if (crystalAge <= 90) {
+              lines.push(`💎 **Memory Crystal** (${crystal.label} · ${crystal.session_count} sessions compressed):`);
+              for (const p of crystal.top_patterns.slice(0, 3)) {
+                lines.push(`  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 90)}`);
+              }
+              lines.push('');
             }
-            lines.push('');
           }
         }
       } catch { /* non-critical */ }
@@ -997,7 +1074,10 @@ export async function handleBrainTool(
           const PRIORITY_ORDER: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3 };
           const PRIORITY_ICON: Record<string, string> = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
           const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
-          const allItems = Object.values(roadmapAll).map(v => JSON.parse(v as string) as Record<string, unknown>);
+          const allItems = Object.values(roadmapAll).flatMap(v => {
+            const item = safeJsonParse<Record<string, unknown> | null>(v as string, null);
+            return item ? [item] : [];
+          });
           const openItems = allItems
             .filter(i => openStatuses.has(i.status as string))
             .sort((a, b) => {
@@ -1037,20 +1117,20 @@ export async function handleBrainTool(
             for (const nk of nodeKeys.slice(0, 3)) {
               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, 15)) {
                 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 !== 'co-occurs' && edge.edgeType !== 'fixes') continue;
                 if (edge.confidence < 0.35) continue;
-                // For "fixes" edges, the lesson is on the "from" node (fix for "to")
-                // For "causes" edges, target is the failure mode
                 const lessonKey = edge.edgeType === 'fixes' ? `cachly:lesson:best:${edge.from}` : `cachly:lesson:best:${edge.to}`;
                 const lessonRaw = await redis.get(lessonKey);
-                const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
-                ppePredictions.push({ concept: node.id, edgeType: edge.edgeType, target: edge.to, confidence: edge.confidence, lesson });
+                const lesson = safeJsonParse<{ what_worked?: string; topic: string } | null>(lessonRaw, null);
+                ppePredictions.push({ concept: node.id, edgeType: edge.edgeType, target: edge.to, confidence: edge.confidence, lesson: lesson ?? undefined });
               }
             }
           }
@@ -1081,7 +1161,7 @@ export async function handleBrainTool(
       // Measures: of recalled lessons with confidence > 0.85, what % had outcome=success?
       try {
         const calRaw = await redis.get('cachly:mcm:calibration:last');
-        const lastCalMs = calRaw ? JSON.parse(calRaw).ts : 0;
+        const lastCalMs = safeJsonParse<{ ts?: number } | null>(calRaw, null)?.ts ?? 0;
         const daysSinceCal = (Date.now() - lastCalMs) / 86_400_000;
         if (daysSinceCal >= 30 && lessons.length >= 5) {
           // Quick calibration pass on recalled lessons (recall_count > 0, outcome=success)
@@ -1125,8 +1205,6 @@ export async function handleBrainTool(
       } catch { /* non-critical */ }
 
       // ── 🌍 Knowledge Commons — community stats banner ───────────────────────
-      // Fetch syndication stats and show a 1-liner: total lessons + confirms + weekly growth.
-      // Non-fatal: never blocks session start if the API call fails.
       try {
         const commonsStats = await apiFetch<{
           total_lessons: number;
@@ -1143,6 +1221,17 @@ export async function handleBrainTool(
         }
       } catch { /* non-critical — never block session start */ }
 
+      // ── Brain Doctor hint (Punkt 6) — surface when brain needs attention ───
+      const hasOpenFailures = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial').length > 0;
+      const hasStaleLessons = lessons.some(l => l.outcome === 'success' && calculateConfidence(l) < CONFIDENCE_WARN_VALUE);
+      if (lessons.length === 0 || hasOpenFailures || hasStaleLessons) {
+        const reasons: string[] = [];
+        if (lessons.length === 0) reasons.push('brain is empty');
+        if (hasOpenFailures) reasons.push('open failures');
+        if (hasStaleLessons) reasons.push('stale lessons');
+        lines.push(`🩺 _Run \`brain_doctor\` to fix: ${reasons.join(', ')}._`);
+      }
+
       return lines.join('\n');
     }
 
@@ -1168,18 +1257,23 @@ export async function handleBrainTool(
       // Calculate duration from session_start marker
       let durationMin: number | undefined;
       const currentRaw = await redis.get('cachly:session:current');
-      if (currentRaw) {
-        try {
-          const current = JSON.parse(currentRaw) as { started: string };
-          durationMin = Math.round((now.getTime() - new Date(current.started).getTime()) / 60000);
-        } catch { /* ignore */ }
+      if (!currentRaw) {
+        return `⚠️ No active session found.\n\nRun \`session_start\` first to begin tracking a session, then call \`session_end\` when you're done.`;
+      }
+      const current = safeJsonParse<{ started: string } | null>(currentRaw, null);
+      if (current?.started) {
+        durationMin = Math.round((now.getTime() - new Date(current.started).getTime()) / 60000);
       }
 
       // ── Session Replay: capture decision log ─────────────────────────────
-      let decisionLog: Array<{ ts: string; topic: string; outcome: string; what_worked: string }> = [];
+      type DecisionEntry = { ts: string; topic: string; outcome: string; what_worked: string };
+      let decisionLog: DecisionEntry[] = [];
       try {
         const dlEntries = await redis.lrange('cachly:session:decision-log', 0, -1);
-        decisionLog = dlEntries.map(e => JSON.parse(e) as { ts: string; topic: string; outcome: string; what_worked: string });
+        decisionLog = dlEntries.flatMap(e => {
+          const entry = safeJsonParse<DecisionEntry | null>(e, null);
+          return entry ? [entry] : [];
+        });
         await redis.del('cachly:session:decision-log');
       } catch { /* non-critical */ }