@cachly-dev/mcp-server 0.9.19 → 0.9.21

package/dist/handlers/team.js

@@ -0,0 +1,1048 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { calculateConfidence, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_VALUE, CONFIDENCE_WARN_DAYS, CONFIDENCE_STALE_DAYS } from '../confidence.js';
+export const TEAM_TOOL_NAMES = new Set([
+    'sync_file_changes', 'team_learn', 'team_recall', 'team_synthesize', 'memory_crystalize',
+    'brain_doctor', 'recall_at', 'trace_dependency', 'global_learn', 'global_recall',
+    'publish_lesson', 'import_public_brain', 'setup_ai_memory',
+]);
+export async function handleTeamTool(name, args, getConnection, apiFetch) {
+    switch (name) {
+        case 'sync_file_changes': {
+            const { instance_id, changed_files, git_diff_stat, commit_msg } = args;
+            const redis = await getConnection(instance_id);
+            // Store file change event in session history
+            const changeRecord = {
+                ts: new Date().toISOString(),
+                files: changed_files,
+                commit_msg,
+                diff_stat: git_diff_stat?.slice(0, 500),
+            };
+            await redis.lpush('cachly:session:file_changes', JSON.stringify(changeRecord));
+            await redis.ltrim('cachly:session:file_changes', 0, 99);
+            await redis.expire('cachly:session:file_changes', 30 * 86400);
+            // Find lessons relevant to the changed files
+            const lessonKeys = [];
+            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+            await new Promise((resolve, reject) => {
+                lStream.on('data', (batch) => lessonKeys.push(...batch));
+                lStream.on('end', resolve);
+                lStream.on('error', reject);
+            });
+            const relevant = [];
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                const lesson = JSON.parse(raw);
+                // Match by file_paths stored in lesson OR by topic keywords matching file name
+                const topicWords = lesson.topic.toLowerCase().split(/[:\-_]/);
+                const fileMatches = changed_files.some(f => {
+                    const fname = f.split('/').pop()?.replace(/\.[^.]+$/, '').toLowerCase() ?? '';
+                    return topicWords.some(w => w.length > 3 && fname.includes(w))
+                        || (lesson.file_paths ?? []).some(lf => f.includes(lf) || lf.includes(f));
+                });
+                if (fileMatches) {
+                    const emoji = lesson.outcome === 'success' ? '✅' : '⚠️';
+                    relevant.push(`  ${emoji} \`${lesson.topic}\` — ${lesson.what_worked.slice(0, 80)}`);
+                }
+            }
+            const lines = [
+                `📁 **File sync recorded**: ${changed_files.length} files`,
+                commit_msg ? `📝 Commit: "${commit_msg}"` : '',
+                '',
+                `**Changed:** ${changed_files.slice(0, 8).map(f => `\`${f}\``).join(', ')}${changed_files.length > 8 ? ` +${changed_files.length - 8} more` : ''}`,
+                '',
+            ];
+            if (relevant.length > 0) {
+                lines.push(`🧠 **Relevant brain lessons (${relevant.length}):**`, ...relevant);
+            }
+            else {
+                lines.push(`💡 No existing lessons match these files yet. Add them with \`learn_from_attempts\`.`);
+            }
+            return lines.filter(Boolean).join('\n');
+        }
+        // ── team_learn ────────────────────────────────────────────────────────────
+        case 'team_learn': {
+            const { instance_id, author, topic, outcome, what_worked, what_failed, severity, file_paths, commands, tags } = args;
+            if (!author || !topic || !outcome || !what_worked) {
+                return '❌ Required: author, topic, outcome, what_worked';
+            }
+            const iid = instance_id;
+            if (!iid)
+                return '❌ instance_id required';
+            // Store with author attribution via the same learn_from_attempts Redis structure
+            const lesson = {
+                topic, outcome, what_worked,
+                what_failed: what_failed ?? '',
+                severity: severity ?? 'minor',
+                author,
+                file_paths: file_paths ?? [],
+                commands: commands ?? [],
+                tags: [...(tags ?? []), 'team'],
+                timestamp: new Date().toISOString(),
+                recall_count: 0,
+                version: 2,
+            };
+            const redis = await getConnection(iid);
+            const key = `cachly:lessons:${topic}`;
+            await redis.rpush(key, JSON.stringify(lesson));
+            if (outcome === 'success') {
+                await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(lesson));
+            }
+            return `✅ Team lesson stored by **${author}**: \`${topic}\` (${outcome})\n💡 ${what_worked.slice(0, 120)}`;
+        }
+        // ── team_recall ───────────────────────────────────────────────────────────
+        case 'team_recall': {
+            const { instance_id, topic, author, limit = 10 } = args;
+            const redis = await getConnection(instance_id);
+            const lessonKeys = [];
+            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+            await new Promise((resolve, reject) => {
+                lStream.on('data', (batch) => lessonKeys.push(...batch));
+                lStream.on('end', resolve);
+                lStream.on('error', reject);
+            });
+            let lessons = [];
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    lessons.push(JSON.parse(raw));
+                }
+                catch { /* skip */ }
+            }
+            // Filter
+            if (topic) {
+                const t = topic.toLowerCase();
+                lessons = lessons.filter(l => l.topic.toLowerCase().includes(t) ||
+                    (l.tags ?? []).some((tag) => tag.toLowerCase().includes(t)));
+            }
+            if (author) {
+                const a = author.toLowerCase();
+                lessons = lessons.filter(l => l.author?.toLowerCase().includes(a));
+            }
+            // Sort by recall_count desc
+            lessons.sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0));
+            lessons = lessons.slice(0, limit);
+            if (lessons.length === 0) {
+                return topic
+                    ? `📭 No team lessons found for \`${topic}\`.\n\nShared instance: add lessons with \`learn_from_attempts\` and include an \`author\` field.`
+                    : `📭 No lessons in this brain yet.\n\nAll team members sharing this instance will see lessons here.`;
+            }
+            const lines = [`👥 **Team Brain** — ${lessons.length} lesson${lessons.length > 1 ? 's' : ''}`, ''];
+            for (const l of lessons) {
+                const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+                const sev = l.severity === 'critical' ? '🔴 ' : l.severity === 'major' ? '🟡 ' : '';
+                const authorStr = l.author ? ` · _by ${l.author}_` : '';
+                const recallStr = (l.recall_count ?? 0) > 0 ? ` · recalled ${l.recall_count}×` : '';
+                const ago = Math.round((Date.now() - new Date(l.ts).getTime()) / 86400000);
+                const agoStr = ago === 0 ? 'today' : ago === 1 ? 'yesterday' : `${ago}d ago`;
+                lines.push(`${emoji} ${sev}**\`${l.topic}\`**${authorStr}${recallStr} · ${agoStr}`);
+                lines.push(`   ${l.what_worked.slice(0, 120)}`);
+                lines.push('');
+            }
+            return lines.join('\n');
+        }
+        // ── team_synthesize — Team Brain Synthesis ────────────────────────────────
+        case 'team_synthesize': {
+            const { instance_id, topic } = args;
+            const redis = await getConnection(instance_id);
+            // Load history list for this topic (all authors' contributions)
+            const listKey = `cachly:lessons:${topic}`;
+            const all = await redis.lrange(listKey, 0, -1);
+            if (all.length < 2) {
+                return `📭 Need at least 2 entries for topic \`${topic}\` to synthesize.\n\nCurrently: ${all.length} entr${all.length === 1 ? 'y' : 'ies'}.\n\nHave team members store lessons via \`learn_from_attempts(topic="${topic}", ...)\`.`;
+            }
+            const entries = all.map(r => { try {
+                return JSON.parse(r);
+            }
+            catch {
+                return null;
+            } }).filter((e) => e !== null);
+            // Group by outcome
+            const successes = entries.filter(e => e.outcome === 'success');
+            const failures = entries.filter(e => e.outcome === 'failure');
+            const partials = entries.filter(e => e.outcome === 'partial');
+            const authors = [...new Set(entries.map(e => e.author).filter(Boolean))];
+            const hasMultiAuthor = authors.length > 1;
+            // Build canonical merged version
+            // what_worked: pick the most recent success, or longest for most detail
+            const bestSuccess = successes.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime())[0];
+            const whatWorkedCandidates = successes.map(e => e.what_worked).filter(w => w && w.length > 10);
+            const canonicalWorked = whatWorkedCandidates.sort((a, b) => b.length - a.length)[0] ?? bestSuccess?.what_worked ?? '';
+            // what_failed: union of all unique failure reasons
+            const allFailed = [...new Set([...failures, ...partials].map(e => e.what_failed).filter((w) => !!w && w.length > 5))];
+            const severities = entries.map(e => e.severity).filter(Boolean);
+            const canonicalSeverity = severities.includes('critical') ? 'critical' : severities.includes('major') ? 'major' : 'minor';
+            const lines = [
+                `🧬 **Team Brain Synthesis: \`${topic}\`**`,
+                `_${entries.length} entries from ${authors.length} author${authors.length === 1 ? '' : 's'}${hasMultiAuthor ? ` (${authors.join(', ')})` : ''} · ${successes.length} success · ${failures.length} failure · ${partials.length} partial_`,
+                '',
+                `**Canonical "what worked":**`,
+                `> ${canonicalWorked}`,
+                '',
+                allFailed.length > 0 ? `**Avoid (combined failures):**` : '',
+                ...allFailed.map(f => `> ❌ ${f}`),
+                allFailed.length > 0 ? '' : '',
+                `**Suggested canonical lesson:**`,
+                '```',
+                `learn_from_attempts(`,
+                `  topic       = "${topic}",`,
+                `  outcome     = "success",`,
+                `  what_worked = "${canonicalWorked.replace(/"/g, "'")}",`,
+                allFailed.length > 0 ? `  what_failed = "${allFailed[0].replace(/"/g, "'")}",` : '',
+                `  severity    = "${canonicalSeverity}",`,
+                `)`,
+                '```',
+                '',
+                hasMultiAuthor
+                    ? `💡 _${authors.length} team members contributed to this synthesis. Store the canonical version to replace individual entries._`
+                    : `💡 _Single author — more value when multiple team members contribute to the same topic._`,
+            ].filter(l => l !== undefined).join('\n');
+            return lines;
+        }
+        // ── brain_doctor ──────────────────────────────────────────────────────────
+        // ── memory_crystalize ─────────────────────────────────────────────────────
+        case 'memory_crystalize': {
+            const { instance_id, label: crystalLabel = '' } = args;
+            const redis = await getConnection(instance_id);
+            const now = new Date();
+            const week = `${now.getFullYear()}-W${String(Math.ceil((now.getDate() - now.getDay() + 10) / 7)).padStart(2, '0')}`;
+            const effectiveLabel = crystalLabel || `${now.toISOString().slice(0, 7)} Crystal`;
+            // Read session history
+            const sessionHistory = await redis.lrange('cachly:session:history', 0, 49);
+            // Read all auto-learned lessons
+            const allLessonKeys = [];
+            const ls = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+            await new Promise((res, rej) => {
+                ls.on('data', (b) => allLessonKeys.push(...b));
+                ls.on('end', res);
+                ls.on('error', rej);
+            });
+            const allLessons = [];
+            for (const k of allLessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    allLessons.push(JSON.parse(raw));
+                }
+                catch { /* skip */ }
+            }
+            // Group lessons by top-level category
+            const categoryMap = new Map();
+            for (const l of allLessons) {
+                const cat = l.topic.split(':')[0] || 'misc';
+                if (!categoryMap.has(cat))
+                    categoryMap.set(cat, []);
+                categoryMap.get(cat).push(l);
+            }
+            // Build top patterns (most frequent categories with a representative insight)
+            const topPatterns = [];
+            for (const [cat, catLessons] of [...categoryMap.entries()].sort((a, b) => b[1].length - a[1].length).slice(0, 8)) {
+                const successLessons = catLessons.filter(l => l.outcome === 'success');
+                const best = successLessons[0] ?? catLessons[0];
+                if (!best)
+                    continue;
+                topPatterns.push({
+                    category: cat,
+                    insight: best.what_worked.slice(0, 120),
+                    count: catLessons.length,
+                });
+            }
+            const crystal = {
+                label: effectiveLabel,
+                ts: now.toISOString(),
+                session_count: sessionHistory.length,
+                lesson_count: allLessons.length,
+                top_patterns: topPatterns,
+                categories: [...categoryMap.keys()],
+                created_from: `${sessionHistory.length} sessions, ${allLessons.length} lessons`,
+            };
+            const crystalJson = JSON.stringify(crystal);
+            await redis.set('cachly:crystal:latest', crystalJson);
+            await redis.expire('cachly:crystal:latest', 90 * 86400);
+            await redis.set(`cachly:crystal:${week}`, crystalJson);
+            await redis.expire(`cachly:crystal:${week}`, 365 * 86400);
+            const lines = [
+                `💎 **Memory Crystal created: ${effectiveLabel}**`,
+                ``,
+                `📊 Compressed: **${sessionHistory.length} sessions** + **${allLessons.length} lessons** → ${topPatterns.length} top patterns`,
+                ``,
+                `**Top patterns by category:**`,
+                ...topPatterns.slice(0, 6).map(p => `  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 90)}`),
+                ``,
+                `💡 This crystal will appear in every future \`session_start\` briefing.`,
+                `💡 Re-run \`memory_crystalize\` monthly to keep it fresh.`,
+            ];
+            return lines.join('\n');
+        }
+        case 'brain_doctor': {
+            const { instance_id, workspace_path: drWorkspacePath = '' } = args;
+            const redis = await getConnection(instance_id);
+            const issues = [];
+            const checks = [];
+            // Count lessons
+            const lessonKeys = [];
+            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
+            await new Promise((resolve, reject) => {
+                lStream.on('data', (batch) => lessonKeys.push(...batch));
+                lStream.on('end', resolve);
+                lStream.on('error', reject);
+            });
+            // Count context
+            let ctxCount = 0;
+            const ctxStream = redis.scanStream({ match: 'cachly:ctx:*', count: 200 });
+            await new Promise((resolve, reject) => {
+                ctxStream.on('data', (batch) => {
+                    ctxCount += batch.filter((k) => !k.endsWith(':meta')).length;
+                });
+                ctxStream.on('end', resolve);
+                ctxStream.on('error', reject);
+            });
+            const lessons = [];
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    lessons.push(JSON.parse(raw));
+                }
+                catch { /* skip */ }
+            }
+            // Last session
+            const lastSessionRaw = await redis.get('cachly:session:last');
+            let lastSession = null;
+            if (lastSessionRaw) {
+                try {
+                    lastSession = JSON.parse(lastSessionRaw);
+                }
+                catch { /* ignore */ }
+            }
+            // Open failures
+            const openFailures = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial');
+            // Unused lessons (never recalled)
+            const unusedLessons = lessons.filter(l => (l.recall_count ?? 0) === 0);
+            // Critical lessons
+            const criticalLessons = lessons.filter(l => l.severity === 'critical');
+            // Confidence decay analysis
+            const staleLessons = lessons.filter(l => l.outcome === 'success' && calculateConfidence(l) < CONFIDENCE_STALE_VALUE);
+            const warnLessons = lessons.filter(l => l.outcome === 'success' && calculateConfidence(l) >= CONFIDENCE_STALE_VALUE && calculateConfidence(l) < CONFIDENCE_WARN_VALUE);
+            const withAudit = lessons.filter(l => (l.audit_trail ?? []).length > 1);
+            const teamLessons = lessons.filter(l => l.author);
+            const uniqueAuthors = new Set(lessons.map(l => l.author).filter(Boolean));
+            // Effective IQ boost: total recalls / lessons (how much the brain actually helped)
+            const totalRecalls = lessons.reduce((sum, l) => sum + (l.recall_count ?? 0), 0);
+            const iqBoostPct = lessons.length > 0 ? Math.min(100, Math.round((totalRecalls / lessons.length) * 10)) : 0;
+            // Quality score (0-100)
+            let score = 50;
+            if (lessonKeys.length >= 5)
+                score += 10;
+            if (lessonKeys.length >= 20)
+                score += 10;
+            if (ctxCount >= 3)
+                score += 10;
+            if (ctxCount >= 10)
+                score += 5;
+            if (lastSession)
+                score += 10;
+            if (openFailures.length === 0)
+                score += 5;
+            const unusedRatio = lessons.length > 0 ? unusedLessons.length / lessons.length : 0;
+            if (unusedRatio < 0.5)
+                score += 10;
+            if (staleLessons.length === 0)
+                score += 5;
+            if (uniqueAuthors.size >= 2)
+                score += 5; // team collaboration bonus
+            const scoreEmoji = score >= 80 ? '🟢' : score >= 50 ? '🟡' : '🔴';
+            const iqEmoji = iqBoostPct >= 50 ? '🚀' : iqBoostPct >= 20 ? '📈' : '💤';
+            checks.push(`${scoreEmoji} **Brain Quality Score: ${score}/100**`);
+            checks.push(`${iqEmoji} **Effective IQ Boost: ${iqBoostPct}%** (${totalRecalls} recalls across ${lessons.length} lessons)`);
+            checks.push(`📚 **Lessons:** ${lessonKeys.length} (${criticalLessons.length} critical · ${withAudit.length} with audit trail · ${teamLessons.length} from team)`);
+            checks.push(`💾 **Context entries:** ${ctxCount}`);
+            checks.push(`🎯 **Confidence:** ${lessons.length - staleLessons.length - warnLessons.length} fresh · ${warnLessons.length} warn · ${staleLessons.length} stale`);
+            checks.push(`⏱️ **Decay config:** warn after ${CONFIDENCE_WARN_DAYS}d · stale after ${CONFIDENCE_STALE_DAYS}d`);
+            if (uniqueAuthors.size >= 2) {
+                checks.push(`👥 **Team:** ${uniqueAuthors.size} contributors (${[...uniqueAuthors].join(', ')})`);
+            }
+            // Stale index detection
+            try {
+                const lastIndexRaw = await redis.get('cachly:index:last_run');
+                if (lastIndexRaw) {
+                    const lastIndexAge = Math.round((Date.now() - new Date(lastIndexRaw).getTime()) / 86_400_000);
+                    if (lastIndexAge > 7) {
+                        issues.push(`🔄 Index is ${lastIndexAge}d stale — run \`index_project\` to re-sync semantic search`);
+                    }
+                    else {
+                        checks.push(`🗂️ **Semantic index:** ${lastIndexAge}d old (fresh)`);
+                    }
+                }
+                else {
+                    issues.push(`💡 No semantic index — run \`index_project(dir="<your-src>")\` to enable semantic search`);
+                }
+            }
+            catch { /* non-critical */ }
+            // Memory crystal status
+            try {
+                const crystalRaw = await redis.get('cachly:crystal:latest');
+                if (crystalRaw) {
+                    const crystal = JSON.parse(crystalRaw);
+                    const crystalAge = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
+                    checks.push(`💎 **Memory Crystal:** ${crystal.label} (${crystalAge}d ago)`);
+                    if (crystalAge > 30)
+                        issues.push(`💡 Memory Crystal is ${crystalAge}d old — re-run \`memory_crystalize\` to compress new sessions`);
+                }
+                else if (lessonKeys.length >= 10) {
+                    issues.push(`💡 ${lessonKeys.length} lessons but no Memory Crystal — run \`memory_crystalize\` to compress wisdom`);
+                }
+            }
+            catch { /* non-critical */ }
+            // openclaw cross-promo (check package.json in workspace)
+            if (drWorkspacePath) {
+                try {
+                    const pkgPath = drWorkspacePath.replace(/\/$/, '') + '/package.json';
+                    const pkgRaw = readFileSync(pkgPath, 'utf-8');
+                    const pkg = JSON.parse(pkgRaw);
+                    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+                    const hasLLMDep = ['openai', '@anthropic-ai/sdk', '@google/generative-ai', 'mistralai', 'cohere-ai'].some(d => d in allDeps);
+                    const hasOpenclaw = '@cachly-dev/openclaw' in allDeps;
+                    if (hasLLMDep && !hasOpenclaw) {
+                        issues.push(`💡 **openclaw missing:** you use LLM APIs (${Object.keys(allDeps).filter(d => ['openai', '@anthropic-ai/sdk'].includes(d)).join(', ')}) but not \`@cachly-dev/openclaw\``);
+                        issues.push(`   → \`npm install @cachly-dev/openclaw\` cuts LLM costs 60–90% with 3 lines of code`);
+                    }
+                    else if (hasOpenclaw) {
+                        checks.push(`✅ **@cachly-dev/openclaw installed** (LLM cost caching active)`);
+                    }
+                }
+                catch { /* no package.json or unreadable */ }
+            }
+            if (lastSession) {
+                const ageMin = Math.round((Date.now() - new Date(lastSession.ts).getTime()) / 60000);
+                const ageStr = ageMin < 60 ? `${ageMin}m` : ageMin < 1440 ? `${Math.round(ageMin / 60)}h` : `${Math.round(ageMin / 1440)}d`;
+                checks.push(`🕐 **Last session:** ${ageStr} ago`);
+            }
+            else {
+                issues.push('❌ No session history — call `session_start` + `session_end` to start tracking');
+            }
+            if (lessonKeys.length === 0) {
+                issues.push('❌ No lessons — call `learn_from_attempts` after solving bugs');
+            }
+            else if (lessonKeys.length < 5) {
+                issues.push(`💡 Only ${lessonKeys.length} lessons — add more after each problem solved`);
+            }
+            if (iqBoostPct === 0 && lessons.length >= 5) {
+                issues.push(`💤 **IQ Boost is 0%** — lessons exist but are never recalled. Use \`recall_best_solution\` BEFORE tasks.`);
+            }
+            if (ctxCount === 0) {
+                issues.push('💡 No context — use `remember_context` to cache architecture docs, ADRs, etc.');
+            }
+            if (openFailures.length > 0) {
+                issues.push(`⚠️ ${openFailures.length} unresolved failure${openFailures.length > 1 ? 's' : ''}: ${openFailures.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
+            }
+            if (staleLessons.length > 0) {
+                issues.push(`🔴 ${staleLessons.length} STALE lesson${staleLessons.length > 1 ? 's' : ''} (>${CONFIDENCE_STALE_DAYS}d, confidence <${CONFIDENCE_STALE_VALUE * 100}%): ${staleLessons.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
+                issues.push(`   → Re-verify with \`recall_best_solution\` to reset confidence clock`);
+            }
+            if (warnLessons.length > 0) {
+                issues.push(`⚠️ ${warnLessons.length} lesson${warnLessons.length > 1 ? 's' : ''} aging (>${CONFIDENCE_WARN_DAYS}d): ${warnLessons.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
+            }
+            if (unusedRatio > 0.7 && lessons.length > 5) {
+                issues.push(`💡 ${unusedLessons.length} lessons never recalled — verify topics match your workflow`);
+            }
+            const lines = ['🩺 **Brain Doctor Report**', '', ...checks.map(c => '  ' + c), ''];
+            if (issues.length > 0) {
+                lines.push('**Issues to fix:**');
+                for (const i of issues)
+                    lines.push('  ' + i);
+                lines.push('');
+            }
+            else {
+                lines.push('  🎉 Brain looks healthy! Keep calling session_start/session_end.');
+            }
+            return lines.join('\n');
+        }
+        // ── recall_at — Brain Archaeology ────────────────────────────────────────
+        case 'recall_at': {
+            const { instance_id, topic, date } = args;
+            const redis = await getConnection(instance_id);
+            const cutoff = new Date(date).getTime();
+            if (isNaN(cutoff))
+                return `❌ Invalid date "${date}". Use ISO format: "2026-01-15"`;
+            const listKey = `cachly:lessons:${topic}`;
+            const all = await redis.lrange(listKey, 0, -1);
+            if (all.length === 0)
+                return `📭 No history found for \`${topic}\`. Lessons are stored via \`learn_from_attempts\`.`;
+            const before = all
+                .map(raw => { try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            } })
+                .filter((l) => l !== null && new Date(l.ts).getTime() <= cutoff)
+                .sort((a, b) => new Date(a.ts).getTime() - new Date(b.ts).getTime());
+            if (before.length === 0)
+                return `📭 No entries for \`${topic}\` found before **${date}**. Earliest entry: ${new Date(JSON.parse(all[0]).ts).toLocaleDateString('de-DE')}.`;
+            const lines = [
+                `🏺 **Brain Archaeology: \`${topic}\` before ${date}**`,
+                `_${before.length} of ${all.length} total entries shown_`,
+                '',
+            ];
+            for (const l of before.slice(-10)) {
+                const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+                const d = new Date(l.ts).toLocaleDateString('de-DE');
+                lines.push(`**${d}** ${emoji} ${l.outcome}`);
+                if (l.what_worked)
+                    lines.push(`  → ${l.what_worked.slice(0, 100)}`);
+                lines.push('');
+            }
+            lines.push(`_Full evolution: ${all.map(r => { try {
+                const l = JSON.parse(r);
+                return l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+            }
+            catch {
+                return '?';
+            } }).join(' → ')}_`);
+            return lines.join('\n');
+        }
+        // ── trace_dependency — Causal Chain ──────────────────────────────────────
+        case 'trace_dependency': {
+            const { instance_id, dependency, mark_review = false } = args;
+            const redis = await getConnection(instance_id);
+            const depKey = `cachly:dep:${dependency}`;
+            const raw = await redis.get(depKey);
+            if (!raw)
+                return `📭 No lessons found that depend on \`${dependency}\`.\n\nAdd dependencies via: \`learn_from_attempts(..., depends_on=["${dependency}"])\``;
+            const topics = JSON.parse(raw);
+            const lines = [
+                `🔗 **Causal Chain: \`${dependency}\`** — ${topics.length} dependent lesson${topics.length === 1 ? '' : 's'}`,
+                '',
+            ];
+            for (const t of topics) {
+                const lessonRaw = await redis.get(`cachly:lesson:best:${t}`);
+                if (!lessonRaw) {
+                    lines.push(`  • \`${t}\` _(lesson deleted)_`);
+                    continue;
+                }
+                const lesson = JSON.parse(lessonRaw);
+                const emoji = lesson.outcome === 'success' ? '✅' : lesson.outcome === 'partial' ? '⚠️' : '❌';
+                const reviewBadge = lesson.needs_review ? ' 🔍 **needs_review**' : '';
+                lines.push(`  ${emoji} \`${t}\` (${lesson.severity ?? 'major'})${reviewBadge}`);
+                if (mark_review) {
+                    const updated = { ...lesson, needs_review: true };
+                    await redis.set(`cachly:lesson:best:${t}`, JSON.stringify(updated));
+                }
+            }
+            if (mark_review) {
+                lines.push('', `🔍 All ${topics.length} lessons marked as **needs_review** — verify they still work with the changed dependency.`);
+            }
+            else {
+                lines.push('', `_Run with \`mark_review: true\` to flag all dependent lessons for re-verification._`);
+            }
+            return lines.join('\n');
+        }
+        // ── global_learn ──────────────────────────────────────────────────────────
+        case 'global_learn': {
+            const { instance_id, topic, lesson, severity = 'minor', tags = [] } = args;
+            const redis = await getConnection(instance_id);
+            const key = `cachly:global:lesson:${topic}`;
+            const record = {
+                topic,
+                lesson,
+                severity,
+                tags,
+                ts: new Date().toISOString(),
+                scope: 'global',
+                recall_count: 0,
+            };
+            // Preserve recall_count on update
+            const existing = await redis.get(key);
+            if (existing) {
+                const prev = JSON.parse(existing);
+                record.recall_count = prev.recall_count ?? 0;
+            }
+            await redis.set(key, JSON.stringify(record));
+            return `🌐 **Global lesson stored**: \`${topic}\`\n\n${lesson}\n\nRecallable from any project via \`global_recall(topic="${topic}")\`.`;
+        }
+        // ── global_recall ─────────────────────────────────────────────────────────
+        case 'global_recall': {
+            const { instance_id, topic } = args;
+            const redis = await getConnection(instance_id);
+            const keys = [];
+            const gStream = redis.scanStream({ match: 'cachly:global:lesson:*', count: 200 });
+            await new Promise((resolve, reject) => {
+                gStream.on('data', (batch) => keys.push(...batch));
+                gStream.on('end', resolve);
+                gStream.on('error', reject);
+            });
+            let lessons = [];
+            for (const k of keys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    lessons.push(JSON.parse(raw));
+                }
+                catch { /* skip */ }
+            }
+            if (topic) {
+                const t = topic.toLowerCase();
+                lessons = lessons.filter(l => l.topic.toLowerCase().includes(t));
+            }
+            if (lessons.length === 0) {
+                return `📭 No global lessons${topic ? ` for \`${topic}\`` : ''}.\n\nAdd cross-project knowledge with \`global_learn(topic="...", lesson="...")\`.`;
+            }
+            // Increment recall_count
+            for (const l of lessons) {
+                const k = `cachly:global:lesson:${l.topic}`;
+                const raw = await redis.get(k);
+                if (raw) {
+                    const rec = JSON.parse(raw);
+                    rec.recall_count = (rec.recall_count ?? 0) + 1;
+                    await redis.set(k, JSON.stringify(rec));
+                }
+            }
+            const lines = [`🌐 **Global Brain** — ${lessons.length} lesson${lessons.length > 1 ? 's' : ''}`, ''];
+            for (const l of lessons) {
+                const sev = l.severity === 'critical' ? '🔴 ' : l.severity === 'major' ? '🟡 ' : '';
+                lines.push(`${sev}**\`${l.topic}\`**`);
+                lines.push(l.lesson.slice(0, 200));
+                lines.push('');
+            }
+            return lines.join('\n');
+        }
+        // ── publish_lesson ────────────────────────────────────────────────────────
+        case 'publish_lesson': {
+            const { instance_id, topic, lesson, framework = 'general', severity = 'minor' } = args;
+            const redis = await getConnection(instance_id);
+            // Strip potential PII patterns (emails, tokens, paths)
+            const sanitized = lesson
+                .replace(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g, '[email]')
+                .replace(/\b(sk-|cky_live_|Bearer\s)[A-Za-z0-9_\-]{8,}/g, '[token]')
+                .replace(/\/Users\/[^\s/]+/g, '/Users/[user]')
+                .replace(/\/home\/[^\s/]+/g, '/home/[user]');
+            const publicLesson = {
+                topic,
+                lesson: sanitized,
+                framework,
+                severity,
+                ts: new Date().toISOString(),
+                published: true,
+                votes: 0,
+            };
+            // Store locally with public flag (future: sync to Cachly public API)
+            const key = `cachly:public:lesson:${framework}:${topic}`;
+            await redis.set(key, JSON.stringify(publicLesson), 'EX', 365 * 86400);
+            return [
+                `📢 **Lesson published!**`,
+                ``,
+                `**Topic:** \`${topic}\``,
+                `**Framework:** ${framework}`,
+                `**Content:** ${sanitized.slice(0, 200)}${sanitized.length > 200 ? '…' : ''}`,
+                ``,
+                `This lesson is now available in the Public Brain for other developers.`,
+                `Import it anywhere: \`import_public_brain(framework="${framework}")\``,
+            ].join('\n');
+        }
+        // ── import_public_brain ───────────────────────────────────────────────────
+        case 'import_public_brain': {
+            const { instance_id, framework, limit = 20 } = args;
+            const redis = await getConnection(instance_id);
+            // Community-curated lessons per framework
+            const COMMUNITY_LESSONS = {
+                nextjs: [
+                    { topic: 'nextjs:image-layout', lesson: 'Use fill + relative parent instead of layout="fill" (deprecated since Next.js 13)', severity: 'major' },
+                    { topic: 'nextjs:app-router-fetch', lesson: 'fetch() in Server Components is cached by default — add {cache:"no-store"} for dynamic data', severity: 'major' },
+                    { topic: 'nextjs:metadata-export', lesson: 'Export metadata const or generateMetadata() — never both in same file', severity: 'minor' },
+                    { topic: 'nextjs:client-boundary', lesson: '"use client" propagates down — keep it at the lowest component, not at page level', severity: 'major' },
+                    { topic: 'nextjs:env-prefix', lesson: 'Only NEXT_PUBLIC_* env vars are exposed to client — others are server-only', severity: 'critical' },
+                    { topic: 'nextjs:revalidate', lesson: 'export const revalidate = 0 disables caching for entire route; use revalidatePath() for on-demand', severity: 'minor' },
+                ],
+                fastapi: [
+                    { topic: 'fastapi:async-db', lesson: 'Use async session with asyncpg — sync SQLAlchemy blocks the event loop', severity: 'critical' },
+                    { topic: 'fastapi:pydantic-v2', lesson: 'Pydantic v2: use model_validate() instead of parse_obj(), .dict() → .model_dump()', severity: 'major' },
+                    { topic: 'fastapi:lifespan', lesson: 'Use lifespan context manager instead of deprecated on_event startup/shutdown', severity: 'minor' },
+                    { topic: 'fastapi:background-tasks', lesson: 'BackgroundTasks run after response is sent — not in a separate thread pool', severity: 'major' },
+                    { topic: 'fastapi:cors-order', lesson: 'CORSMiddleware must be added before other middleware to work correctly', severity: 'critical' },
+                ],
+                go: [
+                    { topic: 'go:context-cancel', lesson: 'Always call cancel() from context.WithCancel — leak goroutines if not cancelled', severity: 'critical' },
+                    { topic: 'go:defer-in-loop', lesson: 'defer in a loop runs at function return, not loop iteration — use IIFE or explicit close', severity: 'major' },
+                    { topic: 'go:nil-interface', lesson: 'nil interface != interface containing nil pointer — use explicit nil checks', severity: 'major' },
+                    { topic: 'go:goroutine-leak', lesson: 'Goroutines with channel sends block forever if receiver is gone — use select with done chan', severity: 'critical' },
+                    { topic: 'go:embed-path', lesson: '//go:embed path must be relative and known at compile time — no os.Getenv', severity: 'minor' },
+                ],
+                docker: [
+                    { topic: 'docker:layer-cache', lesson: 'Copy package.json before source code — Docker caches layers, npm install only reruns on dep changes', severity: 'major' },
+                    { topic: 'docker:non-root', lesson: 'Run as non-root user (USER 1001) — some k8s clusters reject root containers by policy', severity: 'critical' },
+                    { topic: 'docker:build-arg-secret', lesson: 'Never use ARG for secrets — visible in image history. Use --secret mount instead', severity: 'critical' },
+                    { topic: 'docker:entrypoint-exec', lesson: 'Use exec form ["cmd","arg"] not shell form "cmd arg" — shell form ignores SIGTERM', severity: 'major' },
+                    { topic: 'docker:multi-stage', lesson: 'Multi-stage builds: copy only built artifacts to final stage — keep image small', severity: 'minor' },
+                ],
+                kubernetes: [
+                    { topic: 'k8s:resource-limits', lesson: 'Always set resource limits — unbounded pods cause node evictions and OOMKill', severity: 'critical' },
+                    { topic: 'k8s:liveness-vs-readiness', lesson: 'Liveness failures restart pod; Readiness failures remove from LB. Use different endpoints', severity: 'major' },
+                    { topic: 'k8s:imagepullpolicy', lesson: 'imagePullPolicy: Always in production — IfNotPresent can serve stale images', severity: 'major' },
+                    { topic: 'k8s:configmap-env', lesson: 'ConfigMap changes don\'t restart pods — use rollout restart or mount as volume', severity: 'critical' },
+                    { topic: 'k8s:pdb', lesson: 'Set PodDisruptionBudget for stateful apps — node drains kill all pods without it', severity: 'major' },
+                ],
+                react: [
+                    { topic: 'react:useeffect-deps', lesson: 'Omitting dependencies from useEffect deps array causes stale closure bugs — use exhaustive-deps ESLint rule', severity: 'critical' },
+                    { topic: 'react:key-index', lesson: 'Never use array index as key in lists — causes subtle re-render bugs on reorder/delete', severity: 'major' },
+                    { topic: 'react:setState-in-render', lesson: 'setState() during render causes infinite loop — move to useEffect or event handler', severity: 'critical' },
+                    { topic: 'react:memo-reference', lesson: 'Object/array literals in JSX recreate on every render — useMemo for expensive derived values', severity: 'minor' },
+                ],
+                typescript: [
+                    { topic: 'ts:type-guard', lesson: 'Use "x is Type" return type for type guard functions — not "boolean"', severity: 'minor' },
+                    { topic: 'ts:strict-null', lesson: 'Enable strictNullChecks in tsconfig — catches 90% of runtime null errors at compile time', severity: 'critical' },
+                    { topic: 'ts:enum-avoid', lesson: 'Prefer union types ("a"|"b") over enum — enums have surprising runtime behavior', severity: 'minor' },
+                    { topic: 'ts:satisfies', lesson: 'Use "satisfies" operator to validate type without widening — more precise than explicit annotation', severity: 'minor' },
+                ],
+                python: [
+                    { topic: 'python:mutable-default', lesson: 'Never use mutable default arguments (def f(x=[])) — shared across all calls. Use None + guard', severity: 'critical' },
+                    { topic: 'python:walrus-operator', lesson: ':= (walrus) assigns and returns — useful in while/comprehensions but hard to read in complex expr', severity: 'minor' },
+                    { topic: 'python:asyncio-run', lesson: 'asyncio.run() creates new event loop — calling it inside an existing loop raises RuntimeError', severity: 'major' },
+                    { topic: 'python:typing-optional', lesson: 'Optional[X] == Union[X, None] — in Python 3.10+ use X | None syntax', severity: 'minor' },
+                ],
+            };
+            const fw = framework.toLowerCase();
+            const lessons = COMMUNITY_LESSONS[fw];
+            if (!lessons) {
+                const available = Object.keys(COMMUNITY_LESSONS).join(', ');
+                return `❌ No public brain available for \`${framework}\`.\n\nAvailable: ${available}\n\nOr publish your own: \`publish_lesson(framework="${framework}", ...)\``;
+            }
+            const toImport = lessons.slice(0, limit);
+            let importedCount = 0;
+            for (const l of toImport) {
+                const key = `cachly:lesson:best:${l.topic}`;
+                const existing = await redis.get(key);
+                if (!existing) {
+                    await redis.set(key, JSON.stringify({
+                        ...l,
+                        what_worked: l.lesson,
+                        outcome: 'success',
+                        ts: new Date().toISOString(),
+                        recall_count: 0,
+                        source: 'public_brain',
+                        version: 2,
+                    }));
+                    importedCount++;
+                }
+            }
+            const lines = [
+                `📥 **Public Brain imported: ${framework}**`,
+                ``,
+                `${importedCount} new lessons added (${toImport.length - importedCount} already existed)`,
+                ``,
+                `**Imported topics:**`,
+                ...toImport.map(l => {
+                    const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '💡';
+                    return `  ${sev} \`${l.topic}\``;
+                }),
+                ``,
+                `These lessons will now appear in \`session_start\` when relevant.`,
+                `Recall any time: \`recall_best_solution(topic="${fw}:...")\``,
+            ];
+            return lines.join('\n');
+        }
+        // ── setup_ai_memory ───────────────────────────────────────────────────────
+        case 'setup_ai_memory': {
+            const { instance_id, project_dir, embed_provider: providerArg = 'openai', project_description = 'a software project', } = args;
+            const inst = await apiFetch(`/api/v1/instances/${instance_id}`);
+            // Provider-specific env var instructions
+            const providerEnvMap = {
+                openai: { key: 'OPENAI_API_KEY', hint: 'Get at: https://platform.openai.com/api-keys' },
+                mistral: { key: 'MISTRAL_API_KEY', hint: 'Get at: https://console.mistral.ai/api-keys' },
+                cohere: { key: 'COHERE_API_KEY', hint: 'Get at: https://dashboard.cohere.com/api-keys' },
+                ollama: { key: 'OLLAMA_BASE_URL', hint: 'Run: brew install ollama && ollama serve  (free, local, no key needed)' },
+                gemini: { key: 'GEMINI_API_KEY', hint: 'Get at: https://aistudio.google.com/app/apikey' },
+            };
+            const provInfo = providerEnvMap[providerArg] ?? providerEnvMap['openai'];
+            const hasVector = !!inst.vector_token;
+            // Generate .mcp.json snippet
+            const mcpJsonSnippet = JSON.stringify({
+                mcpServers: {
+                    cachly: {
+                        command: 'npx',
+                        args: ['-y', '@cachly-dev/mcp-server@latest'],
+                        env: {
+                            CACHLY_JWT: 'your-api-token-from-cachly.dev/settings',
+                            [provInfo.key]: providerArg === 'ollama' ? 'http://localhost:11434' : 'your-key-here',
+                            ...(providerArg !== 'openai' ? { CACHLY_EMBED_PROVIDER: providerArg } : {}),
+                        },
+                    },
+                },
+            }, null, 2);
+            // Generate copilot-instructions.md content
+            const tier = inst.tier.toUpperCase();
+            const smartRecallNote = hasVector
+                ? '- `smart_recall("natural language query")` — semantic search (finds by meaning)'
+                : '- `recall_context("arch:*")` — exact/glob key lookup (upgrade to Speed/Business for smart_recall)';
+            const layerNote = hasVector
+                ? `Layer 3 (Semantic): smart_recall uses pgvector HNSW on your ${tier} instance`
+                : `Layer 3 (Autopilot): this file — upgrade to Speed/Business tier to unlock smart_recall`;
+            const copilotInstructions = `# cachly AI Brain — ${project_description}
+
+> AI memory system powered by [cachly.dev](https://cachly.dev). Works with GitHub Copilot, Claude Code, Cursor, Windsurf, Continue.dev, and any MCP-compatible editor.
+
+---
+
+## 🔴 MANDATORY RULES — Always enforced, no exceptions
+
+### Rule 1 — Session Start (FIRST thing in every window)
+Call \`session_start\` **before reading any source files or making any changes**:
+
+\`\`\`
+session_start(
+  instance_id = "${instance_id}",
+  focus       = "<what you plan to work on today>",
+)
+\`\`\`
+
+Returns: last session summary, handoff from previous window, recent lessons, open failures, brain health.
+
+**If \`session_start\` is unavailable**, fall back:
+1. \`smart_recall("recent lessons <topic>")\`
+2. \`recall_best_solution("<topic>")\`
+
+### Rule 2 — Learn After Every Fix/Deploy/Discovery (AUTOMATIC — no prompting needed)
+After **every** bug fix, deployment, failed attempt, or discovery — call \`learn_from_attempts\` immediately:
+
+\`\`\`
+learn_from_attempts(
+  instance_id = "${instance_id}",
+  topic       = "category:keyword",   # deploy:web | fix:auth | debug:db | infra:docker
+  outcome     = "success" | "failure" | "partial",
+  what_worked = "exact approach or command that worked",
+  what_failed = "what did NOT work (prevents future wasted time)",
+  severity    = "critical" | "major" | "minor",
+  commands    = ["exact command that worked"],
+  file_paths  = ["path/to/changed/file"],
+)
+\`\`\`
+
+**These events MUST automatically trigger \`learn_from_attempts\`:**
+- ✅ Successfully deployed → \`topic="deploy:<component>", outcome="success"\`
+- ✅ Fixed a bug → \`topic="fix:<description>", outcome="success"\`
+- ✅ Discovered root cause → \`topic="debug:<area>", outcome="partial"\`
+- ✅ Tried something that failed → \`topic="<area>", outcome="failure", what_failed="..."\`
+- ✅ Found a config quirk → \`topic="infra:<topic>", outcome="success"\`
+- ✅ Ran a working command → store it in \`commands=[...]\`
+
+### Rule 3 — Session Handoff (when closing window or task list > 3 items)
+\`\`\`
+session_handoff(
+  instance_id     = "${instance_id}",
+  completed_tasks = ["what was done"],
+  remaining_tasks = ["what is still to do"],
+  files_changed   = [{"path": "src/...", "status": "modified", "description": "what changed"}],
+  instructions    = "IMPORTANT: what the next window MUST know to not break things",
+  context_summary = "current state of the system",
+)
+\`\`\`
+
+The next \`session_start\` automatically includes this handoff. The new window sees exactly what's done, what remains, and what NOT to break.
+
+### Rule 4 — Session End (LAST thing before closing)
+\`\`\`
+session_end(
+  instance_id     = "${instance_id}",
+  summary         = "What was accomplished (2-3 sentences with specifics)",
+  files_changed   = ["list", "of", "changed", "files"],
+  lessons_learned = <number of learn_from_attempts calls made>,
+)
+\`\`\`
+
+> \`session_end\` **automatically extracts and stores lessons** from the summary text — no manual calls needed.
+
+### Rule 5 — Code Index Invalidation (AUTOMATIC)
+- \`index_project\` tracks MD5 hashes per file — **skips unchanged files automatically**
+- After code changes: next \`index_project\` run re-indexes only modified files
+- After delete/rename: run \`index_project\` again to sync
+- No manual invalidation needed
+
+---
+
+## Task-type trigger table
+
+| You're about to... | Call BEFORE | Call AFTER |
+|---|---|---|
+| Deploy anything | \`recall_best_solution("deploy:<component>")\` | \`learn_from_attempts(topic="deploy:...")\` |
+| Fix a bug | \`recall_best_solution("fix:<area>")\` | \`learn_from_attempts(topic="fix:...")\` |
+| Add a feature | \`session_start(focus="feat:<area>")\` | \`learn_from_attempts(topic="feat:...")\` |
+| Infra/server work | \`recall_best_solution("infra:<topic>")\` | \`learn_from_attempts(topic="infra:...")\` |
+| Debug an issue | \`smart_recall("<error message or symptom>")\` | \`learn_from_attempts(topic="debug:...")\` |
+
+---
+
+## Available Brain Tools
+
+| Tool | When to use |
+|------|-------------|
+| \`session_start\` | **FIRST** — mandatory at start of every session |
+| \`session_end\` | **LAST** — mandatory at end, auto-learns from summary |
+| \`session_handoff\` | When closing window with remaining tasks |
+| \`learn_from_attempts\` | **AUTOMATIC** after every fix/deploy/discovery |
+| \`recall_best_solution\` | Before any non-trivial task |
+| \`remember_context\` | After analyzing code — save findings for future sessions |
+${smartRecallNote ? `| \`smart_recall\` | Search brain by meaning/keywords |\n` : ''}\
+| \`recall_context\` | Get exact key (supports glob: \`arch:*\`, \`file:*\`) |
+| \`brain_search\` | BM25+ full-text search over all brain data |
+| \`auto_learn_session\` | Batch-learn from a list of observations (optional) |
+| \`index_project\` | Index source files (smart hash, skips unchanged files) |
+| \`list_remembered\` | See what's cached in the brain |
+| \`forget_context\` | Remove stale context |
+
+---
+
+## Instance Details
+
+- **Instance ID:** \`${instance_id}\`
+- **Instance name:** ${inst.name}
+- **Tier:** ${tier}
+- **${layerNote}**
+- **Embedding provider:** ${providerArg}
+
+---
+
+## How the 3-layer system works
+
+\`\`\`
+Layer 1 — Storage:  Your cachly Valkey instance (${inst.name}) — persists forever
+Layer 2 — Tools:    learn_from_attempts · recall_best_solution · brain_search · session_start/end
+Layer 3 — Autopilot: This file — AI reads it and runs tools automatically every session
+\`\`\`
+
+Result: Your AI **never solves the same problem twice** and always picks up exactly where it left off. 🚀
+`;
+            const lines = [
+                `🧠 **cachly AI Memory Setup Complete**`,
+                ``,
+                `**Instance:** ${inst.name} (${tier}) · ID: \`${instance_id}\``,
+                `**Embedding Provider:** ${providerArg}`,
+                `**Semantic Search:** ${hasVector ? '✅ pgvector HNSW available' : '⚠️  Not available on ' + tier + ' — upgrade to Speed/Business'}`,
+                ``,
+                `─────────────────────────────────────────────`,
+                `**Step 1 — Add to .mcp.json:**`,
+                `\`\`\`json`,
+                mcpJsonSnippet,
+                `\`\`\``,
+                ``,
+                `**Step 2 — Set your ${providerArg} key:**`,
+                `\`\`\`bash`,
+                `export ${provInfo.key}="your-key-here"`,
+                `\`\`\``,
+                `_(${provInfo.hint})_`,
+                ``,
+                `─────────────────────────────────────────────`,
+                `**Step 3 — copilot-instructions.md (Layer 3 Autopilot):**`,
+                ``,
+                ...(project_dir
+                    ? [`🔍 Detecting IDEs in \`${project_dir}\`…`]
+                    : [`Copy this to \`.github/copilot-instructions.md\` (Copilot), \`CLAUDE.md\` (Claude Code), or \`.cursor/rules\` (Cursor) in your project:`]),
+                ``,
+                `\`\`\`markdown`,
+                copilotInstructions,
+                `\`\`\``,
+                ``,
+                `─────────────────────────────────────────────`,
+                `**How the 3 layers work together:**`,
+                `  Layer 1 → Your Valkey instance stores all lessons + context (persists forever)`,
+                `  Layer 2 → MCP tools (learn_from_attempts, recall_best_solution, smart_recall) read/write it`,
+                `  Layer 3 → copilot-instructions.md makes your AI run them automatically`,
+                ``,
+                `Result: Your AI never solves the same problem twice. 🚀`,
+            ];
+            // ── IDE auto-detection + file writing ────────────────────────────────
+            if (project_dir) {
+                const { mkdir, writeFile, access } = await import('node:fs/promises');
+                const { constants } = await import('node:fs');
+                const exists = async (p) => access(p, constants.F_OK).then(() => true).catch(() => false);
+                const targets = [];
+                let stopHookWritten = false;
+                // GitHub Copilot — always write (universal fallback)
+                targets.push({
+                    ide: 'GitHub Copilot',
+                    path: join(project_dir, '.github', 'copilot-instructions.md'),
+                    content: copilotInstructions,
+                });
+                // Claude Code — CLAUDE.md in project root
+                if (await exists(join(project_dir, 'CLAUDE.md')) || await exists(join(project_dir, '.claude'))) {
+                    targets.push({
+                        ide: 'Claude Code',
+                        path: join(project_dir, 'CLAUDE.md'),
+                        content: copilotInstructions,
+                    });
+                    // Claude Code Stop-Hook — auto-saves checkpoint when Claude stops responding
+                    const claudeDir = join(project_dir, '.claude');
+                    await mkdir(claudeDir, { recursive: true });
+                    const stopHook = {
+                        hooks: {
+                            Stop: [
+                                {
+                                    matcher: '',
+                                    hooks: [
+                                        {
+                                            type: 'command',
+                                            command: `npx --yes @cachly-dev/mcp-server@latest checkpoint --instance-id ${instance_id}`,
+                                        },
+                                    ],
+                                },
+                            ],
+                        },
+                    };
+                    const settingsPath = join(claudeDir, 'settings.json');
+                    let existingSettings = {};
+                    try {
+                        const { readFile: rf } = await import('node:fs/promises');
+                        existingSettings = JSON.parse(await rf(settingsPath, 'utf-8'));
+                    }
+                    catch { /* new file */ }
+                    const merged = { ...existingSettings, hooks: stopHook.hooks };
+                    await writeFile(settingsPath, JSON.stringify(merged, null, 2), 'utf-8');
+                    stopHookWritten = true;
+                }
+                // Cursor — .cursor/rules (new format) or .cursorrules (legacy)
+                if (await exists(join(project_dir, '.cursor')) ||
+                    await exists(join(project_dir, '.cursorrules'))) {
+                    const cursorDir = join(project_dir, '.cursor');
+                    await mkdir(cursorDir, { recursive: true });
+                    targets.push({
+                        ide: 'Cursor',
+                        path: join(cursorDir, 'rules'),
+                        content: copilotInstructions,
+                    });
+                }
+                // Windsurf — .windsurfrules
+                if (await exists(join(project_dir, '.windsurfrules')) ||
+                    await exists(join(project_dir, '.windsurf'))) {
+                    targets.push({
+                        ide: 'Windsurf',
+                        path: join(project_dir, '.windsurfrules'),
+                        content: copilotInstructions,
+                    });
+                }
+                // VS Code (Copilot) — already covered by .github/copilot-instructions.md above
+                // Continue.dev — .continue/config.json is JSON, not markdown — skip, copilot-instructions handles it
+                const written = [];
+                for (const target of targets) {
+                    const dir = target.path.substring(0, target.path.lastIndexOf('/'));
+                    await mkdir(dir, { recursive: true });
+                    await writeFile(target.path, target.content, 'utf-8');
+                    written.push(`✅ [${target.ide}] → \`${target.path.replace(project_dir, '.')}\``);
+                }
+                if (stopHookWritten) {
+                    written.push(`✅ [Claude Code Stop-Hook] → \`.claude/settings.json\` (auto-checkpoint on stop)`);
+                }
+                lines.push(...written);
+            }
+            return lines.join('\n');
+        }
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=team.js.map