@cachly-dev/mcp-server 0.10.48 → 0.10.50

package/src/handlers/brain.ts

@@ -8,19 +8,28 @@ import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein,
          ZERO_RESULTS_LOG, zeroResultsTotal, indexVocab as _indexVocab } from '../search.js';
 import type { KeywordMatch } from '../search.js';
+import { rerankByQuality } from '../rerank.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 MCP_VERSION = '0.10.50';
 const WHATS_NEW: Record<string, string[]> = {
-  '0.10.0': [
+  '0.10.50': [
     `🆕 **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`,
+    `  ✅ \`smart_recall\` — unified keyword + semantic hybrid list (one ranked result, not two sections)`,
+    `  ✅ \`smart_recall\` — "Brain saved you here" banner surfaces time saved inline per proven lesson`,
+    `  ✅ Quality reranking — proven successes outrank symptom-dense failures (+11% Precision@1)`,
+    `  ✅ Cachly-Bench — IR benchmark with CI regression guard (see BENCH.md for the proof)`,
+    `  🔧 Contradiction resolution now persisted to Redis (90-day TTL)`,
+    `  💡 Run \`smart_recall\` to see your Brain's recall quality in action`,
+  ],
+  '0.10.49': [
+    `  ✅ \`brain_from_git\` — auto-seed your Brain from git history in seconds`,
+    `  ✅ \`brain_predict_failures\` — predict CI/build failures before they happen`,
+    `  ✅ VS Code extension — Brain status bar, ambient learning, CodeLens hints`,
+    `  ✅ Team Brain — share lessons across your whole engineering team`,
+    `  🔧 Stability — auto-expiring memory keys, longer provisioning wait, robust recall`,
   ],
 };
 
@@ -138,6 +147,18 @@ export async function handleBrainTool(
               const resId = ckgSlug(`resolution:${topic}`);
               await ckgUpdateEdge(redis, cId, 'contradicts', resId, false);
             } catch { /* non-critical */ }
+            // Persist a queryable resolution record — so contradiction history survives
+            // (CKG edges alone aren't easily auditable). Bounded + TTL'd like other history.
+            try {
+              const resolutionKey = `cachly:contradictions:${topic}`;
+              const direction = prev.outcome === 'success' && outcome === 'failure'
+                ? 'kept-success' : 'overwrote-failure';
+              await redis.rpush(resolutionKey, JSON.stringify({
+                ts, prev_outcome: prev.outcome, new_outcome: outcome, direction,
+              }));
+              await redis.ltrim(resolutionKey, -50, -1);
+              await redis.expire(resolutionKey, 180 * 86400);
+            } catch { /* non-critical */ }
             contradictionWarning.push(`🗳️ Run \`madc_deliberate(topic="${topic}")\` to resolve via expert agent voting.`);
           }
         } catch { /* ignore parse error */ }
@@ -183,7 +204,7 @@ export async function handleBrainTool(
         const existing = await redis.get(depKey);
         const depTopics: string[] = safeJsonParse<string[]>(existing, []);
         if (!depTopics.includes(topic)) depTopics.push(topic);
-        await redis.set(depKey, JSON.stringify(depTopics));
+        await redis.set(depKey, JSON.stringify(depTopics), 'EX', 90 * 86400);
       }
 
       const lessonObj = {
@@ -207,9 +228,11 @@ export async function handleBrainTool(
       };
       const lesson = JSON.stringify(lessonObj);
 
-      // Always append to the history list (audit log)
+      // Always append to the history list (audit log); keep last 100 entries, 90-day TTL
       const listKey = `cachly:lessons:${topic}`;
       await redis.rpush(listKey, lesson);
+      await redis.ltrim(listKey, -100, -1);
+      await redis.expire(listKey, 90 * 86400);
 
       // Update best key for success/partial; for failure only update if no success exists
       if (outcome === 'success' || outcome === 'partial') {
@@ -417,8 +440,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}`,
@@ -476,65 +518,48 @@ export async function handleBrainTool(
       const redis = await getConnection(instance_id);
 
       // ── Layer 1: Keyword search across ALL brain data (always works, no embedding) ──
-      const kwMatches = await keywordSearch(
+      const rawMatches = await keywordSearch(
         redis,
         ['cachly:ctx:*', 'cachly:lesson:best:*', 'cachly:idx:*'],
         query,
         10,
       );
 
-      const lines: string[] = [`🧠 **Smart Recall** for: _"${query}"_\n`];
-
-      // Show sub-query info if multi-topic was detected
-      const subQueries = splitMultiQuery(query);
-      if (subQueries.length > 1) {
-        lines.push(`_Detected ${subQueries.length} sub-topics:_ ${subQueries.map((s, i) => `${i + 1}. "${s}"`).join(', ')}\n`);
-      }
-
-      if (kwMatches.length > 0) {
-        lines.push(`### 🔍 BM25 Matches (${kwMatches.length})\n`);
+      // ── Layer 1.5: Quality-aware rerank — proven success lessons outrank
+      // text-similar failed attempts (the moat; see src/rerank.ts + Cachly-Bench). ──
+      const kwMatches = rerankByQuality(rawMatches);
 
-        // Group by sub-query if multi-topic
-        if (subQueries.length > 1) {
-          const grouped = new Map<string, KeywordMatch[]>();
-          for (const m of kwMatches.slice(0, 12)) {
-            const sq = m.subQuery ?? query;
-            if (!grouped.has(sq)) grouped.set(sq, []);
-            grouped.get(sq)!.push(m);
-          }
-          for (const [sq, matches] of grouped) {
-            lines.push(`**Topic: "${sq}"** (${matches.length} results)\n`);
-            for (const m of matches.slice(0, 4)) {
-              const label = m.key
-                .replace('cachly:ctx:', '📝 ')
-                .replace('cachly:lesson:best:', '💡 ')
-                .replace('cachly:idx:', '📂 ');
-              const preview = m.content.slice(0, 300).replace(/\n/g, ' ');
-              lines.push(`  **${label}** _(BM25: ${m.score.toFixed(2)}, matched: ${m.matchedWords.join(', ')})_`);
-              lines.push(`  > ${preview}${m.content.length > 300 ? '…' : ''}\n`);
+      // Increment recall_count on matched lessons (fire-and-forget) + collect "Brain saved you here" signal.
+      type RecalledLesson = { topic: string; severity: string; recall_count: number; savedMins: number };
+      const savedHere: RecalledLesson[] = [];
+      const lessonMatches = kwMatches.filter(m => m.key.startsWith('cachly:lesson:best:'));
+      for (const m of lessonMatches.slice(0, 5)) {
+        const existing = await redis.get(m.key).catch(() => null);
+        if (existing) {
+          const lesson = safeJsonParse(existing, null as null | { recall_count?: number; outcome?: string; severity?: string; [k: string]: unknown });
+          if (lesson) {
+            const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: new Date().toISOString() };
+            redis.set(m.key, JSON.stringify(updated)).catch(() => {});
+            const sev = lesson.severity as string;
+            const savedMins = sev === 'critical' ? 240 : sev === 'major' ? 60 : 30;
+            redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => {});
+            // Surface banner for proven successes (recall_count >= 1 means it's been validated)
+            if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1) {
+              savedHere.push({
+                topic: m.key.replace('cachly:lesson:best:', ''),
+                severity: sev ?? 'major',
+                recall_count: (lesson.recall_count ?? 0) + 1,
+                savedMins,
+              });
             }
           }
-          // Summary: which sub-queries had matches
-          const matched = [...grouped.keys()];
-          const unmatched = subQueries.filter(sq => !matched.includes(sq));
-          if (unmatched.length > 0) {
-            lines.push(`\n⚠️ **No results for:** ${unmatched.map(s => `"${s}"`).join(', ')}`);
-          }
-        } else {
-          for (const m of kwMatches.slice(0, 8)) {
-            const label = m.key
-              .replace('cachly:ctx:', '📝 ')
-              .replace('cachly:lesson:best:', '💡 ')
-              .replace('cachly:idx:', '📂 ');
-            const preview = m.content.slice(0, 400).replace(/\n/g, ' ');
-            lines.push(`**${label}** _(BM25: ${m.score.toFixed(2)}, matched: ${m.matchedWords.join(', ')})_`);
-            lines.push(`> ${preview}${m.content.length > 400 ? '…' : ''}\n`);
-          }
         }
       }
 
-      // ── Layer 2: Semantic search (optional, only if embedding provider + vector_token available) ──
+      // ── Layer 2: Semantic search (parallel, optional) ────────────────────────
       const inst = await apiFetch<Instance>(`/api/v1/instances/${instance_id}`);
+      type SemHit = { key: string; similarity: number; content: string };
+      const semHits: SemHit[] = [];
       if (inst.vector_token && hasEmbedProvider()) {
         try {
           const embedding = await computeEmbedding(query);
@@ -544,22 +569,15 @@ export async function handleBrainTool(
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ embedding, namespace: 'cachly:ctx', threshold, top_k: 5 }),
           });
-
           if (searchRes.ok) {
             const results = (await searchRes.json()) as SemanticSearchResponse[];
-            const semHits = results.filter(r => r.found && r.id);
-            if (semHits.length > 0) {
-              lines.push(`\n### 🎯 Semantic Matches (${semHits.length})\n`);
-              for (const hit of semHits) {
-                const parts = hit.id!.replace('ctx:', '').split(':');
-                const category = parts[0];
-                const key = parts.slice(1).join(':');
-                const content = await redis.get(`cachly:ctx:${category}:${key}`);
-                lines.push(
-                  `**${key}** _(${((hit.similarity ?? 0) * 100).toFixed(0)}% similar)_`,
-                  `> ${content?.slice(0, 300) ?? '(evicted)'}${(content?.length ?? 0) > 300 ? '…' : ''}\n`,
-                );
-              }
+            for (const hit of results.filter(r => r.found && r.id)) {
+              const parts = hit.id!.replace('ctx:', '').split(':');
+              const category = parts[0];
+              const key = parts.slice(1).join(':');
+              const redisKey = `cachly:ctx:${category}:${key}`;
+              const content = await redis.get(redisKey).catch(() => null);
+              semHits.push({ key: redisKey, similarity: hit.similarity ?? 0, content: content ?? '(evicted)' });
             }
           }
         } catch {
@@ -567,7 +585,106 @@ export async function handleBrainTool(
         }
       }
 
-      if (kwMatches.length === 0) {
+      // ── Layer 3: Hybrid merge — one unified ranked list ──────────────────────
+      // BM25 quality scores (already reranked) are re-normalized to [0,1] for merging.
+      type HybridResult = {
+        key: string; content: string; hybridScore: number;
+        bm25Score?: number; semScore?: number; matchedWords?: string[];
+        matchType: 'keyword' | 'semantic' | 'hybrid'; subQuery?: string;
+      };
+
+      const bm25Scores = kwMatches.map(m => m.score);
+      const bm25Min = bm25Scores.length ? Math.min(...bm25Scores) : 0;
+      const bm25Range = bm25Scores.length ? (Math.max(...bm25Scores) - bm25Min) || 1 : 1;
+      const bm25Norm = (s: number) => (s - bm25Min) / bm25Range;
+
+      const hybridMap = new Map<string, HybridResult>();
+      for (const m of kwMatches) {
+        const n = bm25Norm(m.score);
+        hybridMap.set(m.key, {
+          key: m.key, content: m.content, bm25Score: n,
+          hybridScore: n * (semHits.length > 0 ? 0.7 : 1.0),
+          matchedWords: m.matchedWords, matchType: 'keyword', subQuery: m.subQuery,
+        });
+      }
+      for (const hit of semHits) {
+        const existing = hybridMap.get(hit.key);
+        if (existing) {
+          existing.semScore = hit.similarity;
+          existing.hybridScore = (existing.bm25Score ?? 0) * 0.6 + hit.similarity * 0.4;
+          existing.matchType = 'hybrid';
+        } else {
+          hybridMap.set(hit.key, {
+            key: hit.key, content: hit.content, semScore: hit.similarity,
+            hybridScore: hit.similarity * 0.5, matchType: 'semantic',
+          });
+        }
+      }
+      const hybridResults = [...hybridMap.values()].sort((a, b) => b.hybridScore - a.hybridScore);
+
+      // ── Build output ──────────────────────────────────────────────────────────
+      const lines: string[] = [`🧠 **Smart Recall** for: _"${query}"_\n`];
+
+      // "Brain saved you here" banner — surfaces value inline for proven recalled lessons
+      const SORDER: Record<string, number> = { critical: 0, major: 1, minor: 2 };
+      const topLesson = savedHere.sort((a, b) => (SORDER[a.severity] ?? 1) - (SORDER[b.severity] ?? 1))[0];
+      if (topLesson) {
+        lines.push(`> 💡 **Brain saved you ~${topLesson.savedMins}m here** — ${topLesson.severity} issue from \`${topLesson.topic}\` recalled ${topLesson.recall_count}× proven\n`);
+      }
+
+      // Show sub-query info if multi-topic was detected
+      const subQueries = splitMultiQuery(query);
+      if (subQueries.length > 1) {
+        lines.push(`_Detected ${subQueries.length} sub-topics:_ ${subQueries.map((s, i) => `${i + 1}. "${s}"`).join(', ')}\n`);
+      }
+
+      if (hybridResults.length > 0) {
+        const modeLabel = semHits.length > 0
+          ? `keyword + semantic hybrid`
+          : `keyword`;
+        lines.push(`### 🔍 Results (${hybridResults.length} — ${modeLabel})\n`);
+
+        // Group by sub-query for multi-topic queries
+        if (subQueries.length > 1) {
+          const grouped = new Map<string, HybridResult[]>();
+          for (const r of hybridResults.slice(0, 12)) {
+            const sq = r.subQuery ?? query;
+            if (!grouped.has(sq)) grouped.set(sq, []);
+            grouped.get(sq)!.push(r);
+          }
+          for (const [sq, results] of grouped) {
+            lines.push(`**Topic: "${sq}"** (${results.length} results)\n`);
+            for (const r of results.slice(0, 4)) {
+              const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
+              const scorePart = r.matchType === 'hybrid'
+                ? `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🔀 hybrid`
+                : r.matchType === 'semantic'
+                ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
+                : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
+              const preview = r.content.slice(0, 300).replace(/\n/g, ' ');
+              lines.push(`  **${label}** _(${scorePart})_`);
+              lines.push(`  > ${preview}${r.content.length > 300 ? '…' : ''}\n`);
+            }
+          }
+          const matched = [...grouped.keys()];
+          const unmatched = subQueries.filter(sq => !matched.includes(sq));
+          if (unmatched.length > 0) {
+            lines.push(`\n⚠️ **No results for:** ${unmatched.map(s => `"${s}"`).join(', ')}`);
+          }
+        } else {
+          for (const r of hybridResults.slice(0, 8)) {
+            const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
+            const scorePart = r.matchType === 'hybrid'
+              ? `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🔀 hybrid`
+              : r.matchType === 'semantic'
+              ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`
+              : `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, matched: ${r.matchedWords?.join(', ')}`;
+            const preview = r.content.slice(0, 400).replace(/\n/g, ' ');
+            lines.push(`**${label}** _(${scorePart})_`);
+            lines.push(`> ${preview}${r.content.length > 400 ? '…' : ''}\n`);
+          }
+        }
+      } else {
         lines.push(`⚠️ No matches found for: "${query}"`);
 
         // Did-You-Mean: find nearest token in index vocab
@@ -897,6 +1014,31 @@ export async function handleBrainTool(
       // Brain health
       lines.push(`📊 **Brain:** ${lessons.length} lessons · ${ctxCount} context entries`, '');
 
+      // ── 📌 Proven Laws — auto-crystallized lessons (quick win 3) ─────────────
+      // A lesson that has proven itself (recalled ≥ CRYSTALLIZE_RECALLS times) or
+      // was explicitly pinned becomes a "law" — surfaced at the top of every
+      // briefing so the most battle-tested knowledge is never buried. This is
+      // the today-safe version of swarm crystallization: enough confirmations
+      // auto-promote a lesson without any manual step.
+      {
+        type LessonPin = typeof lessons[0] & { pinned?: boolean };
+        const CRYSTALLIZE_RECALLS = 5;
+        const laws = (lessons as LessonPin[])
+          .filter(l => l.outcome === 'success' && (l.pinned === true || (l.recall_count ?? 0) >= CRYSTALLIZE_RECALLS))
+          .sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0))
+          .slice(0, 5);
+        if (laws.length > 0) {
+          lines.push(`📌 **Proven Laws** (auto-crystallized — your most-trusted knowledge):`);
+          for (const l of laws) {
+            const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
+            const rc  = l.recall_count ?? 0;
+            const why = l.pinned === true ? 'pinned' : `recalled ${rc}×`;
+            lines.push(`  🏆${sev} \`${l.topic}\` _(${why})_ — ${l.what_worked.slice(0, 100)}`);
+          }
+          lines.push('');
+        }
+      }
+
       // ── Layer 7: MCM Domain Coverage Map ────────────────────────────────────
       if (lessons.length >= 3) {
         const domainMap = new Map<string, { total: number; success: number; critical: number }>();
@@ -996,8 +1138,14 @@ export async function handleBrainTool(
           for (const l of topRecalled) {
             const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
             const sev   = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
-            const rct   = l.recall_count && l.recall_count > 1 ? ` _(${l.recall_count}× recalled)_` : '';
-            lines.push(`  ${emoji}${sev} \`${l.topic}\`${rct} — ${l.what_worked.slice(0, 100)}`);
+            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('');
         }
@@ -1065,27 +1213,63 @@ export async function handleBrainTool(
       }
 
       // ── 🔮 Predictive Pre-Warning — intent-based danger detection ────────────
-      // Fires BEFORE work starts. If focus area has known failure patterns → warn loudly.
-      if (focusTerms.length > 0) {
+      // Fires BEFORE work starts. Uses explicit focus when given; otherwise
+      // derives the likely work area from the last session's changed files +
+      // summary (you usually keep working where you left off). This makes the
+      // warning fire even when the caller forgets to pass `focus`.
+      {
         type LessonAny = typeof lessons[0] & { author?: string; tags?: string[] };
-        const dangerLessons = (lessons as LessonAny[]).filter(l => {
-          if (l.outcome === 'success') return false;
-          const topicCategory = l.topic.split(':')[0];
-          return focusTerms.some(term =>
-            l.topic.toLowerCase().includes(term) ||
-            topicCategory === term ||
-            (l.tags ?? []).some((t: string) => t.toLowerCase() === term),
-          );
-        });
-        if (dangerLessons.length >= 1) {
-          // Insert warning block right after the title line (index 1 = blank line after title)
-          const warning = [
-            `🚨 **PRE-WARNING** — Read this BEFORE starting:`,
-            `  Known pitfalls for **"${focus}"** (${dangerLessons.length} past failure${dangerLessons.length > 1 ? 's' : ''}):`,
-            ...dangerLessons.slice(0, 3).map(l => `  ❌ \`${l.topic}\` — ${(l.what_failed ?? l.what_worked).slice(0, 80)}`),
-            '',
-          ];
-          lines.splice(2, 0, ...warning); // after '🧠 **Session Briefing**' + empty line
+
+        // Common path noise / extensions to drop when deriving terms from files.
+        const PATH_NOISE = new Set([
+          'src', 'lib', 'test', 'tests', 'dist', 'index', 'main', 'app',
+          'internal', 'pkg', 'cmd', 'node_modules', 'components', 'utils',
+          'ts', 'tsx', 'js', 'jsx', 'go', 'py', 'rs', 'java', 'json', 'yaml', 'yml',
+        ]);
+        const deriveTermsFromFiles = (files: string[]): string[] => {
+          const terms = new Set<string>();
+          for (const f of files) {
+            for (const seg of f.toLowerCase().split(/[/\\._-]/)) {
+              if (seg.length > 3 && !PATH_NOISE.has(seg)) terms.add(seg);
+            }
+          }
+          return [...terms];
+        };
+
+        let warnTerms = focusTerms;
+        let warnLabel = focus;
+        let derived = false;
+        if (warnTerms.length === 0 && lastSession) {
+          const fromFiles = deriveTermsFromFiles(lastSession.files_changed ?? []);
+          const fromSummary = (lastSession.summary ?? '').toLowerCase()
+            .replace(/[^a-z0-9\s:_-]/g, ' ').split(/\s+/).filter(t => t.length > 3 && !PATH_NOISE.has(t));
+          warnTerms = [...new Set([...fromFiles, ...fromSummary])];
+          warnLabel = 'where you left off last session';
+          derived = true;
+        }
+
+        if (warnTerms.length > 0) {
+          const dangerLessons = (lessons as LessonAny[]).filter(l => {
+            if (l.outcome === 'success') return false;
+            const topicCategory = l.topic.split(':')[0];
+            return warnTerms.some(term =>
+              l.topic.toLowerCase().includes(term) ||
+              topicCategory === term ||
+              (l.tags ?? []).some((t: string) => t.toLowerCase() === term),
+            );
+          });
+          if (dangerLessons.length >= 1) {
+            const headline = derived
+              ? `  You're likely to continue **${warnLabel}** — ${dangerLessons.length} known pitfall${dangerLessons.length > 1 ? 's' : ''} there:`
+              : `  Known pitfalls for **"${warnLabel}"** (${dangerLessons.length} past failure${dangerLessons.length > 1 ? 's' : ''}):`;
+            const warning = [
+              `🚨 **PRE-WARNING** — Read this BEFORE starting:`,
+              headline,
+              ...dangerLessons.slice(0, 3).map(l => `  ❌ \`${l.topic}\` — ${(l.what_failed ?? l.what_worked).slice(0, 80)}`),
+              '',
+            ];
+            lines.splice(2, 0, ...warning); // after '🧠 **Session Briefing**' + empty line
+          }
         }
       }
 

package/src/handlers/context.ts

@@ -64,13 +64,18 @@ export async function handleContextTool(
           if (ttl && ttl > 0) {
             body['expires_at'] = new Date(Date.now() + ttl * 1000).toISOString();
           }
-          await fetch(`${vectorUrl}/entries`, {
+          const res = await fetch(`${vectorUrl}/entries`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(body),
-          }).catch(() => undefined);
-        } catch {
-          // Embedding optional — continue silently
+            signal: AbortSignal.timeout(8000),
+          });
+          if (!res.ok) {
+            process.stderr.write(`[cachly] semantic index skipped (HTTP ${res.status}) — smart_recall on this context will be keyword-only\n`);
+          }
+        } catch (e) {
+          // Embedding is optional — keyword recall still works. Log so it's debuggable.
+          process.stderr.write(`[cachly] semantic index failed: ${e instanceof Error ? e.message : String(e)} — smart_recall on this context will be keyword-only\n`);
         }
       }
 

package/src/handlers/fedbrain.ts

@@ -9,6 +9,9 @@ import { keywordSearch, tokenize } from '../search.js';
 import { safeJsonParse } from '../utils.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
+// Last brain_from_git category counts — set after each run so index.ts can include them in telemetry
+export let _lastBrainFromGitCounts: { fixes: number; features: number; refactors: number; total: number } | null = null;
+
 // Git concurrency semaphore (for brain_from_git parallel workers)
 let _gitSemCount = 0;
 const _GIT_SEM_MAX = 10;
@@ -363,8 +366,6 @@ export async function handleFedbrainTool(
 
       if (hooksArr.includes('ci')) {
         lines.push(`### GitHub Actions CI outcome hook`);
-        lines.push(`**Setup:** add a repo secret \`CACHLY_CACHE_TOKEN\` = your instance's cache token`);
-        lines.push(`(find it via \`get_connection_string\` — the token in the cache URL).`);
         lines.push(`**Add at the end of each job** (after build/test steps):`);
         lines.push('```yaml');
         lines.push(`- name: cachly CLS — record CI outcome`);
@@ -372,14 +373,15 @@ export async function handleFedbrainTool(
         lines.push(`  run: |`);
         lines.push(`    node -e "`);
         lines.push(`    const r=require('https');`);
-        lines.push(`    const d=JSON.stringify({source:'ci_outcome',payload:{`);
+        lines.push(`    const d=JSON.stringify({instance_id:'${instance_id}',source:'ci_outcome',payload:{`);
         lines.push(`      status:'\${{ job.status }}',prev_status:'unknown',job:'\${{ github.job }}',`);
         lines.push(`      context:'github-actions run \${{ github.run_number }}'}});`);
-        lines.push(`    r.request({hostname:'api.cachly.dev',path:'/v1/cache/'+process.env.CACHLY_CACHE_TOKEN+'/cls/ingest',method:'POST',`);
-        lines.push(`      headers:{'Content-Type':'application/json','Content-Length':d.length}},()=>{}).end(d);`);
+        lines.push(`    r.request({hostname:'api.cachly.dev',path:'/api/v1/cls/ingest',method:'POST',`);
+        lines.push(`      headers:{'Content-Type':'application/json','Authorization':'Bearer $CACHLY_JWT',`);
+        lines.push(`        'Content-Length':d.length}},()=>{}).end(d);`);
         lines.push(`    " 2>/dev/null || true`);
         lines.push(`  env:`);
-        lines.push(`    CACHLY_CACHE_TOKEN: \${{ secrets.CACHLY_CACHE_TOKEN }}`);
+        lines.push(`    CACHLY_JWT: \${{ secrets.CACHLY_JWT }}`);
         lines.push('```');
         lines.push('');
       }
@@ -1013,11 +1015,16 @@ export async function handleFedbrainTool(
         // Only store if no existing lesson for this topic (avoid overwriting higher-confidence lessons)
         const existing = await redis.get(`cachly:lesson:best:${topic}`);
         if (!existing) {
-          await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(lessonObj));
+          // Auto-inferred git lessons get a 90-day TTL — they self-refresh on the next
+          // brain_from_git run, and shouldn't pin memory forever if the repo goes stale.
+          await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(lessonObj), 'EX', 90 * 86400);
           await redis.rpush(`cachly:lessons:${topic}`, JSON.stringify(lessonObj));
+          await redis.ltrim(`cachly:lessons:${topic}`, -100, -1);
+          await redis.expire(`cachly:lessons:${topic}`, 90 * 86400);
         }
         await redis.rpush('cachly:lessons:brain_from_git:all', JSON.stringify({ topic, sha: commit.sha.slice(0, 8), subject: commit.subject.slice(0, 60) }));
         await redis.ltrim('cachly:lessons:brain_from_git:all', -500, -1);
+        await redis.expire('cachly:lessons:brain_from_git:all', 90 * 86400);
 
         // Update CKG
         const conceptId = ckgSlug(topic);
@@ -1034,6 +1041,13 @@ export async function handleFedbrainTool(
 
       const categoryBreakdown = [...categoryCount.entries()].sort((a, b) => b[1] - a[1]).map(([k, v]) => `  • **${k}** (${v})`).join('\n');
 
+      _lastBrainFromGitCounts = {
+        fixes: categoryCount.get('fix') ?? 0,
+        features: categoryCount.get('feat') ?? 0,
+        refactors: categoryCount.get('refactor') ?? 0,
+        total: ingested,
+      };
+
       return [
         `🔁 **brain_from_git: ${repoDir}**`,
         isIncremental ? `🔄 Incremental mode — only new commits since \`${lastSha.slice(0, 8)}\` were processed` : '',

package/src/handlers/roadmap.ts

@@ -157,9 +157,12 @@ export async function handleRoadmapTool(
       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 items = Object.values(all)
-        .map(v => JSON.parse(v as string) as Record<string, unknown>)
+        .flatMap(v => {
+          const item = safeJsonParse<Record<string, unknown> | null>(v as string, null);
+          return item ? [item] : [];
+        })
         .filter(i => i.status === 'in-progress' || i.status === 'planned')
-        .filter(i => !filterTag || (i.tags as string[]).includes(filterTag));
+        .filter(i => !filterTag || (Array.isArray(i.tags) ? i.tags : []).includes(filterTag));
       if (items.length === 0) return '🎉 **No open roadmap items!** All tasks are done (or use `roadmap_list` to check).';
       // in-progress first, then by priority
       items.sort((a, b) => {
@@ -169,7 +172,8 @@ export async function handleRoadmapTool(
       });
       const next = items[0];
       const remaining = items.length - 1;
-      const tags = (next.tags as string[]).length ? `\nTags:      ${(next.tags as string[]).join(', ')}` : '';
+      const nextTags = Array.isArray(next.tags) ? next.tags as string[] : [];
+      const tags = nextTags.length ? `\nTags:      ${nextTags.join(', ')}` : '';
       const milestone = next.milestone ? `\nMilestone: ${next.milestone}` : '';
       const notes = next.notes ? `\nNotes:     ${(next.notes as string).split('\n').pop()?.slice(0, 120)}` : '';
       return [