@cachly-dev/mcp-server 0.5.80 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.5.80",
+  "version": "0.6.1",
   "mcpName": "io.github.cachly-dev/mcp-server",
   "description": "AI memory brain for Claude Code, Cursor, Copilot & Windsurf — persistent sessions, lessons learned, semantic search, team brain. 51 MCP tools.",
   "type": "module",

package/src/index.ts

@@ -55,7 +55,7 @@ import { Redis } from 'ioredis';
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 const JWT = process.env.CACHLY_JWT ?? '';
 const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.5.80';
+const CURRENT_VERSION = '0.6.1';
 /**
  * ┌──────────────────────────────────────────────────────────────────────┐
  * │  EMBEDDING PROVIDER — pluggable, client-side first                  │
@@ -186,6 +186,7 @@ async function computeEmbedding(text: string): Promise<number[]> {
       });
       if (!res.ok) throw new Error(`Mistral embedding error: ${res.statusText}`);
       const json = (await res.json()) as { data: { embedding: number[] }[] };
+      if (!json.data?.[0]?.embedding) throw new Error('Mistral returned empty embedding response');
       return json.data[0].embedding;
     }
 
@@ -250,6 +251,7 @@ async function computeEmbedding(text: string): Promise<number[]> {
       });
       if (!res.ok) throw new Error(`OpenAI embedding error: ${res.statusText}`);
       const json = (await res.json()) as { data: { embedding: number[] }[] };
+      if (!json.data?.[0]?.embedding) throw new Error('OpenAI returned empty embedding response');
       return json.data[0].embedding;
     }
 
@@ -3384,6 +3386,104 @@ const TOOLS = [
       required: ['instance_id', 'key'],
     },
   },
+
+  // ── v0.6 Cognitive Cache Tools ────────────────────────────────────────────
+  {
+    name: 'memory_consolidate',
+    description:
+      'Cognitive memory consolidation — the weekly garbage collector for your AI Brain. ' +
+      'Scans all lessons, detects contradictions (same topic with conflicting outcomes), ' +
+      'merges duplicates, flags stale entries (not recalled in 90+ days), and computes a ' +
+      'health score. Returns a full consolidation report with conflicts resolved, ' +
+      'duplicates merged, and a before/after count. ' +
+      'Run weekly or when brain_doctor reports > 20 lessons. ' +
+      'Like git gc for knowledge.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id:   { type: 'string', description: 'UUID of the cache instance' },
+        dry_run:       { type: 'boolean', description: 'If true, report what would change without writing (default: false)' },
+        stale_days:    { type: 'number',  description: 'Lessons not recalled in this many days are flagged stale (default: 90)' },
+      },
+      required: ['instance_id'],
+    },
+  },
+  {
+    name: 'brain_diff',
+    description:
+      'git log for your AI Brain — see exactly what changed since a point in time. ' +
+      'Returns a structured changelog: new lessons added, lessons updated (outcome changed), ' +
+      'lessons recalled (hit count increased), and lessons that decayed. ' +
+      'Perfect for weekly reviews: "What did my AI learn this week?" ' +
+      'Example: brain_diff(instance_id="...", since="7d") → "12 new · 4 updated · 2 stale"',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        since:       { type: 'string', description: 'Time window: "1d", "7d", "30d", or ISO-8601 date (default: "7d")' },
+        format:      { type: 'string', enum: ['summary', 'detailed'], description: 'Output format (default: summary)' },
+      },
+      required: ['instance_id'],
+    },
+  },
+  {
+    name: 'causal_trace',
+    description:
+      'Root Cause Analysis through memory — the most powerful debugging tool in your AI Brain. ' +
+      'Given a problem description, traces the causal chain from root cause through intermediate ' +
+      'failures to the current symptom, then surfaces the exact solution that worked before. ' +
+      'Example: causal_trace(problem="auth breaks after restart") → ' +
+      '"Root: k8s:namespace-terminating → keycloak:jwks-race → Solution from March 12: PollUntilContextTimeout 3min" ' +
+      'No other memory system can do this. Replaces 30 minutes of git blame + log archaeology.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+        problem:     { type: 'string', description: 'Describe the problem or error you are seeing right now' },
+        max_depth:   { type: 'number', description: 'Max causal chain depth to trace (default: 5)' },
+        tags:        { type: 'array', items: { type: 'string' }, description: 'Optional: narrow search to these tags' },
+      },
+      required: ['instance_id', 'problem'],
+    },
+  },
+  {
+    name: 'knowledge_decay',
+    description:
+      'Confidence scoring for every lesson in your Brain — because old knowledge rots. ' +
+      'Computes a decay score (0–100%) per lesson based on age, recall frequency, and outcome. ' +
+      'Lessons recalled recently score high. Lessons from 90 days ago never recalled score low. ' +
+      'Returns a ranked list with visual confidence bars: "████░░░░ 40%". ' +
+      'Use this before a big refactor to know which lessons to trust and which to re-validate.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id:  { type: 'string', description: 'UUID of the cache instance' },
+        min_age_days: { type: 'number', description: 'Only include lessons older than N days (default: 0 = all)' },
+        show_top:     { type: 'number', description: 'Number of entries to return, sorted by lowest confidence first (default: 20)' },
+      },
+      required: ['instance_id'],
+    },
+  },
+  {
+    name: 'autopilot',
+    description:
+      'The endgame: generate a CLAUDE.md / copilot-instructions.md that turns any AI into a ' +
+      'self-managing brain operator. Zero manual session_start / session_end calls forever. ' +
+      'The generated file instructs Claude, Cursor, Copilot, Windsurf, or Gemini to ' +
+      'automatically call session_start at window open, learn_from_attempts after every fix, ' +
+      'and session_end before closing — without being asked. ' +
+      'One command. Every AI. Always on.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id:  { type: 'string', description: 'UUID of the cache instance' },
+        editor:       { type: 'string', enum: ['claude', 'cursor', 'copilot', 'windsurf', 'gemini', 'continue', 'all'], description: 'Target editor (default: claude)' },
+        project_name: { type: 'string', description: 'Your project name (used in generated instructions)' },
+        style:        { type: 'string', enum: ['minimal', 'full'], description: 'minimal = just the hooks, full = full ruleset with examples (default: full)' },
+      },
+      required: ['instance_id'],
+    },
+  },
 ] as const;
 
 // ── Handlers ──────────────────────────────────────────────────────────────────
@@ -6945,6 +7045,512 @@ async function handleBulkLockStream(name: string, args: Record<string, unknown>)
       ].filter(s => s !== undefined).join('\n');
     }
 
+    // ── v0.6 Cognitive Cache: memory_consolidate ─────────────────────────────
+    case 'memory_consolidate': {
+      const { instance_id, dry_run = false, stale_days = 90 } = args as {
+        instance_id: string; dry_run?: boolean; stale_days?: number;
+      };
+      const redis = await getConnection(instance_id);
+      const now = Date.now();
+      const staleMs = stale_days * 86400 * 1000;
+
+      // Scan all lessons
+      let cursor = 0;
+      const lessonKeys: string[] = [];
+      do {
+        const [next, keys] = await redis.scan(cursor, 'MATCH', 'cachly:lesson:best:*', 'COUNT', 200);
+        cursor = parseInt(next);
+        lessonKeys.push(...keys);
+      } while (cursor !== 0);
+
+      if (lessonKeys.length === 0) {
+        return '🧠 **Brain is empty** — no lessons to consolidate yet. Use `learn_from_attempts` after your next bug fix.';
+      }
+
+      type Lesson = { topic: string; outcome: string; what_worked?: string; what_failed?: string; ts: string; recall_count?: number; severity?: string; tags?: string[] };
+      const lessons: Map<string, Lesson> = new Map();
+      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 */ }
+      }
+
+      // Detect duplicates: same topic prefix (e.g. deploy:api vs deploy:api-v2)
+      const duplicates: string[][] = [];
+      const topicGroups = new Map<string, string[]>();
+      for (const [k, l] of lessons) {
+        const prefix = l.topic.split(':')[0];
+        const group = topicGroups.get(prefix) ?? [];
+        group.push(k);
+        topicGroups.set(prefix, group);
+      }
+
+      // Detect contradictions: same exact topic, different outcomes
+      const contradictions: Array<{ topic: string; keys: string[] }> = [];
+      const exactTopics = new Map<string, string[]>();
+      for (const [k, l] of lessons) {
+        const arr = exactTopics.get(l.topic) ?? [];
+        arr.push(k);
+        exactTopics.set(l.topic, arr);
+      }
+      for (const [topic, keys] of exactTopics) {
+        const outcomes = new Set(keys.map(k => lessons.get(k)?.outcome));
+        if (outcomes.size > 1) contradictions.push({ topic, keys });
+      }
+
+      // Detect stale: not recalled in stale_days
+      const stale: string[] = [];
+      for (const [k, l] of lessons) {
+        const age = now - new Date(l.ts).getTime();
+        const recalls = l.recall_count ?? 0;
+        if (age > staleMs && recalls === 0) stale.push(k);
+      }
+
+      // Merge duplicates by prefix: keep the success/highest-severity one
+      let merged = 0;
+      if (!dry_run) {
+        for (const [, keys] of topicGroups) {
+          if (keys.length < 2) continue;
+          const bySuccess = keys.filter(k => lessons.get(k)?.outcome === 'success');
+          const winner = bySuccess[0] ?? keys[0];
+          for (const k of keys) {
+            if (k !== winner) { await redis.del(k); merged++; }
+          }
+        }
+        // Resolve contradictions: keep success, delete failure for same topic
+        for (const { keys } of contradictions) {
+          const success = keys.find(k => lessons.get(k)?.outcome === 'success');
+          if (success) {
+            for (const k of keys) {
+              if (k !== success) { await redis.del(k); }
+            }
+          }
+        }
+        // Flag stale entries with a TTL of 30 days (not deleted, just expiring)
+        for (const k of stale) {
+          await redis.expire(k, 86400 * 30);
+        }
+      }
+
+      const lines = [
+        `🔬 **Memory Consolidation Report** ${dry_run ? '(dry run — no changes made)' : '✅ Applied'}`,
+        ``,
+        `📊 **Before:** ${lessonKeys.length} lessons`,
+        ``,
+        `🔁 **Contradictions detected:** ${contradictions.length}`,
+        ...contradictions.slice(0, 5).map(c => `  → \`${c.topic}\`: ${c.keys.length} conflicting entries (kept: success)`),
+        contradictions.length > 5 ? `  … and ${contradictions.length - 5} more` : '',
+        ``,
+        `♻️ **Duplicate clusters:** ${Array.from(topicGroups.values()).filter(v => v.length > 1).length}` +
+          (merged > 0 ? ` → ${merged} entries merged` : ''),
+        ``,
+        `🕰️ **Stale entries (${stale_days}d, 0 recalls):** ${stale.length}` +
+          (stale.length > 0 && !dry_run ? ` → set to expire in 30 days` : ''),
+        ``,
+        `📊 **After:** ${dry_run ? lessonKeys.length : lessonKeys.length - merged} lessons`,
+        ``,
+        dry_run
+          ? `💡 Re-run without dry_run=true to apply changes.`
+          : `✨ Brain consolidated. Run \`brain_diff(since="1h")\` to see the delta.`,
+      ].filter(s => s !== '').join('\n');
+      return lines;
+    }
+
+    // ── v0.6 Cognitive Cache: brain_diff ─────────────────────────────────────
+    case 'brain_diff': {
+      const { instance_id, since = '7d', format = 'summary' } = args as {
+        instance_id: string; since?: string; format?: 'summary' | 'detailed';
+      };
+      const redis = await getConnection(instance_id);
+
+      // Parse since
+      let sinceMs: number;
+      const match = since.match(/^(\d+)([dhm])$/);
+      if (match) {
+        const n = parseInt(match[1]);
+        const unit = match[2];
+        const mult = unit === 'd' ? 86400000 : unit === 'h' ? 3600000 : 60000;
+        sinceMs = Date.now() - n * mult;
+      } else {
+        sinceMs = new Date(since).getTime() || Date.now() - 7 * 86400000;
+      }
+
+      // Scan all lessons
+      let cursor = 0;
+      const lessonKeys: string[] = [];
+      do {
+        const [next, keys] = await redis.scan(cursor, 'MATCH', 'cachly:lesson:best:*', 'COUNT', 200);
+        cursor = parseInt(next);
+        lessonKeys.push(...keys);
+      } while (cursor !== 0);
+
+      type Lesson = { topic: string; outcome: string; what_worked?: string; ts: string; recall_count?: number; severity?: string };
+      const added: Lesson[] = [];
+      const updated: Lesson[] = [];
+      const recalled: Lesson[] = [];
+      const total = lessonKeys.length;
+
+      for (const k of lessonKeys) {
+        const raw = await redis.get(k);
+        if (!raw) continue;
+        try {
+          const l = JSON.parse(raw) as Lesson;
+          const ts = new Date(l.ts).getTime();
+          if (ts >= sinceMs) {
+            // Check history to determine add vs update
+            const histKey = `cachly:lesson:history:${l.topic}`;
+            const histLen = await redis.llen(histKey);
+            if (histLen <= 1) added.push(l);
+            else updated.push(l);
+          }
+          if ((l.recall_count ?? 0) > 0) {
+            // We can't easily know when last recalled without extra metadata, so include
+            // lessons with recalls as "active"
+            recalled.push(l);
+          }
+        } catch { /* skip */ }
+      }
+
+      const sinceLabel = match ? `last ${since}` : new Date(sinceMs).toLocaleDateString('de-DE');
+      const lines: string[] = [
+        `📊 **Brain Diff** — ${sinceLabel}`,
+        ``,
+        `Total lessons in brain: **${total}**`,
+        ``,
+        `✅ **New** (${added.length}):`,
+        ...added.slice(0, format === 'detailed' ? 20 : 5).map(l =>
+          `  + \`${l.topic}\` — ${l.outcome} ${l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟠' : '🟢'}`
+        ),
+        added.length > 5 && format === 'summary' ? `  … and ${added.length - 5} more` : '',
+        ``,
+        `🔄 **Updated** (${updated.length}):`,
+        ...updated.slice(0, format === 'detailed' ? 20 : 5).map(l =>
+          `  ~ \`${l.topic}\` — now: ${l.outcome}`
+        ),
+        updated.length > 5 && format === 'summary' ? `  … and ${updated.length - 5} more` : '',
+        ``,
+        `🔍 **Active** (recalled at least once): ${recalled.length}`,
+        ``,
+        `💡 Run \`memory_consolidate\` to merge duplicates · \`knowledge_decay\` to see confidence scores.`,
+      ].filter(s => s !== '');
+      return lines.join('\n');
+    }
+
+    // ── v0.6 Cognitive Cache: causal_trace ───────────────────────────────────
+    case 'causal_trace': {
+      const { instance_id, problem, max_depth = 5, tags: filterTags = [] } = args as {
+        instance_id: string; problem: string; max_depth?: number; tags?: string[];
+      };
+      const redis = await getConnection(instance_id);
+
+      // Normalize problem to keyword tokens
+      const tokens = problem.toLowerCase()
+        .replace(/[^a-z0-9\s\-_:]/g, ' ')
+        .split(/\s+/)
+        .filter(t => t.length > 2);
+
+      // Scan all lessons + history entries
+      let cursor = 0;
+      const lessonKeys: string[] = [];
+      do {
+        const [next, keys] = await redis.scan(cursor, 'MATCH', 'cachly:lesson:*', 'COUNT', 200);
+        cursor = parseInt(next);
+        lessonKeys.push(...keys);
+      } while (cursor !== 0);
+
+      type Lesson = {
+        topic: string; outcome: string; what_worked?: string; what_failed?: string;
+        ts: string; recall_count?: number; severity?: string; tags?: string[];
+        context?: string;
+      };
+
+      // Score each lesson by token overlap with problem description
+      const scored: Array<{ score: number; lesson: Lesson; key: string }> = [];
+      for (const k of lessonKeys) {
+        const raw = await redis.get(k);
+        if (!raw) continue;
+        try {
+          const l = JSON.parse(raw) as Lesson;
+          // Skip if filter tags given and lesson has none of them
+          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);
+
+      if (chain.length === 0) {
+        return [
+          `🔍 **Causal Trace: "${problem}"**`,
+          ``,
+          `No matching lessons found in brain.`,
+          ``,
+          `💡 After you solve this, call:`,
+          `\`\`\``,
+          `learn_from_attempts(`,
+          `  instance_id = "${instance_id}",`,
+          `  topic       = "fix:${tokens[0] ?? 'issue'}",`,
+          `  outcome     = "success",`,
+          `  what_worked = "...",`,
+          `  what_failed = "${problem}",`,
+          `)`,
+          `\`\`\``,
+        ].join('\n');
+      }
+
+      // Build causal chain narrative: failures first → then successes
+      const failures = chain.filter(c => c.lesson.outcome !== 'success');
+      const solutions = chain.filter(c => c.lesson.outcome === 'success');
+
+      const SEV_ICON: Record<string, string> = { critical: '🔴', major: '🟠', minor: '🟡' };
+
+      const lines: string[] = [
+        `🔍 **Causal Trace: "${problem}"**`,
+        ``,
+        `Found **${chain.length}** related lessons. Reconstructed causal chain:`,
+        ``,
+      ];
+
+      if (failures.length > 0) {
+        lines.push(`**Root causes & failure chain:**`);
+        failures.forEach((c, i) => {
+          const l = c.lesson;
+          const sev = SEV_ICON[l.severity ?? 'minor'] ?? '🟡';
+          lines.push(`${i === 0 ? '  Root:' : '   → :'} ${sev} \`${l.topic}\``);
+          if (l.what_failed) lines.push(`          ↳ ${l.what_failed.slice(0, 120)}`);
+        });
+        lines.push('');
+      }
+
+      if (solutions.length > 0) {
+        lines.push(`**Solutions that worked before:**`);
+        solutions.forEach((c, i) => {
+          const l = c.lesson;
+          const date = new Date(l.ts).toLocaleDateString('de-DE');
+          lines.push(`  ${i + 1}. ✅ \`${l.topic}\` — ${date} · recalled ${l.recall_count ?? 0}× `);
+          if (l.what_worked) lines.push(`     ${l.what_worked.slice(0, 200)}`);
+        });
+        lines.push('');
+      }
+
+      const topSolution = solutions[0]?.lesson;
+      if (topSolution?.what_worked) {
+        lines.push(`**⚡ Most likely fix:**`);
+        lines.push(`\`\`\``);
+        lines.push(topSolution.what_worked.slice(0, 500));
+        lines.push(`\`\`\``);
+        lines.push('');
+      }
+
+      lines.push(`💡 After applying: \`learn_from_attempts(topic="fix:${tokens[0] ?? 'issue'}", outcome="success", ...)\``);
+      return lines.join('\n');
+    }
+
+    // ── v0.6 Cognitive Cache: knowledge_decay ────────────────────────────────
+    case 'knowledge_decay': {
+      const { instance_id, min_age_days = 0, show_top = 20 } = args as {
+        instance_id: string; min_age_days?: number; show_top?: number;
+      };
+      const redis = await getConnection(instance_id);
+      const now = Date.now();
+      const minAgeMs = min_age_days * 86400000;
+
+      let cursor = 0;
+      const lessonKeys: string[] = [];
+      do {
+        const [next, keys] = await redis.scan(cursor, 'MATCH', 'cachly:lesson:best:*', 'COUNT', 200);
+        cursor = parseInt(next);
+        lessonKeys.push(...keys);
+      } while (cursor !== 0);
+
+      type Lesson = { topic: string; outcome: string; ts: string; recall_count?: number; severity?: string };
+      type Scored = { topic: string; confidence: number; age_days: number; recalls: number; outcome: string };
+
+      const scores: Scored[] = [];
+      for (const k of lessonKeys) {
+        const raw = await redis.get(k);
+        if (!raw) continue;
+        try {
+          const l = JSON.parse(raw) as Lesson;
+          const ageMs = now - new Date(l.ts).getTime();
+          if (ageMs < minAgeMs) continue;
+          const age_days = Math.floor(ageMs / 86400000);
+          const recalls = l.recall_count ?? 0;
+
+          // Confidence formula:
+          // base = 100 → decays by 1pt/day after 7 days, floored at 5
+          // boost: +5 per recall, capped at +50
+          // penalty: failure outcome → -20
+          const decayPts = Math.max(0, age_days - 7);
+          const base = Math.max(5, 100 - decayPts);
+          const recallBoost = Math.min(50, recalls * 5);
+          const outcomePenalty = l.outcome === 'failure' ? -20 : 0;
+          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
+      scores.sort((a, b) => a.confidence - b.confidence);
+      const shown = scores.slice(0, show_top);
+
+      function bar(pct: number): string {
+        const filled = Math.round(pct / 10);
+        return '█'.repeat(filled) + '░'.repeat(10 - filled) + ` ${pct}%`;
+      }
+
+      const avgConf = scores.length > 0
+        ? Math.round(scores.reduce((s, e) => s + e.confidence, 0) / scores.length)
+        : 0;
+      const critical = scores.filter(s => s.confidence < 30).length;
+      const healthy = scores.filter(s => s.confidence >= 70).length;
+
+      const lines: string[] = [
+        `🧪 **Knowledge Decay Report** — ${scores.length} lessons`,
+        ``,
+        `Average confidence: **${bar(avgConf)}**`,
+        `🔴 Critical (<30%): ${critical}  🟢 Healthy (≥70%): ${healthy}`,
+        ``,
+        `Lowest confidence lessons (fix these first):`,
+        ``,
+        ...shown.map((s, i) =>
+          `${(i + 1).toString().padStart(2)}. \`${s.topic}\`\n    ${bar(s.confidence)} · ${s.age_days}d old · ${s.recalls} recalls · ${s.outcome}`
+        ),
+        ``,
+        scores.length > show_top ? `… and ${scores.length - show_top} more lessons` : '',
+        ``,
+        critical > 0
+          ? `⚠️ ${critical} lessons are critically stale. Validate them and re-run \`learn_from_attempts\` with updated findings.`
+          : `✅ Brain confidence is healthy overall.`,
+        ``,
+        `💡 Run \`memory_consolidate\` to prune stale entries · \`causal_trace\` to find root causes.`,
+      ].filter(s => s !== '');
+      return lines.join('\n');
+    }
+
+    // ── v0.6 Cognitive Cache: autopilot ──────────────────────────────────────
+    case 'autopilot': {
+      const { instance_id, editor = 'claude', project_name = 'this project', style = 'full' } = args as {
+        instance_id: string; editor?: string; project_name?: string; style?: 'minimal' | 'full';
+      };
+
+      const minimal = `## Cachly AI Brain — Autopilot
+
+**Instance:** \`${instance_id}\`
+
+> Sessions are fully automatic. The Brain starts when you call any tool and saves a summary when you close.
+
+### MANDATORY hooks (always fire, no exceptions):
+- **Window opens** → call \`session_start(instance_id="${instance_id}", focus="<today's goal>")\`
+- **Bug fixed / deployed / discovered** → call \`learn_from_attempts(instance_id="${instance_id}", topic="fix:<area>", outcome="success", what_worked="...")\`
+- **Window closes** → call \`session_end(instance_id="${instance_id}", summary="...", files_changed=[...])\`
+`;
+
+      const full = `## Cachly AI Brain — Autopilot for ${project_name}
+
+**Instance:** \`${instance_id}\`
+
+---
+
+## 🔴 MANDATORY RULES — No exceptions, no prompting needed
+
+### Rule 1 — Session Start (FIRST thing in every window)
+\`\`\`
+session_start(
+  instance_id = "${instance_id}",
+  focus       = "<what you plan to work on today>",
+)
+\`\`\`
+Returns: last session summary, handoff tasks, recent lessons, open failures.
+
+### Rule 2 — Learn After Every Fix/Deploy/Discovery (AUTOMATIC)
+**After EVERY** bug fix, deployment, or technical discovery — call immediately:
+\`\`\`
+learn_from_attempts(
+  instance_id = "${instance_id}",
+  topic       = "category:keyword",
+  outcome     = "success" | "failure" | "partial",
+  what_worked = "exact command or approach",
+  what_failed = "what failed (if applicable)",
+  severity    = "critical" | "major" | "minor",
+  commands    = ["the exact command that worked"],
+  file_paths  = ["path/to/file"],
+  tags        = ["relevant", "tags"],
+)
+\`\`\`
+
+**Triggers:**
+- ✅ Deployed → \`topic="deploy:web", outcome="success"\`
+- ✅ Fixed bug → \`topic="fix:auth-race", outcome="success"\`
+- ✅ Got error → \`topic="debug:docker", outcome="partial"\`
+
+### Rule 3 — Session End (LAST thing before closing)
+\`\`\`
+session_end(
+  instance_id     = "${instance_id}",
+  summary         = "What was accomplished (2-3 sentences)",
+  files_changed   = ["list", "of", "changed", "files"],
+  lessons_learned = <number of learn_from_attempts calls>,
+)
+\`\`\`
+
+### Rule 4 — Before any non-trivial task
+\`\`\`
+smart_recall(
+  instance_id = "${instance_id}",
+  query       = "<describe what you are about to do>",
+)
+\`\`\`
+
+---
+
+## ⚡ Cognitive Tools (v0.6)
+
+| When | Call |
+|---|---|
+| Brain feeling cluttered | \`memory_consolidate(instance_id="${instance_id}")\` |
+| Weekly review | \`brain_diff(instance_id="${instance_id}", since="7d")\` |
+| Weird bug, no idea why | \`causal_trace(instance_id="${instance_id}", problem="<symptom>")\` |
+| Before big refactor | \`knowledge_decay(instance_id="${instance_id}")\` |
+
+---
+
+*Cachly v0.6 · Generated ${new Date().toISOString().slice(0, 10)}*
+`;
+
+      const content = style === 'minimal' ? minimal : full;
+      const filename = editor === 'copilot'
+        ? '.github/copilot-instructions.md'
+        : editor === 'continue'
+          ? '.continue/cachly-autopilot.md'
+          : 'CLAUDE.md';
+
+      return [
+        `🤖 **Autopilot instructions generated** for **${editor === 'all' ? 'all editors' : editor}**`,
+        ``,
+        `**File to create:** \`${filename}\``,
+        ``,
+        `\`\`\`markdown`,
+        content,
+        `\`\`\``,
+        ``,
+        `**How to apply:**`,
+        `\`\`\`bash`,
+        `# Copy to your project root:`,
+        `cat > ${filename} << 'EOF'`,
+        content,
+        `EOF`,
+        `\`\`\``,
+        ``,
+        `✨ Once this file is in place, **${editor === 'copilot' ? 'GitHub Copilot' : editor === 'continue' ? 'Continue.dev' : 'Claude/Cursor/Windsurf'}** will manage the Brain automatically — no manual calls needed, ever.`,
+      ].join('\n');
+    }
+
     default:
       return null;
   }