@cachly-dev/mcp-server 0.9.6 → 0.9.8

package/glama.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "HeinrichNebula"
+  ]
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
-  "description": "Persistent AI memory for Claude Code, Cursor, Copilot & Windsurf — 63 MCP tools. Causal Knowledge Graph, predictive failure detection, continuous learning from git commits + CI, federated knowledge sharing. Your AI learns from every bug fix and never re-researches the same problem.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 63 MCP tools · Claude Code · Cursor · GitHub Copilot · Windsurf · Free tier · EU servers.",
   "type": "module",
   "bin": {
     "cachly-mcp": "dist/index.js"

package/server.json

@@ -1,18 +1,18 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.cachly-dev/cachly-mcp",
-  "description": "Persistent AI memory for Claude Code, Cursor, Copilot & Windsurf. Your AI learns from every bug fix and never re-researches the same problem. 63 MCP tools — Causal Knowledge Graph, predictive failure detection, continuous learning from git commits, federated knowledge sharing.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 67 MCP tools · Free tier · EU servers.",
   "repository": {
     "url": "https://github.com/cachly-dev/cachly-mcp",
     "source": "github"
   },
-  "version": "0.9.6",
+  "version": "0.9.7",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.9.6",
+      "version": "0.9.7",
       "transport": {
         "type": "stdio"
       }

package/src/index.ts

@@ -55,7 +55,7 @@ import { Redis } from 'ioredis';
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
 const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.9.6';
+const CURRENT_VERSION = '0.9.8';
 
 // ── Default Instance Resolution (for Smithery & single-credential setups) ────
 // When CACHLY_BRAIN_INSTANCE_ID is set, tools can omit the instance_id parameter.
@@ -1960,18 +1960,20 @@ async function keywordSearch(
   query: string,
   topK = 10,
 ): Promise<KeywordMatch[]> {
-  // ── Step 1: Collect and tokenize all documents ──
-  const allKeys: string[] = [];
-  for (const pattern of patterns) {
-    const stream = redis.scanStream({ match: pattern, count: 200 });
-    await new Promise<void>((resolve, reject) => {
+  // ── Step 1: Collect all matching keys — patterns scanned in parallel ──
+  const keyBatches = await Promise.all(patterns.map(pattern => {
+    const keys: string[] = [];
+    const stream = redis.scanStream({ match: pattern, count: 500 });
+    return new Promise<string[]>((resolve, reject) => {
       stream.on('data', (batch: string[]) => {
-        allKeys.push(...batch.filter((k: string) => !k.endsWith(':meta')));
+        keys.push(...batch.filter((k: string) => !k.endsWith(':meta')));
       });
-      stream.on('end', resolve);
+      stream.on('end', () => resolve(keys));
       stream.on('error', reject);
     });
-  }
+  }));
+  // Deduplicate across patterns (a key may match multiple globs)
+  const allKeys = [...new Set(keyBatches.flat())];
 
   if (allKeys.length === 0) return [];
 
@@ -2285,15 +2287,37 @@ async function getConnection(instance_id: string): Promise<Redis> {
 
 // ── API helper ────────────────────────────────────────────────────────────────
 
+function jwtExpiryMs(token: string): number | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf-8')) as { exp?: number };
+    return payload.exp ? payload.exp * 1000 : null;
+  } catch { return null; }
+}
+
 async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
   if (!JWT) {
     throw new McpError(
       ErrorCode.InvalidRequest,
-      'CACHLY_JWT env var not set. Get your API token from https://cachly.dev/settings'
+      'CACHLY_JWT env var not set.\n\nGet your token at https://cachly.dev/setup-ai and add it to your MCP config:\n  CACHLY_JWT=<your-token>'
     );
   }
+
+  // Detect token expiry before making the network call — gives a clearer error
+  const expMs = jwtExpiryMs(JWT);
+  if (expMs !== null && expMs < Date.now()) {
+    const expiredAt = new Date(expMs).toISOString();
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      `CACHLY_JWT expired at ${expiredAt}.\n\nGet a fresh token at https://cachly.dev/setup-ai and update CACHLY_JWT in your MCP config.`
+    );
+  }
+
+  const timeoutMs = Number(process.env.CACHLY_API_TIMEOUT_MS ?? 15_000);
   const res = await fetch(`${API_URL}${path}`, {
     ...options,
+    signal: AbortSignal.timeout(timeoutMs),
     headers: {
       'Content-Type': 'application/json',
       Authorization: `Bearer ${JWT}`,
@@ -2302,9 +2326,22 @@ async function apiFetch<T>(path: string, options: RequestInit = {}): Promise<T>
   });
   if (!res.ok) {
     const body = await res.json().catch(() => ({ error: res.statusText }));
+    const detail = (body as { error?: string }).error ?? res.statusText;
+    if (res.status === 401) {
+      throw new McpError(
+        ErrorCode.InvalidRequest,
+        `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at https://cachly.dev/setup-ai`
+      );
+    }
+    if (res.status === 403) {
+      throw new McpError(
+        ErrorCode.InvalidRequest,
+        `Access denied (403): ${detail}\n\nCheck that your CACHLY_JWT belongs to an account with access to this resource.`
+      );
+    }
     throw new McpError(
       ErrorCode.InternalError,
-      `cachly API error ${res.status}: ${(body as { error?: string }).error ?? res.statusText}`
+      `cachly API error ${res.status}: ${detail}`
     );
   }
   if (res.status === 204) return undefined as T;
@@ -3919,6 +3956,72 @@ const TOOLS = [
       required: ['instance_id'],
     },
   },
+  {
+    name: 'crystal_view',
+    description:
+      'Inspect the current Memory Crystal — the compressed wisdom distilled from all past sessions. ' +
+      'Shows top patterns per category, lesson count, and when the crystal was last refreshed. ' +
+      'Call after session_start when you want to quickly see accumulated wisdom across all past work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'Brain instance ID' },
+        show_raw: { type: 'boolean', description: 'Include raw JSON crystal data (default: false)' },
+      },
+      required: ['instance_id'],
+    },
+  },
+  {
+    name: 'compact_recover',
+    description:
+      'Call FIRST after any context limit hit / compaction. Reconstructs full context from Memory Crystal + ' +
+      'recent sessions + WIP registry + open failures. Returns a condensed briefing so the new context ' +
+      'window starts exactly where the previous one left off — no lost progress.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'Brain instance ID' },
+        focus: { type: 'string', description: 'What you were working on (helps filter relevant context)' },
+      },
+      required: ['instance_id'],
+    },
+  },
+  {
+    name: 'brain_from_git',
+    description:
+      'Bootstrap brain lessons from git history. Parses commit messages and infers fix/feature/refactor ' +
+      'lessons automatically. Great for onboarding an existing codebase — run once and the brain instantly ' +
+      'knows your team\'s accumulated patterns. Supports limit and branch options.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'Brain instance ID' },
+        repo_path: { type: 'string', description: 'Path to git repository (default: current directory)' },
+        limit: { type: 'number', description: 'Max commits to process (default: 100, max: 500)' },
+        branch: { type: 'string', description: 'Git branch to parse (default: current branch / HEAD)' },
+        since: { type: 'string', description: 'Only commits after this date, e.g. "2024-01-01" (optional)' },
+      },
+      required: ['instance_id'],
+    },
+  },
+  {
+    name: 'brain_predict_failures',
+    description:
+      'Pre-deploy failure prediction with probability percentages. Given a change context (e.g. ' +
+      '"upgrading Keycloak 21→24" or "deploying Redis 7 to prod"), returns the top likely failure modes ' +
+      'ranked by probability, with pre-loaded fixes. Uses CKG causal edges + lesson history. ' +
+      'Call before any significant deploy, migration, or infrastructure change.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'Brain instance ID' },
+        context: { type: 'string', description: 'What you are about to do, e.g. "upgrading Keycloak 21 to 24"' },
+        top_k: { type: 'number', description: 'Number of failure predictions to return (default: 5)' },
+        format: { type: 'string', enum: ['brief', 'detailed'], description: 'Output format (default: detailed)' },
+      },
+      required: ['instance_id', 'context'],
+    },
+  },
 ] as const;
 
 // ── Handlers ──────────────────────────────────────────────────────────────────
@@ -9176,6 +9279,404 @@ smart_recall(
       return lines.join('\n');
     }
 
+    // ── crystal_view ──────────────────────────────────────────────────────────
+    case 'crystal_view': {
+      const { instance_id, show_raw = false } = args as { instance_id: string; show_raw?: boolean };
+      const redis = await getConnection(instance_id);
+
+      const raw = await redis.get('cachly:crystal:latest');
+      if (!raw) {
+        return [
+          `💎 **Memory Crystal: not yet created**`, '',
+          `No crystal found. Create one with \`memory_crystalize()\` to compress your accumulated wisdom.`,
+          '', `💡 Tip: run \`memory_crystalize\` monthly for best results.`,
+        ].join('\n');
+      }
+
+      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 age = Math.floor((Date.now() - new Date(crystal.ts).getTime()) / 86400000);
+      const freshEmoji = age <= 7 ? '🟢' : age <= 30 ? '🟡' : '🔴';
+
+      const lines = [
+        `💎 **Memory Crystal: ${crystal.label}**`, '',
+        `📅 Created: ${new Date(crystal.ts).toLocaleDateString('de-DE')} (${age}d ago ${freshEmoji})`,
+        `📊 Compressed from: ${crystal.created_from}`,
+        `🗂️ Categories: ${crystal.categories.slice(0, 10).map(c => `\`${c}\``).join(', ')}${crystal.categories.length > 10 ? ` +${crystal.categories.length - 10} more` : ''}`,
+        '',
+        `**🔑 Top patterns (${crystal.top_patterns.length}):**`,
+      ];
+      for (const p of crystal.top_patterns) {
+        lines.push(`  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 110)}`);
+      }
+      if (age > 30) {
+        lines.push('', `⚠️ Crystal is ${age}d old — run \`memory_crystalize()\` to refresh it.`);
+      }
+      if (show_raw) {
+        lines.push('', '```json', JSON.stringify(crystal, null, 2), '```');
+      }
+      lines.push('', `💡 Refresh: \`memory_crystalize()\`  |  Recover: \`compact_recover(instance_id="...")\``);
+      return lines.join('\n');
+    }
+
+    // ── compact_recover ───────────────────────────────────────────────────────
+    case 'compact_recover': {
+      const { instance_id, focus = '' } = args as { instance_id: string; focus?: string };
+      const redis = await getConnection(instance_id);
+
+      const lines = [`🔁 **Compact Recovery Briefing**\n`];
+      lines.push(`> *Call this first after any context limit hit. Reconstructs where you left off.*\n`);
+
+      // 1. Memory Crystal
+      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('');
+      }
+
+      // 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('');
+      }
+
+      // 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}`);
+        }
+        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) {
+          lines.push(`### 🔧 WIP Registry`);
+          lines.push(wip.content.slice(0, 400));
+          lines.push('');
+        }
+      }
+
+      // 5. Open failures (roadmap with status=blocked/in_progress)
+      const roadmapKeys: string[] = [];
+      const rStream = redis.scanStream({ match: 'cachly:roadmap:*', count: 100 });
+      await new Promise<void>((res, rej) => { rStream.on('data', (b: string[]) => roadmapKeys.push(...b)); rStream.on('end', res); rStream.on('error', rej); });
+      const openItems: Array<{ title: string; status: string; priority?: string }> = [];
+      for (const k of roadmapKeys.slice(0, 30)) {
+        const r = await redis.get(k);
+        if (!r) continue;
+        try {
+          const item = JSON.parse(r) as { title?: string; status?: string; priority?: string };
+          if (item.status === 'in_progress' || item.status === 'blocked') openItems.push({ title: item.title ?? k, status: item.status, priority: item.priority });
+        } catch { /* skip */ }
+      }
+      if (openItems.length > 0) {
+        lines.push(`### 🚧 Open Items`);
+        for (const i of openItems.slice(0, 5)) lines.push(`  • [${i.status}] ${i.title}`);
+        lines.push('');
+      }
+
+      // 6. Focus-relevant lessons
+      if (focus) {
+        const lessonKeys: string[] = [];
+        const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+        await new Promise<void>((res, rej) => { lStream.on('data', (b: string[]) => lessonKeys.push(...b)); lStream.on('end', res); lStream.on('error', rej); });
+        const relevant: Array<{ topic: string; what_worked: string }> = [];
+        for (const k of lessonKeys) {
+          const r = await redis.get(k);
+          if (!r) continue;
+          try {
+            const l = JSON.parse(r) as { topic: string; what_worked?: string };
+            if (l.topic.toLowerCase().includes(focus.toLowerCase()) && l.what_worked) {
+              relevant.push({ topic: l.topic, what_worked: l.what_worked });
+            }
+          } catch { /* skip */ }
+        }
+        if (relevant.length > 0) {
+          lines.push(`### 💡 Relevant Lessons for "${focus}"`);
+          for (const l of relevant.slice(0, 4)) lines.push(`  • **${l.topic}**: ${l.what_worked.slice(0, 100)}`);
+          lines.push('');
+        }
+      }
+
+      if (lines.length <= 3) {
+        lines.push(`_No brain data found. Start accumulating knowledge with \`learn_from_attempts\` and \`session_start\`._`);
+      }
+      lines.push(`---`, `🧠 Brain is ready. Continue your work — full context restored.`);
+      return lines.join('\n');
+    }
+
+    // ── 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 redis = await getConnection(instance_id);
+      const { execSync } = await import('node:child_process');
+      const { resolve } = await import('node:path');
+
+      const repoDir = resolve(repo_path);
+      const maxCommits = Math.min(Number(limit) || 100, 500);
+
+      // Verify it's a git repo
+      try {
+        execSync('git rev-parse --git-dir', { cwd: repoDir, stdio: 'pipe' });
+      } catch {
+        return `❌ Not a git repository: \`${repoDir}\`. Pass \`repo_path\` pointing to a git checkout.`;
+      }
+
+      // Build git log command
+      const sinceFlag = since ? `--since="${since}"` : '';
+      const logCmd = `git log ${branch} ${sinceFlag} --pretty=format:"%H|||%s|||%ad|||%an" --date=short --no-merges -n ${maxCommits}`;
+
+      let logOutput = '';
+      try {
+        logOutput = execSync(logCmd, { cwd: repoDir, encoding: 'utf-8', stdio: 'pipe' });
+      } catch (e) {
+        return `❌ git log failed: ${(e as Error).message}. Check \`repo_path\` and \`branch\`.`;
+      }
+
+      const commits = logOutput.trim().split('\n').filter(Boolean).map(line => {
+        const [sha, subject, date, author] = line.split('|||');
+        return { sha: (sha ?? '').trim(), subject: (subject ?? '').trim(), date: (date ?? '').trim(), author: (author ?? '').trim() };
+      });
+
+      if (commits.length === 0) {
+        return `⚠️ No commits found in \`${repoDir}\` on branch \`${branch}\`${since ? ` since ${since}` : ''}.`;
+      }
+
+      // Pattern classifiers
+      const classifyCommit = (subject: string): { category: string; outcome: 'success' | 'failure' | 'partial'; severity: 'critical' | 'major' | 'minor' } => {
+        const s = subject.toLowerCase();
+        if (/\b(fix|fixed|fixes|bug|hotfix|patch|revert|resolve|closes? #\d+)\b/.test(s)) {
+          const sev: 'critical' | 'major' | 'minor' = /\b(critical|crash|security|auth|data loss|outage|prod|production)\b/.test(s) ? 'critical' : /\b(major|breaking|regression|hotfix)\b/.test(s) ? 'major' : 'minor';
+          return { category: 'fix', outcome: 'success', severity: sev };
+        }
+        if (/\b(feat|feature|add|added|implement|new|introduce)\b/.test(s)) return { category: 'feat', outcome: 'success', severity: 'minor' };
+        if (/\b(refactor|clean|cleanup|improve|simplify|extract|rename)\b/.test(s)) return { category: 'refactor', outcome: 'success', severity: 'minor' };
+        if (/\b(perf|optimize|speed|cache|latency|memory|performance)\b/.test(s)) return { category: 'perf', outcome: 'success', severity: 'major' };
+        if (/\b(security|cve|auth|csrf|xss|sql|injection|sanitize|escape|encrypt)\b/.test(s)) return { category: 'security', outcome: 'success', severity: 'critical' };
+        if (/\b(deploy|ci|cd|build|docker|k8s|helm|infra|devops)\b/.test(s)) return { category: 'deploy', outcome: 'success', severity: 'major' };
+        if (/\b(test|spec|coverage|assert|mock|unit|integration)\b/.test(s)) return { category: 'test', outcome: 'success', severity: 'minor' };
+        return { category: 'chore', outcome: 'success', severity: 'minor' };
+      };
+
+      // Extract domain keywords from commit subject
+      const extractDomain = (subject: string): string => {
+        const s = subject.toLowerCase();
+        const tokens = s.replace(/[^a-z0-9\s\-_]/g, ' ').split(/\s+/).filter(t => t.length > 3 && !['that', 'this', 'with', 'from', 'when', 'into', 'also', 'some', 'were'].includes(t));
+        return tokens.slice(0, 3).join('-') || 'general';
+      };
+
+      const ts = new Date().toISOString();
+      let ingested = 0;
+      let skipped = 0;
+      const categoryCount = new Map<string, number>();
+
+      for (const commit of commits) {
+        if (!commit.subject) { skipped++; continue; }
+        const { category, outcome, severity } = classifyCommit(commit.subject);
+        const domain = extractDomain(commit.subject);
+        const topic = `${category}:${domain}`;
+        categoryCount.set(category, (categoryCount.get(category) ?? 0) + 1);
+
+        const lessonObj = {
+          topic, outcome, severity,
+          what_worked: commit.subject.slice(0, 200),
+          what_failed: '',
+          context: `git:${commit.sha.slice(0, 8)} by ${commit.author} on ${commit.date}`,
+          file_paths: [], commands: [`git show ${commit.sha.slice(0, 8)}`],
+          tags: ['brain_from_git', category, 'git-history'],
+          depends_on: [], recall_count: 0, ts, verified_at: ts,
+          confidence: 0.55, // lower confidence for auto-inferred lessons
+          audit_trail: [{ ts, action: 'brain_from_git', sha: commit.sha.slice(0, 8) }],
+          version: 3,
+        };
+
+        // 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));
+          await redis.rpush(`cachly:lessons:${topic}`, JSON.stringify(lessonObj));
+        }
+        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);
+
+        // Update CKG
+        const conceptId = ckgSlug(topic);
+        await ckgUpsertNode(redis, conceptId, category, 'git-derived');
+        ingested++;
+      }
+
+      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}`,
+        ``,
+        `**Breakdown by category:**`,
+        categoryBreakdown,
+        ``,
+        `💡 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');
+    }
+
+    // ── brain_predict_failures ─────────────────────────────────────────────────
+    case 'brain_predict_failures': {
+      const { instance_id, context: ctx, top_k = 5, format = 'detailed' } = args as {
+        instance_id: string; context: string; top_k?: number; format?: 'brief' | 'detailed';
+      };
+      const redis = await getConnection(instance_id);
+
+      const ctxTokens = ctx.toLowerCase().replace(/[^a-z0-9\s\-_:.]/g, ' ').split(/\s+/).filter(t => t.length > 2);
+
+      type FailurePred = { concept: string; failure: string; probability: number; fix?: string; topic?: string; source: 'ckg' | 'lesson' };
+      const failures: FailurePred[] = [];
+
+      // Step 1: CKG — find 'causes' and 'degrades_under' edges from context tokens
+      for (const token of ctxTokens.slice(0, 8)) {
+        const nodeKeys: string[] = [];
+        const nStream = redis.scanStream({ match: `cachly:ckg:node:*${token}*`, count: 50 });
+        await new Promise<void>((res, rej) => { nStream.on('data', (b: string[]) => nodeKeys.push(...b)); nStream.on('end', res); nStream.on('error', rej); });
+
+        for (const nk of nodeKeys.slice(0, 5)) {
+          const nodeRaw = await redis.get(nk);
+          if (!nodeRaw) continue;
+          const node: CKGNode = JSON.parse(nodeRaw);
+          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);
+            if (edge.edgeType !== 'causes' && edge.edgeType !== 'degrades_under') continue;
+
+            // Look up fix for this failure from CKG 'fixes' edges
+            const fixEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${edge.to}`);
+            let fix: string | undefined;
+            for (const fek of fixEdgeKeys.slice(0, 10)) {
+              const feRaw = await redis.get(fek);
+              if (!feRaw) continue;
+              const fe: CKGEdge = JSON.parse(feRaw);
+              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);
+                  break;
+                }
+              }
+            }
+
+            failures.push({
+              concept: node.id,
+              failure: edge.to.replace(/-/g, ' '),
+              probability: edge.confidence,
+              fix,
+              source: 'ckg',
+            });
+          }
+        }
+      }
+
+      // Step 2: Lesson history — find failure-outcome lessons matching context
+      const lessonKeys: string[] = [];
+      const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 300 });
+      await new Promise<void>((res, rej) => { lStream.on('data', (b: string[]) => lessonKeys.push(...b)); lStream.on('end', res); lStream.on('error', rej); });
+
+      for (const k of lessonKeys.slice(0, 100)) {
+        const r = await redis.get(k);
+        if (!r) continue;
+        try {
+          const l = JSON.parse(r) as { topic: string; outcome: string; what_failed?: string; what_worked?: string; confidence?: number; severity?: string };
+          if (l.outcome !== 'failure' && l.outcome !== 'partial') continue;
+          if (!l.what_failed) continue;
+          const haystack = `${l.topic} ${l.what_failed}`.toLowerCase();
+          const matchScore = ctxTokens.filter(t => haystack.includes(t)).length / Math.max(1, ctxTokens.length);
+          if (matchScore < 0.15) continue;
+          const sevBoost = l.severity === 'critical' ? 0.15 : l.severity === 'major' ? 0.05 : 0;
+          failures.push({
+            concept: l.topic,
+            failure: l.what_failed.slice(0, 80),
+            probability: Math.min(0.97, (l.confidence ?? 0.5) * matchScore * 1.5 + sevBoost),
+            fix: l.what_worked?.slice(0, 120),
+            topic: l.topic,
+            source: 'lesson',
+          });
+        } catch { /* skip */ }
+      }
+
+      if (failures.length === 0) {
+        return [
+          `🔮 **Failure Prediction: "${ctx}"**`, '',
+          `No known failure patterns found for this context.`,
+          `💡 The brain learns from every \`learn_from_attempts(outcome="failure")\` call.`,
+          `🔍 Try: \`brain_predict(context="${ctx}")\` for broader predictions.`,
+        ].join('\n');
+      }
+
+      // Deduplicate and rank by probability
+      const seen = new Set<string>();
+      const ranked = failures.filter(f => {
+        const k = f.failure.slice(0, 40);
+        if (seen.has(k)) return false;
+        seen.add(k);
+        return true;
+      }).sort((a, b) => b.probability - a.probability).slice(0, Number(top_k));
+
+      const lines = [`🔮 **Failure Prediction for: "${ctx}"**\n`];
+      lines.push(`> Pre-deploy failure analysis based on ${failures.length} patterns. Ranked by probability.\n`);
+
+      for (let i = 0; i < ranked.length; i++) {
+        const f = ranked[i];
+        const pct = Math.round(f.probability * 100);
+        const bar = '█'.repeat(Math.round(pct / 10)) + '░'.repeat(10 - Math.round(pct / 10));
+        const icon = pct >= 70 ? '🔴' : pct >= 40 ? '🟡' : '🟢';
+        lines.push(`${icon} **${i + 1}. ${f.failure}**`);
+        lines.push(`   Probability: ${bar} **${pct}%** (${f.source === 'ckg' ? 'CKG causal edge' : 'lesson history'})`);
+        if (format === 'detailed' && f.fix) {
+          lines.push(`   ✅ Pre-loaded fix: _${f.fix}_`);
+        }
+        if (format === 'detailed' && f.topic) {
+          lines.push(`   📚 Lesson: \`${f.topic}\``);
+        }
+        lines.push('');
+      }
+
+      const highRisk = ranked.filter(f => f.probability >= 0.6);
+      if (highRisk.length > 0) {
+        lines.push(`⚠️ **${highRisk.length} high-risk failure${highRisk.length > 1 ? 's' : ''} detected** (≥60% probability). Review fixes before proceeding.`);
+      } else {
+        lines.push(`✅ No high-risk failures detected. Proceed with caution and monitor closely.`);
+      }
+      lines.push('', `💡 After deploy: \`learn_from_attempts(topic="deploy:...", outcome="success|failure")\` to improve future predictions.`);
+      return lines.join('\n');
+    }
+
     default:
       return null;
   }
@@ -9833,6 +10334,23 @@ if (!JWT) {
     '╚══════════════════════════════════════════════════════════════════╝\n' +
     '\n',
   );
+} else {
+  // Warn if the JWT is already expired or expiring within the hour.
+  const expMs = jwtExpiryMs(JWT);
+  if (expMs !== null) {
+    const minsLeft = Math.floor((expMs - Date.now()) / 60_000);
+    if (minsLeft <= 0) {
+      process.stderr.write(
+        `\n⚠️  cachly: CACHLY_JWT expired ${Math.abs(minsLeft)} minute(s) ago.\n` +
+        `   All tool calls will fail. Get a fresh token at https://cachly.dev/setup-ai\n\n`,
+      );
+    } else if (minsLeft < 60) {
+      process.stderr.write(
+        `\n⚠️  cachly: CACHLY_JWT expires in ${minsLeft} minute(s).\n` +
+        `   Refresh it soon at https://cachly.dev/setup-ai to avoid interruptions.\n\n`,
+      );
+    }
+  }
 }
 
 // ── Update nudge (non-blocking, fire-and-forget) ─────────────────────────────