@cachly-dev/mcp-server 0.9.17 → 0.9.18

package/dist/handlers/brain.js

@@ -0,0 +1,1322 @@
+import { execSync } from 'node:child_process';
+import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES, CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS } from '../confidence.js';
+import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
+import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
+import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
+export const BRAIN_TOOL_NAMES = new Set([
+    'learn_from_attempts', 'recall_best_solution', 'smart_recall',
+    'session_start', 'session_end', 'session_ping', 'session_handoff', 'auto_learn_session',
+]);
+export async function handleBrainTool(name, args, getConnection, apiFetch) {
+    switch (name) {
+        case 'learn_from_attempts': {
+            const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], author = '', } = args;
+            const redis = await getConnection(instance_id);
+            const ts = new Date().toISOString();
+            // ── Structured template hints ──────────────────────────────────────────
+            const category = topic.split(':')[0];
+            const template = STRUCTURED_TEMPLATES[category];
+            const templateWarnings = [];
+            if (template) {
+                for (const req of template.required) {
+                    if (req === 'commands' && commands.length === 0) {
+                        templateWarnings.push(`📋 ${template.hint}`);
+                    }
+                }
+            }
+            // ── Deduplication + audit trail ────────────────────────────────────────
+            let isUpdate = false;
+            let recallCount = 0;
+            let auditTrail = [];
+            const existingRaw = await redis.get(`cachly:lesson:best:${topic}`);
+            if (existingRaw) {
+                try {
+                    const prev = JSON.parse(existingRaw);
+                    recallCount = prev.recall_count ?? 0;
+                    auditTrail = prev.audit_trail ?? [];
+                    auditTrail.push({ ts, action: 'updated', prev_outcome: prev.outcome });
+                    if (auditTrail.length > 20)
+                        auditTrail = auditTrail.slice(-20);
+                    isUpdate = true;
+                    // ── Contradiction detection ─────────────────────────────────────────
+                    const contradictionWarning = [];
+                    if (prev.outcome === 'success' && outcome === 'failure') {
+                        contradictionWarning.push(`⚠️ **Contradiction detected!** Existing lesson has outcome: \`success\`, but you're storing \`failure\`.`, `The existing "success" lesson will be preserved. Only the audit trail is updated.`, `If you meant to mark this as failed permanently, store a new lesson with a distinct topic slug.`);
+                    }
+                    else if (prev.outcome === 'failure' && outcome === 'success') {
+                        contradictionWarning.push(`✅ **Conflict resolved!** Previous lesson was \`failure\` — now overwriting with \`success\`.`);
+                    }
+                    if (contradictionWarning.length > 0) {
+                        // Store contradiction audit but don't block
+                        auditTrail[auditTrail.length - 1].action = 'contradiction-resolved';
+                        // Layer 3: Write CKG contradicts edge for MADC to process
+                        try {
+                            const cId = ckgSlug(topic);
+                            const resId = ckgSlug(`resolution:${topic}`);
+                            await ckgUpdateEdge(redis, cId, 'contradicts', resId, false);
+                        }
+                        catch { /* non-critical */ }
+                        contradictionWarning.push(`🗳️ Run \`madc_deliberate(topic="${topic}")\` to resolve via expert agent voting.`);
+                    }
+                }
+                catch { /* ignore parse error */ }
+            }
+            else {
+                auditTrail = [{ ts, action: 'created' }];
+            }
+            // ── "I Was Wrong" Protocol — failure attribution ───────────────────────
+            const iWasWrongWarning = [];
+            if (outcome === 'failure') {
+                // Search for related success lessons that might have prevented this failure
+                const scanKeys = [];
+                const scanStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 100 });
+                await new Promise((res, rej) => {
+                    scanStream.on('data', (b) => scanKeys.push(...b));
+                    scanStream.on('end', res);
+                    scanStream.on('error', rej);
+                });
+                const topicWords = topic.split(/[:\-_]/).filter(w => w.length > 2);
+                for (const k of scanKeys.slice(0, 50)) {
+                    const raw = await redis.get(k);
+                    if (!raw)
+                        continue;
+                    try {
+                        const l = JSON.parse(raw);
+                        if (l.outcome !== 'success')
+                            continue;
+                        const lWords = (l.topic ?? '').split(/[:\-_]/).filter(w => w.length > 2);
+                        const overlap = topicWords.filter(w => lWords.includes(w)).length;
+                        if (overlap >= 1 && l.topic !== topic) {
+                            iWasWrongWarning.push(`⚠️ **"I Was Wrong"**: lesson \`${l.topic}\` (success, ${l.severity ?? 'major'}) might have prevented this failure.`, `   → Use \`recall_best_solution(topic="${l.topic}")\` before next attempt.`, `   → To mark it critical: \`learn_from_attempts(topic="${l.topic}", ..., severity="critical")\``);
+                            break; // only show the most relevant match
+                        }
+                    }
+                    catch { /* skip */ }
+                }
+            }
+            // ── Register dependency index for causal chain ─────────────────────────
+            for (const dep of depends_on) {
+                const depKey = `cachly:dep:${dep}`;
+                const existing = await redis.get(depKey);
+                const depTopics = existing ? JSON.parse(existing) : [];
+                if (!depTopics.includes(topic))
+                    depTopics.push(topic);
+                await redis.set(depKey, JSON.stringify(depTopics));
+            }
+            const lessonObj = {
+                topic,
+                outcome,
+                what_worked,
+                what_failed,
+                context: ctx,
+                severity,
+                file_paths,
+                commands,
+                tags,
+                depends_on,
+                ...(author ? { author } : {}),
+                recall_count: recallCount,
+                ts,
+                verified_at: outcome === 'success' || outcome === 'partial' ? ts : undefined,
+                confidence: 1.0,
+                audit_trail: auditTrail,
+                version: 3,
+            };
+            const lesson = JSON.stringify(lessonObj);
+            // Always append to the history list (audit log)
+            const listKey = `cachly:lessons:${topic}`;
+            await redis.rpush(listKey, lesson);
+            // Update best key for success/partial; for failure only update if no success exists
+            if (outcome === 'success' || outcome === 'partial') {
+                await redis.set(`cachly:lesson:best:${topic}`, lesson);
+            }
+            else if (!existingRaw) {
+                await redis.set(`cachly:lesson:best:${topic}`, lesson);
+            }
+            // Track in decision log for session replay
+            try {
+                const dlKey = 'cachly:session:decision-log';
+                const dlEntry = JSON.stringify({ ts, topic, outcome, what_worked: what_worked.slice(0, 120) });
+                await redis.rpush(dlKey, dlEntry);
+                await redis.ltrim(dlKey, -50, -1);
+            }
+            catch { /* non-critical */ }
+            // ── Layer 1+2: CKG update (Causal Knowledge Graph + Belief Update Engine) ──
+            // BUE: Bayesian confidence, contradiction detection, second-degree propagation, decay
+            let beliefConflict = null;
+            try {
+                const conceptId = ckgSlug(topic);
+                const domain = topic.split(':')[0] ?? 'unknown';
+                const conceptType = domain; // fix, debug, deploy, infra, api, etc.
+                // Upsert concept node
+                await ckgUpsertNode(redis, conceptId, domain, conceptType);
+                // Tag co-occurrence edges
+                for (const tag of tags) {
+                    const tagId = ckgSlug(`tag:${tag}`);
+                    await ckgUpsertNode(redis, tagId, 'tag', 'tag');
+                    await ckgUpdateEdge(redis, conceptId, 'co-occurs', tagId, outcome === 'success', outcome === 'partial');
+                }
+                // depends_on → requires edges (structural, always confidence 1.0 direction)
+                for (const dep of depends_on) {
+                    const depId = ckgSlug(dep);
+                    await ckgUpdateEdge(redis, conceptId, 'requires', depId, true);
+                }
+                // fixes edge: if category=fix and outcome=success, link to problem concept
+                if ((domain === 'fix' || domain === 'debug') && (outcome === 'success' || outcome === 'partial')) {
+                    const problemText = what_failed || ctx || '';
+                    const problemConcept = problemText ? extractProblemConcept(problemText) : null;
+                    if (problemConcept) {
+                        const problemId = ckgSlug(`problem:${problemConcept}`);
+                        await ckgUpsertNode(redis, problemId, 'problem', 'problem');
+                        await ckgUpdateEdge(redis, conceptId, 'fixes', problemId, outcome === 'success', outcome === 'partial');
+                    }
+                }
+                // causes edge: if outcome=failure, link topic concept to the problem context
+                if (outcome === 'failure' && (what_failed || what_worked)) {
+                    const causeText = what_failed || what_worked;
+                    const causeConcept = extractProblemConcept(causeText);
+                    if (causeConcept) {
+                        const causeId = ckgSlug(`cause:${causeConcept}`);
+                        await ckgUpsertNode(redis, causeId, 'cause', 'cause');
+                        await ckgUpdateEdge(redis, conceptId, 'causes', causeId, false);
+                    }
+                }
+                // ── BUE: Contradiction detection ──────────────────────────────────────
+                // If this topic previously had a confirmed 'fixes' edge (confidence > 0.7)
+                // and now outcome=failure → flag belief_conflict
+                if (outcome === 'failure') {
+                    const existingEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${conceptId}`);
+                    for (const ek of existingEdgeKeys) {
+                        const er = await redis.get(ek);
+                        if (!er)
+                            continue;
+                        const existEdge = JSON.parse(er);
+                        if (existEdge.edgeType === 'fixes' && existEdge.confidence > 0.7 && existEdge.trials >= 3) {
+                            beliefConflict = `⚠️ **belief_conflict** on \`${topic}\`: previously confirmed fix (confidence ${existEdge.confidence.toFixed(2)}, n=${existEdge.trials}) now reports failure. Both beliefs retained as \`contested\`. Use \`ckg_inspect(concept="${conceptId}")\` to review.`;
+                            // Store conflict marker
+                            const conflictKey = `cachly:ckg:conflict:${conceptId}`;
+                            await redis.set(conflictKey, JSON.stringify({ topic, detected_at: new Date().toISOString(), fix_confidence: existEdge.confidence, fix_trials: existEdge.trials, failure_outcome: outcome }), 'EX', 60 * 60 * 24 * 90);
+                            // Auto-trigger MADC deliberation in background — never blocks learn_from_attempts
+                            // Note: fire-and-forget; madc_deliberate is handled elsewhere in the switch
+                            apiFetch(`/api/v1/instances/${instance_id}`).catch(() => undefined); // keep apiFetch warm
+                        }
+                    }
+                }
+                // ── BUE: Second-degree propagation ────────────────────────────────────
+                // When a 'fixes' edge gets stronger, boost co-occurring second-degree edges slightly
+                if (outcome === 'success' && (domain === 'fix' || domain === 'debug')) {
+                    const fromEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${conceptId}`);
+                    for (const ek of fromEdgeKeys.slice(0, 10)) {
+                        const er = await redis.get(ek);
+                        if (!er)
+                            continue;
+                        const e2 = JSON.parse(er);
+                        if (e2.edgeType !== 'fixes')
+                            continue;
+                        // Boost second-degree: edges from e2.to get a small fractional success
+                        const secondKeys = await redis.smembers(`cachly:ckg:idx:from:${e2.to}`);
+                        for (const sk of secondKeys.slice(0, 5)) {
+                            const sr = await redis.get(sk);
+                            if (!sr)
+                                continue;
+                            const se = JSON.parse(sr);
+                            if (se.edgeType !== 'co-occurs')
+                                continue;
+                            // Add 0.1 fractional success (second-degree signal)
+                            se.successes = (se.successes || 0) + 0.1;
+                            se.trials = (se.trials || 0) + 0.1;
+                            se.confidence = (se.successes + 1) / (se.trials + 2);
+                            se.last_updated = new Date().toISOString();
+                            await redis.set(sk, JSON.stringify(se));
+                        }
+                    }
+                }
+                // ── BUE: Stale edge decay ─────────────────────────────────────────────
+                // Edges older than 90 days with < 3 trials decay by 10% confidence.
+                // Only run probabilistically (1% of calls) to avoid per-call overhead.
+                if (Math.random() < 0.01) {
+                    const decayCutoff = Date.now() - 90 * 24 * 60 * 60 * 1000;
+                    const fromEdgeKeys = await redis.smembers(`cachly:ckg:idx:from:${conceptId}`);
+                    for (const ek of fromEdgeKeys) {
+                        const er = await redis.get(ek);
+                        if (!er)
+                            continue;
+                        const de = JSON.parse(er);
+                        if (de.trials < 3 && de.last_updated && new Date(de.last_updated).getTime() < decayCutoff) {
+                            de.confidence = de.confidence * 0.9;
+                            de.last_updated = new Date().toISOString();
+                            await redis.set(ek, JSON.stringify(de));
+                        }
+                    }
+                }
+            }
+            catch { /* CKG updates are non-critical */ }
+            const emoji = outcome === 'success' ? '✅' : outcome === 'partial' ? '⚠️' : '❌';
+            const sevEmoji = severity === 'critical' ? '🔴' : severity === 'major' ? '🟡' : '🟢';
+            const action = isUpdate ? 'updated' : 'stored';
+            return [
+                `${emoji} **Lesson ${action}:** \`${topic}\` (${outcome}) ${sevEmoji} ${severity}`,
+                beliefConflict ?? '',
+                ``,
+                `**What worked:** ${what_worked}`,
+                what_failed ? `**What failed:** ${what_failed}` : '',
+                ctx ? `**Context:** ${ctx}` : '',
+                file_paths.length > 0 ? `**Files:** ${file_paths.map(f => `\`${f}\``).join(', ')}` : '',
+                commands.length > 0 ? `**Commands:** ${commands.map(c => `\`${c}\``).join(', ')}` : '',
+                tags.length > 0 ? `**Tags:** ${tags.map(t => `#${t}`).join(' ')}` : '',
+                ``,
+                isUpdate
+                    ? `♻️ Updated (recall count: ${recallCount} · audit entries: ${auditTrail.length})`
+                    : `💡 Recall later with \`recall_best_solution(topic="${topic}")\``,
+                depends_on.length > 0
+                    ? `🔗 Depends on: ${depends_on.map(d => `\`${d}\``).join(', ')} → trace with \`trace_dependency\``
+                    : '',
+                ...templateWarnings,
+                ...iWasWrongWarning,
+            ].filter(l => l !== '').join('\n');
+        }
+        case 'recall_best_solution': {
+            const { instance_id, topic } = args;
+            const redis = await getConnection(instance_id);
+            // Try exact best-solution key first
+            const best = await redis.get(`cachly:lesson:best:${topic}`);
+            if (best) {
+                const lesson = JSON.parse(best);
+                // ── Confidence decay check ───────────────────────────────────────────
+                const confidence = calculateConfidence(lesson);
+                const ref = lesson.verified_at ?? lesson.ts;
+                const ageDays = (Date.now() - new Date(ref).getTime()) / 86400000;
+                const badge = confidenceBadge(confidence, ageDays);
+                // Recall resets verified_at (confidence clock restart)
+                const updatedLesson = {
+                    ...lesson,
+                    recall_count: (lesson.recall_count ?? 0) + 1,
+                    verified_at: new Date().toISOString(),
+                    confidence: 1.0,
+                };
+                await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(updatedLesson));
+                const sevEmoji = lesson.severity === 'critical' ? '🔴' : lesson.severity === 'major' ? '🟡' : lesson.severity ? '🟢' : '';
+                const auditSummary = (lesson.audit_trail ?? []).length > 1
+                    ? `_Audit: ${(lesson.audit_trail ?? []).length} changes · stored ${new Date(lesson.ts).toLocaleDateString('de-DE')}_`
+                    : '';
+                // "Remember when..." — emotional header for lessons > 60 days old
+                const ageFromStoreDays = (Date.now() - new Date(lesson.ts).getTime()) / 86400000;
+                const rememberWhen = ageFromStoreDays > 60
+                    ? `💭 _Remember when you solved this ${Math.round(ageFromStoreDays / 30)} months ago? Still works._`
+                    : '';
+                // "Never Google This Again" — suggest pinning after 3rd recall
+                const suggestPin = updatedLesson.recall_count === 3 && !lesson.pinned
+                    ? `📌 **You've looked this up 3 times.** Consider pinning it for instant access: add \`pinned: true\` via \`learn_from_attempts\` to always surface it first.`
+                    : '';
+                return [
+                    rememberWhen,
+                    `${badge} **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}×`,
+                    ``,
+                    `**What worked:** ${lesson.what_worked}`,
+                    lesson.what_failed ? `**What failed (avoid this):** ${lesson.what_failed}` : '',
+                    lesson.context ? `**Context:** ${lesson.context}` : '',
+                    (lesson.file_paths ?? []).length > 0 ? `**Files:** ${(lesson.file_paths ?? []).map((f) => `\`${f}\``).join(', ')}` : '',
+                    (lesson.commands ?? []).length > 0 ? `**Commands:** ${(lesson.commands ?? []).map((c) => `\`${c}\``).join(', ')}` : '',
+                    (lesson.tags ?? []).length > 0 ? `**Tags:** ${(lesson.tags ?? []).map((t) => `#${t}`).join(' ')}` : '',
+                    auditSummary,
+                    suggestPin,
+                ].filter(l => l !== '').join('\n');
+            }
+            // Partial match: scan all lesson keys for topic substring
+            const allKeys = [];
+            const scanStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 100 });
+            await new Promise((resolve, reject) => {
+                scanStream.on('data', (batch) => allKeys.push(...batch));
+                scanStream.on('end', resolve);
+                scanStream.on('error', reject);
+            });
+            const matching = allKeys.filter(k => k.toLowerCase().includes(topic.toLowerCase()));
+            if (matching.length === 0) {
+                // Check attempt history as fallback
+                const histKey = `cachly:lessons:${topic}`;
+                const all = await redis.lrange(histKey, -3, -1);
+                if (all.length > 0) {
+                    const parsed = all.map(e => JSON.parse(e));
+                    const lines = parsed.map(p => `- ${p.outcome === 'success' ? '✅' : '❌'} ${p.what_worked.slice(0, 120)} (${new Date(p.ts).toLocaleDateString('de-DE')})`);
+                    return `⚠️ No successful solution for \`${topic}\` yet. Last attempts:\n\n${lines.join('\n')}`;
+                }
+                return `📭 No lessons found for \`${topic}\`. Use \`learn_from_attempts\` after solving it.`;
+            }
+            // Return all partial matches
+            const results = [];
+            for (const k of matching.slice(0, 5)) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                const lesson = JSON.parse(raw);
+                results.push(`**\`${lesson.topic}\`** — ${lesson.what_worked.slice(0, 200)}`);
+            }
+            return `🔍 **Partial matches for \`${topic}\`:**\n\n${results.join('\n\n')}`;
+        }
+        case 'smart_recall': {
+            const { instance_id, query, threshold = 0.78, } = args;
+            const redis = await getConnection(instance_id);
+            // ── Layer 1: Keyword search across ALL brain data (always works, no embedding) ──
+            const kwMatches = await keywordSearch(redis, ['cachly:ctx:*', 'cachly:lesson:best:*', 'cachly:idx:*'], query, 10);
+            const lines = [`🧠 **Smart Recall** for: _"${query}"_\n`];
+            // Show sub-query info if multi-topic was detected
+            const subQueries = splitMultiQuery(query);
+            if (subQueries.length > 1) {
+                lines.push(`_Detected ${subQueries.length} sub-topics:_ ${subQueries.map((s, i) => `${i + 1}. "${s}"`).join(', ')}\n`);
+            }
+            if (kwMatches.length > 0) {
+                lines.push(`### 🔍 BM25 Matches (${kwMatches.length})\n`);
+                // Group by sub-query if multi-topic
+                if (subQueries.length > 1) {
+                    const grouped = new Map();
+                    for (const m of kwMatches.slice(0, 12)) {
+                        const sq = m.subQuery ?? query;
+                        if (!grouped.has(sq))
+                            grouped.set(sq, []);
+                        grouped.get(sq).push(m);
+                    }
+                    for (const [sq, matches] of grouped) {
+                        lines.push(`**Topic: "${sq}"** (${matches.length} results)\n`);
+                        for (const m of matches.slice(0, 4)) {
+                            const label = m.key
+                                .replace('cachly:ctx:', '📝 ')
+                                .replace('cachly:lesson:best:', '💡 ')
+                                .replace('cachly:idx:', '📂 ');
+                            const preview = m.content.slice(0, 300).replace(/\n/g, ' ');
+                            lines.push(`  **${label}** _(BM25: ${m.score.toFixed(2)}, matched: ${m.matchedWords.join(', ')})_`);
+                            lines.push(`  > ${preview}${m.content.length > 300 ? '…' : ''}\n`);
+                        }
+                    }
+                    // Summary: which sub-queries had matches
+                    const matched = [...grouped.keys()];
+                    const unmatched = subQueries.filter(sq => !matched.includes(sq));
+                    if (unmatched.length > 0) {
+                        lines.push(`\n⚠️ **No results for:** ${unmatched.map(s => `"${s}"`).join(', ')}`);
+                    }
+                }
+                else {
+                    for (const m of kwMatches.slice(0, 8)) {
+                        const label = m.key
+                            .replace('cachly:ctx:', '📝 ')
+                            .replace('cachly:lesson:best:', '💡 ')
+                            .replace('cachly:idx:', '📂 ');
+                        const preview = m.content.slice(0, 400).replace(/\n/g, ' ');
+                        lines.push(`**${label}** _(BM25: ${m.score.toFixed(2)}, matched: ${m.matchedWords.join(', ')})_`);
+                        lines.push(`> ${preview}${m.content.length > 400 ? '…' : ''}\n`);
+                    }
+                }
+            }
+            // ── Layer 2: Semantic search (optional, only if embedding provider + vector_token available) ──
+            const inst = await apiFetch(`/api/v1/instances/${instance_id}`);
+            if (inst.vector_token && hasEmbedProvider()) {
+                try {
+                    const embedding = await computeEmbedding(query);
+                    const vectorUrl = `https://api.cachly.dev/v1/sem/${inst.vector_token}`;
+                    const searchRes = await fetch(`${vectorUrl}/search`, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ embedding, namespace: 'cachly:ctx', threshold, top_k: 5 }),
+                    });
+                    if (searchRes.ok) {
+                        const results = (await searchRes.json());
+                        const semHits = results.filter(r => r.found && r.id);
+                        if (semHits.length > 0) {
+                            lines.push(`\n### 🎯 Semantic Matches (${semHits.length})\n`);
+                            for (const hit of semHits) {
+                                const parts = hit.id.replace('ctx:', '').split(':');
+                                const category = parts[0];
+                                const key = parts.slice(1).join(':');
+                                const content = await redis.get(`cachly:ctx:${category}:${key}`);
+                                lines.push(`**${key}** _(${((hit.similarity ?? 0) * 100).toFixed(0)}% similar)_`, `> ${content?.slice(0, 300) ?? '(evicted)'}${(content?.length ?? 0) > 300 ? '…' : ''}\n`);
+                            }
+                        }
+                    }
+                }
+                catch {
+                    // Semantic search failed silently — keyword results are enough
+                }
+            }
+            if (kwMatches.length === 0) {
+                lines.push(`⚠️ No matches found for: "${query}"`);
+                // Did-You-Mean: find nearest token in index vocab
+                const queryTokens = tokenize(query);
+                const suggestions = [];
+                if (_indexVocab.size > 0 && queryTokens.length > 0) {
+                    for (const qt of queryTokens.slice(0, 3)) {
+                        if (qt.length < 4)
+                            continue;
+                        let bestDist = 3;
+                        let bestTok = '';
+                        for (const v of _indexVocab) {
+                            if (v.length < 3 || Math.abs(v.length - qt.length) > 4)
+                                continue;
+                            const d = levenshtein(qt, v);
+                            if (d > 0 && d < bestDist) {
+                                bestDist = d;
+                                bestTok = v;
+                            }
+                        }
+                        if (bestTok)
+                            suggestions.push(`"${bestTok}" (instead of "${qt}")`);
+                    }
+                }
+                if (suggestions.length > 0) {
+                    lines.push(`💡 **Did you mean:** ${suggestions.join(', ')}?`);
+                }
+                else {
+                    lines.push(`\n💡 Tips:`);
+                    lines.push(`  • Try different keywords`);
+                    lines.push(`  • Use \`list_remembered\` to see available context`);
+                    lines.push(`  • Use \`recall_best_solution("topic")\` for exact topic lookup`);
+                }
+            }
+            return lines.join('\n');
+        }
+        // ── get_api_status ────────────────────────────────────────────────────────
+        case 'session_start': {
+            const { instance_id, focus = '', author = '', provider = '', workspace_path = '' } = args;
+            const redis = await getConnection(instance_id);
+            // 1. Scan all best-solution 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);
+            });
+            const lessons = [];
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    lessons.push(JSON.parse(raw));
+                }
+                catch { /* skip corrupt */ }
+            }
+            lessons.sort((a, b) => new Date(b.ts).getTime() - new Date(a.ts).getTime());
+            // 3. Count context entries (filter :meta keys)
+            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);
+            });
+            // 4. Last session
+            const lastSessionRaw = await redis.get('cachly:session:last');
+            let lastSession = null;
+            if (lastSessionRaw) {
+                try {
+                    lastSession = JSON.parse(lastSessionRaw);
+                }
+                catch { /* ignore */ }
+            }
+            // 5. Focus filtering
+            const focusTerms = focus.toLowerCase().split(/\s+/).filter(Boolean);
+            const focusLessons = focusTerms.length > 0
+                ? lessons.filter(l => focusTerms.some(term => l.topic.toLowerCase().includes(term) ||
+                    (l.tags ?? []).some((t) => t.toLowerCase().includes(term))))
+                : [];
+            // 6. Streak tracking
+            let streakDays = 0;
+            let streakRecord = 0;
+            let streakMessage = '';
+            try {
+                const streakRaw = await redis.get('cachly:streak:current');
+                const streak = streakRaw ? JSON.parse(streakRaw) : null;
+                const today = new Date().toISOString().slice(0, 10);
+                if (streak) {
+                    const lastDate = streak.last_date;
+                    const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
+                    if (lastDate === today) {
+                        // Already counted today
+                        streakDays = streak.days;
+                        streakRecord = streak.record;
+                    }
+                    else if (lastDate === yesterday) {
+                        // Continuing streak
+                        streakDays = streak.days + 1;
+                        streakRecord = Math.max(streakDays, streak.record);
+                        await redis.set('cachly:streak:current', JSON.stringify({ days: streakDays, last_date: today, record: streakRecord }));
+                    }
+                    else {
+                        // Streak broken
+                        streakDays = 1;
+                        streakRecord = streak.record;
+                        await redis.set('cachly:streak:current', JSON.stringify({ days: 1, last_date: today, record: streakRecord }));
+                    }
+                }
+                else {
+                    // First session ever
+                    streakDays = 1;
+                    streakRecord = 1;
+                    await redis.set('cachly:streak:current', JSON.stringify({ days: 1, last_date: today, record: 1 }));
+                }
+                if (streakDays >= 7)
+                    streakMessage = `🔥 **${streakDays}-day streak!** ${streakDays === streakRecord ? ' New record!' : `Best: ${streakRecord}d`}`;
+                else if (streakDays > 1)
+                    streakMessage = `🔥 ${streakDays}-day streak`;
+            }
+            catch { /* non-critical */ }
+            // 7. Save session start marker
+            await redis.set('cachly:session:current', JSON.stringify({
+                started: new Date().toISOString(),
+                focus,
+                provider,
+            }), 'EX', 86400); // auto-expire after 24h if session_end never called
+            // ── Build briefing ──────────────────────────────────────────────────────
+            const providerLabel = provider ? ` · ${provider}` : '';
+            const lines = [`🧠 **Session Briefing**${providerLabel}`, ''];
+            if (streakMessage)
+                lines.push(streakMessage, '');
+            // Handoff from previous window (if any)
+            const handoffRaw = await redis.get('cachly:session:handoff');
+            if (handoffRaw) {
+                try {
+                    const handoff = JSON.parse(handoffRaw);
+                    const ago = Math.round((Date.now() - new Date(handoff.ts).getTime()) / 60000);
+                    const agoStr = ago < 60 ? `${ago}m ago` : ago < 1440 ? `${Math.round(ago / 60)}h ago` : `${Math.round(ago / 1440)}d ago`;
+                    lines.push(`🤝 **Handoff from previous window** (${agoStr}):`);
+                    if (handoff.context_summary)
+                        lines.push(`   ${handoff.context_summary}`);
+                    if (handoff.remaining_tasks.length > 0) {
+                        lines.push(`   ⏳ **Remaining tasks:**`);
+                        for (const t of handoff.remaining_tasks)
+                            lines.push(`     - ${t}`);
+                    }
+                    if (handoff.completed_tasks.length > 0) {
+                        lines.push(`   ✅ **Already done:** ${handoff.completed_tasks.join(', ')}`);
+                    }
+                    const brokenFiles = (handoff.files_changed ?? []).filter(f => f.status === 'broken' || f.status === 'partial');
+                    if (brokenFiles.length > 0) {
+                        lines.push(`   ⚠️ **Needs fix:** ${brokenFiles.map(f => `\`${f.path}\` (${f.status}${f.description ? ': ' + f.description : ''})`).join(', ')}`);
+                    }
+                    if (handoff.blocked_on)
+                        lines.push(`   🚫 **Blocked on:** ${handoff.blocked_on}`);
+                    if (handoff.instructions)
+                        lines.push(`   📝 **Instructions:** ${handoff.instructions}`);
+                    lines.push('');
+                }
+                catch { /* ignore corrupt handoff */ }
+            }
+            // ── Last checkpoint (session_ping) — shown when no session_end found ────
+            const checkpointRaw = await redis.get('cachly:session:checkpoint');
+            if (checkpointRaw) {
+                try {
+                    const cp = JSON.parse(checkpointRaw);
+                    // Only show checkpoint if it's more recent than last session_end
+                    const cpTime = new Date(cp.ts).getTime();
+                    const lastSessionTime = lastSession ? new Date(lastSession.ts).getTime() : 0;
+                    if (cpTime > lastSessionTime) {
+                        const ago = Math.round((Date.now() - cpTime) / 60000);
+                        const agoStr = ago < 60 ? `${ago}m ago` : ago < 1440 ? `${Math.round(ago / 60)}h ago` : `${Math.round(ago / 1440)}d ago`;
+                        const providerStr = cp.provider ? ` [${cp.provider}]` : '';
+                        lines.push(`📌 **Last checkpoint**${providerStr} (${agoStr}): ${cp.task}`);
+                        if (cp.files_touched.length > 0) {
+                            lines.push(`   Files: ${cp.files_touched.slice(0, 5).map(f => `\`${f}\``).join(', ')}`);
+                        }
+                        if (cp.next_step)
+                            lines.push(`   📍 Next step was: ${cp.next_step}`);
+                        if (!lastSession || cpTime - lastSessionTime > 300_000) {
+                            lines.push(`   ⚠️ No \`session_end\` found — reconstructed from last checkpoint`);
+                        }
+                        lines.push('');
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            // ── Git reconstruction — when no session_end + workspace_path given ─────
+            if (workspace_path && !lastSession) {
+                try {
+                    const { execSync } = await import('node:child_process');
+                    const gitLog = execSync(`git -C "${workspace_path}" log --oneline --format="%h %s" -15 2>/dev/null`, { encoding: 'utf-8', timeout: 5000 }).trim();
+                    const gitDiff = execSync(`git -C "${workspace_path}" diff --stat HEAD~3 2>/dev/null || git -C "${workspace_path}" diff --stat 2>/dev/null`, { encoding: 'utf-8', timeout: 5000 }).trim();
+                    if (gitLog) {
+                        lines.push(`🔍 **Git reconstruction** (no session_end found — reconstructed from git):`);
+                        for (const l of gitLog.split('\n').slice(0, 8))
+                            lines.push(`   ${l}`);
+                        if (gitDiff) {
+                            const diffLines = gitDiff.split('\n').filter(l => l.includes('|') || l.includes('changed'));
+                            if (diffLines.length > 0) {
+                                lines.push(`   **Recent changes:**`);
+                                for (const dl of diffLines.slice(0, 5))
+                                    lines.push(`   ${dl.trim()}`);
+                            }
+                        }
+                        lines.push('');
+                    }
+                }
+                catch { /* git not available or no repo — silent */ }
+            }
+            // Last session
+            if (lastSession) {
+                const ago = Math.round((Date.now() - new Date(lastSession.ts).getTime()) / 60000);
+                const agoStr = ago < 60 ? `${ago}m ago` : ago < 1440 ? `${Math.round(ago / 60)}h ago` : `${Math.round(ago / 1440)}d ago`;
+                lines.push(`📅 **Last session** (${agoStr}): ${lastSession.summary}`);
+                if (lastSession.duration_min)
+                    lines.push(`   Duration: ${lastSession.duration_min} min`);
+                if ((lastSession.files_changed ?? []).length > 0) {
+                    lines.push(`   Files: ${(lastSession.files_changed ?? []).slice(0, 5).map((f) => `\`${f}\``).join(', ')}`);
+                }
+                lines.push('');
+            }
+            // Brain health
+            lines.push(`📊 **Brain:** ${lessons.length} lessons · ${ctxCount} context entries`, '');
+            // ── Layer 7: MCM Domain Coverage Map ────────────────────────────────────
+            if (lessons.length >= 3) {
+                const domainMap = new Map();
+                for (const l of lessons) {
+                    const dom = l.topic.split(':')[0] ?? 'other';
+                    if (!domainMap.has(dom))
+                        domainMap.set(dom, { total: 0, success: 0, critical: 0 });
+                    const d = domainMap.get(dom);
+                    d.total++;
+                    if (l.outcome === 'success')
+                        d.success++;
+                    if (l.severity === 'critical')
+                        d.critical++;
+                }
+                const sorted = [...domainMap.entries()].sort((a, b) => b[1].total - a[1].total).slice(0, 6);
+                const hasContestedDomains = sorted.some(([, d]) => d.success < d.total * 0.4 && d.total >= 2);
+                if (sorted.length > 0) {
+                    lines.push(`🗺️ **Knowledge Coverage:**`);
+                    for (const [dom, d] of sorted) {
+                        const pct = Math.round((d.success / d.total) * 100);
+                        const filled = Math.round(pct / 10);
+                        const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+                        const flag = d.critical > 0 ? ' 🔴' : pct < 40 && d.total >= 2 ? ' ⚠️' : '';
+                        lines.push(`  ${bar} ${dom.padEnd(18)} ${String(pct).padStart(3)}% (${d.success}/${d.total} confirmed)${flag}`);
+                    }
+                    if (hasContestedDomains) {
+                        lines.push(`  ⚠️ _Some domains have contested beliefs — use \`ckg_inspect\` to review_`);
+                    }
+                    lines.push('');
+                }
+            }
+            // ── Layer 7 MCM: Active belief conflicts ─────────────────────────────────
+            try {
+                const conflictKeys = [];
+                const cfStream = redis.scanStream({ match: 'cachly:ckg:conflict:*', count: 50 });
+                await new Promise((res, rej) => { cfStream.on('data', (b) => conflictKeys.push(...b)); cfStream.on('end', res); cfStream.on('error', rej); });
+                if (conflictKeys.length > 0) {
+                    lines.push(`⚡ **Active belief conflicts (${conflictKeys.length}):**`);
+                    for (const ck of conflictKeys.slice(0, 3)) {
+                        const cr = await redis.get(ck);
+                        if (!cr)
+                            continue;
+                        const cf = JSON.parse(cr);
+                        lines.push(`  ⚠️ \`${cf.topic}\` — previously confirmed fix (${(cf.fix_confidence * 100).toFixed(0)}%, n=${cf.fix_trials}) now contradicted. Use \`ckg_inspect(concept="${ckgSlug(cf.topic)}")\``);
+                    }
+                    lines.push('');
+                }
+            }
+            catch { /* non-critical */ }
+            // ── Layer 7 MCM: Blind Spot Detection ────────────────────────────────────
+            // If the focus mentions a domain that has no CKG node → surface blind spot
+            if (focus && focus.length > 3) {
+                try {
+                    const focusTokens = focus.toLowerCase().replace(/[^a-z0-9\s:_-]/g, ' ').split(/\s+/).filter(t => t.length > 3);
+                    const blindSpots = [];
+                    for (const token of focusTokens.slice(0, 6)) {
+                        const nodeExists = await redis.exists(`cachly:ckg:node:${token}`);
+                        if (!nodeExists) {
+                            // Check if any node starts with this token (prefix match)
+                            const prefixKeys = [];
+                            const psStream = redis.scanStream({ match: `cachly:ckg:node:${token}*`, count: 10 });
+                            await new Promise((res, rej) => { psStream.on('data', (b) => prefixKeys.push(...b)); psStream.on('end', res); psStream.on('error', rej); });
+                            if (prefixKeys.length === 0)
+                                blindSpots.push(token);
+                        }
+                    }
+                    if (blindSpots.length > 0) {
+                        lines.push(`🔭 **Blind spots detected for this focus:**`);
+                        for (const bs of blindSpots.slice(0, 3)) {
+                            lines.push(`  ⬜ \`${bs}\` — no CKG knowledge. Suggestions:`);
+                            lines.push(`     • \`brain_from_git(instance_id="...", concept="${bs}")\` — bootstrap from commits`);
+                            lines.push(`     • \`fedbrain_search(query="${bs}")\` — search global commons`);
+                        }
+                        lines.push('');
+                    }
+                }
+                catch { /* non-critical */ }
+            }
+            if (focusLessons.length > 0) {
+                lines.push(`🎯 **Relevant for "${focus}":**`);
+                for (const l of focusLessons.slice(0, 4)) {
+                    const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+                    const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
+                    lines.push(`  ${emoji}${sev} \`${l.topic}\` — ${l.what_worked.slice(0, 100)}`);
+                }
+                lines.push('');
+            }
+            // Recent lessons
+            if (lessons.length > 0) {
+                lines.push(`🕐 **Recent lessons:**`);
+                const toShow = focusLessons.length > 0 ? lessons.filter(l => !focusLessons.includes(l)).slice(0, 4) : lessons.slice(0, 5);
+                for (const l of toShow) {
+                    const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+                    const sev = l.severity === 'critical' ? '🔴' : l.severity === 'major' ? '🟡' : '';
+                    lines.push(`  ${emoji}${sev} \`${l.topic}\` — ${l.what_worked.slice(0, 90)}`);
+                }
+                lines.push('');
+            }
+            else {
+                lines.push('📭 No lessons yet. Use `learn_from_attempts` after solving tasks.', '');
+            }
+            // Open failures (lessons whose best-key has outcome != success)
+            const openFailures = lessons.filter(l => l.outcome === 'failure' || l.outcome === 'partial');
+            if (openFailures.length > 0) {
+                lines.push(`⚠️ **Unresolved** (${openFailures.length} topic${openFailures.length > 1 ? 's' : ''} with no success yet):`);
+                for (const l of openFailures.slice(0, 3)) {
+                    lines.push(`  ❌ \`${l.topic}\` — ${(l.what_failed ?? l.what_worked).slice(0, 80)}`);
+                }
+                lines.push('');
+            }
+            // ── Stale / low-confidence lessons (confidence decay) ─────────────────
+            const staleSuccessLessons = lessons.filter(l => {
+                if (l.outcome !== 'success' && l.outcome !== 'partial')
+                    return false;
+                return calculateConfidence(l) < CONFIDENCE_WARN_VALUE;
+            });
+            if (staleSuccessLessons.length > 0) {
+                lines.push(`🔴 **Stale lessons** (not recalled in >${CONFIDENCE_WARN_DAYS}d — verify before applying):`);
+                for (const l of staleSuccessLessons.slice(0, 4)) {
+                    const conf = calculateConfidence(l);
+                    const ageDays = Math.round((Date.now() - new Date(l.verified_at ?? l.ts).getTime()) / 86400000);
+                    const flag = conf < CONFIDENCE_STALE_VALUE ? '🔴' : '⚠️';
+                    lines.push(`  ${flag} \`${l.topic}\` — ${ageDays}d stale, ${(conf * 100).toFixed(0)}% confidence`);
+                }
+                lines.push(`  _Run \`recall_best_solution\` on these to reset their confidence clock._`);
+                lines.push('');
+            }
+            // ── Session Replay: show last session's decision log ──────────────────
+            const lastSessionAny = lastSession;
+            if (lastSessionAny?.decision_log?.length) {
+                const dl = lastSessionAny.decision_log;
+                const successes = dl.filter(d => d.outcome === 'success');
+                const failures = dl.filter(d => d.outcome === 'failure');
+                lines.push(`🎬 **Last session decisions** (${dl.length} lessons stored):`);
+                if (successes.length > 0)
+                    lines.push(`  ✅ Worked: ${successes.slice(0, 3).map(d => `\`${d.topic}\``).join(', ')}`);
+                if (failures.length > 0)
+                    lines.push(`  ❌ Failed: ${failures.slice(0, 3).map(d => `\`${d.topic}\``).join(', ')}`);
+                lines.push('');
+            }
+            // ── 🔮 Predictive Pre-Warning — intent-based danger detection ────────────
+            // Fires BEFORE work starts. If focus area has known failure patterns → warn loudly.
+            if (focusTerms.length > 0) {
+                const dangerLessons = lessons.filter(l => {
+                    if (l.outcome === 'success')
+                        return false;
+                    const topicCategory = l.topic.split(':')[0];
+                    return focusTerms.some(term => l.topic.toLowerCase().includes(term) ||
+                        topicCategory === term ||
+                        (l.tags ?? []).some((t) => t.toLowerCase() === term));
+                });
+                if (dangerLessons.length >= 1) {
+                    // Insert warning block right after the title line (index 1 = blank line after title)
+                    const warning = [
+                        `🚨 **PRE-WARNING** — Read this BEFORE starting:`,
+                        `  Known pitfalls for **"${focus}"** (${dangerLessons.length} past failure${dangerLessons.length > 1 ? 's' : ''}):`,
+                        ...dangerLessons.slice(0, 3).map(l => `  ❌ \`${l.topic}\` — ${(l.what_failed ?? l.what_worked).slice(0, 80)}`),
+                        '',
+                    ];
+                    lines.splice(2, 0, ...warning); // after '🧠 **Session Briefing**' + empty line
+                }
+            }
+            // ── 👥 Team Telepathy — what teammates learned this week ─────────────────
+            if (author) {
+                const oneWeekAgo = Date.now() - 7 * 86_400_000;
+                const teamLessons = lessons.filter(l => l.author && l.author !== author && new Date(l.ts).getTime() > oneWeekAgo);
+                if (teamLessons.length > 0) {
+                    // Group by author
+                    const byAuthor = new Map();
+                    for (const l of teamLessons) {
+                        const a = l.author;
+                        if (!byAuthor.has(a))
+                            byAuthor.set(a, []);
+                        byAuthor.get(a).push(l);
+                    }
+                    lines.push(`👥 **Team this week** (${teamLessons.length} lesson${teamLessons.length > 1 ? 's' : ''} from teammates):`);
+                    for (const [teamAuthor, tls] of byAuthor) {
+                        lines.push(`  👤 **${teamAuthor}**:`);
+                        for (const l of tls.slice(0, 3)) {
+                            const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
+                            lines.push(`    ${emoji} \`${l.topic}\` — ${l.what_worked.slice(0, 80)}`);
+                        }
+                        if (tls.length > 3)
+                            lines.push(`    … and ${tls.length - 3} more`);
+                    }
+                    lines.push('');
+                }
+            }
+            // ── 💎 Memory Crystal — compressed wisdom from old sessions ──────────────
+            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);
+                    if (crystalAge <= 90) {
+                        lines.push(`💎 **Memory Crystal** (${crystal.label} · ${crystal.session_count} sessions compressed):`);
+                        for (const p of crystal.top_patterns.slice(0, 3)) {
+                            lines.push(`  • **${p.category}** (${p.count}×): ${p.insight.slice(0, 90)}`);
+                        }
+                        lines.push('');
+                    }
+                }
+            }
+            catch { /* non-critical */ }
+            // ── 🗺️ Roadmap — open items at session start ────────────────────────────
+            try {
+                const roadmapAll = await redis.hgetall(`cachly:roadmap:${instance_id}`);
+                if (roadmapAll && Object.keys(roadmapAll).length > 0) {
+                    const PRIORITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
+                    const PRIORITY_ICON = { critical: '🔴', high: '🟠', medium: '🟡', low: '🔵' };
+                    const openStatuses = new Set(['planned', 'in-progress', 'blocked']);
+                    const allItems = Object.values(roadmapAll).map(v => JSON.parse(v));
+                    const openItems = allItems
+                        .filter(i => openStatuses.has(i.status))
+                        .sort((a, b) => {
+                        if (a.status === 'in-progress' && b.status !== 'in-progress')
+                            return -1;
+                        if (b.status === 'in-progress' && a.status !== 'in-progress')
+                            return 1;
+                        return (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99);
+                    });
+                    const doneCount = allItems.filter(i => i.status === 'done').length;
+                    if (openItems.length > 0) {
+                        lines.push(`🗺️ **Roadmap** (${openItems.length} open · ${doneCount} done):`);
+                        for (const it of openItems.slice(0, 5)) {
+                            const statusIcon = it.status === 'in-progress' ? '⚡' : it.status === 'blocked' ? '🚫' : '📋';
+                            lines.push(`  ${statusIcon} ${PRIORITY_ICON[it.priority] ?? '⚪'} \`${it.id}\` **${it.title}**`);
+                        }
+                        if (openItems.length > 5)
+                            lines.push(`  … and ${openItems.length - 5} more`);
+                        lines.push(`  _Use \`roadmap_next\` for the top priority item · \`roadmap_list\` for full view_`);
+                        lines.push('');
+                    }
+                }
+            }
+            catch { /* non-critical */ }
+            // ── 🔮 PPE: Predictive Pre-fetch — CKG-powered risk detection ────────────
+            // Layer 4: Before starting any work, scan the CKG for nodes matching focus
+            // tokens and traverse causal edges to surface predicted failure points inline.
+            // This is the PPE "pre-fetch" that was previously only available via brain_predict.
+            if (focus && focus.length > 3) {
+                try {
+                    const ppeFocusTokens = focus.toLowerCase().replace(/[^a-z0-9\s\-_:]/g, ' ').split(/\s+/).filter(t => t.length > 2).slice(0, 5);
+                    const ppePredictions = [];
+                    for (const token of ppeFocusTokens) {
+                        const nodeKeys = [];
+                        const nStream = redis.scanStream({ match: `cachly:ckg:node:*${token}*`, count: 20 });
+                        await new Promise((res, rej) => { nStream.on('data', (b) => nodeKeys.push(...b)); nStream.on('end', res); nStream.on('error', rej); });
+                        for (const nk of nodeKeys.slice(0, 3)) {
+                            const nodeRaw = await redis.get(nk);
+                            if (!nodeRaw)
+                                continue;
+                            const node = JSON.parse(nodeRaw);
+                            const edgeKeys = await redis.smembers(`cachly:ckg:idx:from:${node.id}`);
+                            for (const ek of edgeKeys.slice(0, 15)) {
+                                const edgeRaw = await redis.get(ek);
+                                if (!edgeRaw)
+                                    continue;
+                                const edge = JSON.parse(edgeRaw);
+                                if (edge.edgeType !== 'causes' && edge.edgeType !== 'co-occurs' && edge.edgeType !== 'fixes')
+                                    continue;
+                                if (edge.confidence < 0.35)
+                                    continue;
+                                // For "fixes" edges, the lesson is on the "from" node (fix for "to")
+                                // For "causes" edges, target is the failure mode
+                                const lessonKey = edge.edgeType === 'fixes' ? `cachly:lesson:best:${edge.from}` : `cachly:lesson:best:${edge.to}`;
+                                const lessonRaw = await redis.get(lessonKey);
+                                const lesson = lessonRaw ? JSON.parse(lessonRaw) : undefined;
+                                ppePredictions.push({ concept: node.id, edgeType: edge.edgeType, target: edge.to, confidence: edge.confidence, lesson });
+                            }
+                        }
+                    }
+                    const ppeSeen = new Set();
+                    const ppeUniq = ppePredictions
+                        .filter(p => { const k = `${p.concept}:${p.target}`; if (ppeSeen.has(k))
+                        return false; ppeSeen.add(k); return true; })
+                        .sort((a, b) => b.confidence - a.confidence)
+                        .slice(0, 4);
+                    if (ppeUniq.length > 0) {
+                        lines.push(`🔮 **Predicted risks for "${focus}"** (PPE pre-fetch):`);
+                        for (const p of ppeUniq) {
+                            const confPct = Math.round(p.confidence * 100);
+                            const icon = p.edgeType === 'causes' ? '⚡' : p.edgeType === 'fixes' ? '🔧' : '🔄';
+                            lines.push(`  ${icon} **${confPct}%** \`${p.concept}\` ${p.edgeType} \`${p.target}\``);
+                            if (p.lesson?.what_worked)
+                                lines.push(`     ✅ ${p.lesson.what_worked.slice(0, 110)}`);
+                        }
+                        lines.push(`  _Full analysis: \`brain_predict(context="${focus}")\`_`);
+                        lines.push('');
+                    }
+                }
+                catch { /* non-critical — never block session start */ }
+            }
+            // ── 📐 MCM Confidence Calibration — 30-day accuracy pass ─────────────────
+            // Layer 7: Periodically check if high-confidence lessons are actually reliable.
+            // If last calibration was >30 days ago (or never), run a quick pass.
+            // Measures: of recalled lessons with confidence > 0.85, what % had outcome=success?
+            try {
+                const calRaw = await redis.get('cachly:mcm:calibration:last');
+                const lastCalMs = calRaw ? JSON.parse(calRaw).ts : 0;
+                const daysSinceCal = (Date.now() - lastCalMs) / 86_400_000;
+                if (daysSinceCal >= 30 && lessons.length >= 5) {
+                    // Quick calibration pass on recalled lessons (recall_count > 0, outcome=success)
+                    const recalledSuccess = lessons.filter(l => l.outcome === 'success' && (l.recall_count ?? 0) > 0);
+                    const recalledAll = lessons.filter(l => (l.recall_count ?? 0) > 0);
+                    if (recalledAll.length >= 3) {
+                        const precision = recalledAll.length > 0 ? recalledSuccess.length / recalledAll.length : 1;
+                        const lowPrecisionDomains = [];
+                        // Per-domain breakdown
+                        const domCalMap = new Map();
+                        for (const l of recalledAll) {
+                            const dom = l.topic.split(':')[0] ?? 'other';
+                            if (!domCalMap.has(dom))
+                                domCalMap.set(dom, { success: 0, total: 0 });
+                            const d = domCalMap.get(dom);
+                            d.total++;
+                            if (l.outcome === 'success')
+                                d.success++;
+                        }
+                        for (const [dom, d] of domCalMap) {
+                            if (d.total >= 2 && d.success / d.total < 0.6)
+                                lowPrecisionDomains.push(dom);
+                        }
+                        // Save calibration result
+                        await redis.set('cachly:mcm:calibration:last', JSON.stringify({
+                            ts: Date.now(),
+                            precision: precision,
+                            recalled: recalledAll.length,
+                            low_precision_domains: lowPrecisionDomains,
+                        }));
+                        if (lowPrecisionDomains.length > 0 || precision < 0.7) {
+                            lines.push(`📐 **MCM Calibration** (30-day pass — ${recalledAll.length} recalled lessons):`);
+                            lines.push(`  Overall precision: **${(precision * 100).toFixed(0)}%** recalled lessons actually worked`);
+                            if (lowPrecisionDomains.length > 0) {
+                                lines.push(`  ⚠️ Low-precision domains: ${lowPrecisionDomains.map(d => `\`${d}\``).join(', ')} — consider revisiting these lessons`);
+                            }
+                            lines.push(`  💡 Use \`learn_from_attempts\` to update stale lessons and improve accuracy.`);
+                            lines.push('');
+                        }
+                    }
+                    // Even if no issues, stamp the date so we don't re-check for 30d
+                    await redis.set('cachly:mcm:calibration:last', JSON.stringify({ ts: Date.now(), precision: 1, recalled: 0 }), 'EX', 35 * 86400);
+                }
+            }
+            catch { /* non-critical */ }
+            // ── 🌍 Knowledge Commons — community stats banner ───────────────────────
+            // Fetch syndication stats and show a 1-liner: total lessons + confirms + weekly growth.
+            // Non-fatal: never blocks session start if the API call fails.
+            try {
+                const commonsStats = await apiFetch('/api/v1/syndication/stats');
+                if (commonsStats.total_lessons > 0) {
+                    lines.push(`🌍 **Commons:** ${commonsStats.total_lessons.toLocaleString()} lessons · ` +
+                        `${commonsStats.total_confirms.toLocaleString()} confirms · ` +
+                        `+${commonsStats.added_last_7_days} this week`);
+                    lines.push('');
+                }
+            }
+            catch { /* non-critical — never block session start */ }
+            return lines.join('\n');
+        }
+        // ── session_end ───────────────────────────────────────────────────────────
+        case 'session_end': {
+            const { instance_id, summary, files_changed = [], lessons_learned, workspace_path = '', } = args;
+            const redis = await getConnection(instance_id);
+            const now = new Date();
+            // Calculate duration from session_start marker
+            let durationMin;
+            const currentRaw = await redis.get('cachly:session:current');
+            if (currentRaw) {
+                try {
+                    const current = JSON.parse(currentRaw);
+                    durationMin = Math.round((now.getTime() - new Date(current.started).getTime()) / 60000);
+                }
+                catch { /* ignore */ }
+            }
+            // ── Session Replay: capture decision log ─────────────────────────────
+            let decisionLog = [];
+            try {
+                const dlEntries = await redis.lrange('cachly:session:decision-log', 0, -1);
+                decisionLog = dlEntries.map(e => JSON.parse(e));
+                await redis.del('cachly:session:decision-log');
+            }
+            catch { /* non-critical */ }
+            const sessionRecord = {
+                ts: now.toISOString(),
+                summary,
+                files_changed,
+                ...(lessons_learned !== undefined ? { lessons_learned } : {}),
+                ...(durationMin !== undefined ? { duration_min: durationMin } : {}),
+                ...(decisionLog.length > 0 ? { decision_log: decisionLog } : {}),
+            };
+            // Save as "last session"
+            await redis.set('cachly:session:last', JSON.stringify(sessionRecord));
+            // Append to history list (keep last 50 sessions, TTL 90 days)
+            await redis.lpush('cachly:session:history', JSON.stringify(sessionRecord));
+            await redis.ltrim('cachly:session:history', 0, 49);
+            await redis.expire('cachly:session:history', 90 * 86400);
+            // Clean up current session marker
+            await redis.del('cachly:session:current');
+            // ── AUTO-LEARN from session summary (no manual call needed) ─────────────
+            // Parse the summary for actionable lessons and store them automatically.
+            const autoLearned = [];
+            try {
+                // Extract key sentences from the summary that contain action verbs
+                const actionVerbs = /\b(fixed|deployed|added|removed|refactored|migrated|updated|resolved|implemented|improved|optimized|configured|created|deleted|disabled|enabled|discovered|found|learned|debugged|patched|upgraded|installed|tested|built|rewrote|moved|renamed|split|merged|extracted)\b/i;
+                const sentences = summary
+                    .split(/[.!\n]+/)
+                    .map(s => s.trim())
+                    .filter(s => s.length > 20 && actionVerbs.test(s));
+                for (const sentence of sentences.slice(0, 6)) {
+                    // Build a topic slug from the first meaningful words
+                    const words = sentence.toLowerCase()
+                        .replace(/[^a-z0-9\s]/g, ' ')
+                        .split(/\s+/)
+                        .filter(w => w.length > 3 && !['that', 'this', 'with', 'from', 'have', 'been', 'were', 'they', 'then', 'when', 'also', 'into', 'will', 'would', 'could', 'should'].includes(w));
+                    const slug = words.slice(0, 4).join('-');
+                    if (!slug)
+                        continue;
+                    const topic = `auto:${slug}`;
+                    const key = `cachly:lesson:best:${topic}`;
+                    // Don't overwrite existing successful lessons
+                    const existing = await redis.get(key);
+                    if (existing) {
+                        try {
+                            const ex = JSON.parse(existing);
+                            if (ex.outcome === 'success')
+                                continue;
+                        }
+                        catch { /* ignore */ }
+                    }
+                    const lesson = {
+                        topic,
+                        outcome: 'success',
+                        what_worked: sentence,
+                        context: `Auto-learned from session summary. Full summary: ${summary.slice(0, 300)}`,
+                        severity: 'minor',
+                        ts: now.toISOString(),
+                        recall_count: 0,
+                        auto_learned: true,
+                        session_ts: now.toISOString(),
+                        version: 2,
+                    };
+                    await redis.set(key, JSON.stringify(lesson));
+                    // 90-day TTL for auto-learned lessons
+                    await redis.expire(key, 90 * 86400);
+                    autoLearned.push(topic);
+                }
+                // Also store a lesson per changed file area if files were changed
+                if (files_changed.length > 0) {
+                    const areas = [...new Set(files_changed.map(f => f.split('/').slice(0, 2).join('/')))].slice(0, 3);
+                    for (const area of areas) {
+                        const slug = area.replace(/[^a-z0-9]/gi, '-').toLowerCase().replace(/-+/g, '-').slice(0, 30);
+                        const topic = `auto:changed:${slug}`;
+                        const key = `cachly:lesson:best:${topic}`;
+                        const lesson = {
+                            topic,
+                            outcome: 'success',
+                            what_worked: `Files changed in ${area}: ${files_changed.filter(f => f.startsWith(area.split('/')[0])).slice(0, 5).join(', ')}`,
+                            context: summary.slice(0, 200),
+                            severity: 'minor',
+                            ts: now.toISOString(),
+                            recall_count: 0,
+                            auto_learned: true,
+                            version: 2,
+                        };
+                        await redis.set(key, JSON.stringify(lesson));
+                        await redis.expire(key, 90 * 86400);
+                        autoLearned.push(topic);
+                    }
+                }
+            }
+            catch { /* auto-learn errors must never break session_end */ }
+            // ── 🌿 Ambient Git Learning ────────────────────────────────────────────────
+            // Read git commits since session start → auto-learn each meaningful commit.
+            const ambientLearned = [];
+            if (workspace_path) {
+                try {
+                    // Get the session start time (stored by session_start)
+                    const sessionStartTs = currentRaw
+                        ? (() => { try {
+                            return JSON.parse(currentRaw).started ?? '';
+                        }
+                        catch {
+                            return '';
+                        } })()
+                        : '';
+                    const sinceArg = sessionStartTs ? `--since="${sessionStartTs}"` : '--since="1 hour ago"';
+                    const gitOut = execSync(`git -C "${workspace_path}" log ${sinceArg} --oneline --format="%H|||%s|||%ai"`, { timeout: 5000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+                    if (gitOut) {
+                        const commitActionRe = /\b(fix|add|remove|refactor|migrate|update|resolve|implement|improve|optimize|configure|create|delete|disable|enable|debug|patch|upgrade|build|rewrite|deploy|feat|chore|docs|test|perf|ci)\b/i;
+                        for (const line of gitOut.split('\n').slice(0, 10)) {
+                            const [hash, msg, dateStr] = line.split('|||');
+                            if (!msg || !commitActionRe.test(msg))
+                                continue;
+                            const slug = msg
+                                .toLowerCase().replace(/^(fix|feat|chore|docs|test|ci|perf|refactor|build|revert)[:(\s]/i, '')
+                                .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+                            if (!slug)
+                                continue;
+                            const topic = `git:${slug}`;
+                            const key = `cachly:lesson:best:${topic}`;
+                            const existing = await redis.get(key);
+                            if (existing)
+                                continue; // don't overwrite existing
+                            const commitLesson = {
+                                topic,
+                                outcome: 'success',
+                                what_worked: msg.slice(0, 200),
+                                context: `Auto-learned from git commit ${(hash ?? '').slice(0, 7)} at ${dateStr ?? ''} in ${workspace_path}`,
+                                severity: 'minor',
+                                ts: now.toISOString(),
+                                recall_count: 0,
+                                auto_learned: true,
+                                source: 'ambient-git',
+                                version: 3,
+                            };
+                            await redis.set(key, JSON.stringify(commitLesson));
+                            await redis.expire(key, 60 * 86400); // 60 day TTL for git lessons
+                            ambientLearned.push(topic);
+                        }
+                    }
+                }
+                catch { /* git not available or not a repo — silent skip */ }
+            }
+            const durationStr = durationMin !== undefined ? ` · ${durationMin} min` : '';
+            return [
+                `✅ **Session saved**${durationStr}`,
+                ``,
+                `📋 **Summary:** ${summary}`,
+                files_changed.length > 0 ? `📁 **Files changed:** ${files_changed.map(f => `\`${f}\``).join(', ')}` : '',
+                lessons_learned !== undefined ? `🧠 **Lessons stored:** ${lessons_learned}` : '',
+                autoLearned.length > 0 ? `🤖 **Auto-learned:** ${autoLearned.length} lessons extracted from summary (${autoLearned.slice(0, 3).map(t => `\`${t}\``).join(', ')}${autoLearned.length > 3 ? '…' : ''})` : '',
+                ambientLearned.length > 0 ? `🌿 **Ambient git learning:** ${ambientLearned.length} commit${ambientLearned.length > 1 ? 's' : ''} auto-learned (${ambientLearned.slice(0, 3).map(t => `\`${t}\``).join(', ')}${ambientLearned.length > 3 ? '…' : ''})` : '',
+                ``,
+                `💡 Next session: \`session_start(focus="...")\` to see this summary.`,
+            ].filter(l => l !== '').join('\n');
+        }
+        // ── session_ping — lightweight checkpoint ─────────────────────────────────
+        case 'session_ping': {
+            const { instance_id, task, files_touched = [], next_step = '', provider = '', } = args;
+            const redis = await getConnection(instance_id);
+            const checkpoint = {
+                ts: new Date().toISOString(),
+                task,
+                files_touched,
+                next_step,
+                provider,
+            };
+            // Store as the latest checkpoint — session_start reads this when no session_end found
+            await redis.set('cachly:session:checkpoint', JSON.stringify(checkpoint), 'EX', 86400 * 3); // 3-day TTL
+            // Also keep a short rolling log (last 20 checkpoints for history)
+            await redis.lpush('cachly:session:checkpoint:log', JSON.stringify(checkpoint));
+            await redis.ltrim('cachly:session:checkpoint:log', 0, 19);
+            const providerStr = provider ? ` [${provider}]` : '';
+            const filesStr = files_touched.length > 0 ? ` · ${files_touched.length} file${files_touched.length > 1 ? 's' : ''} touched` : '';
+            const nextStr = next_step ? `\n📍 **Next step:** ${next_step}` : '';
+            return [
+                `📌 **Checkpoint saved**${providerStr} — ${new Date().toLocaleTimeString()}`,
+                `🔨 **Working on:** ${task}${filesStr}`,
+                nextStr,
+                ``,
+                `💡 If you switch providers, \`session_start\` will show this checkpoint automatically.`,
+            ].filter(l => l !== '').join('\n');
+        }
+        // ── session_handoff — cross-window continuity ─────────────────────────────
+        case 'session_handoff': {
+            const { instance_id, completed_tasks = [], remaining_tasks = [], files_changed = [], instructions = '', context_summary = '', blocked_on = '', } = args;
+            const redis = await getConnection(instance_id);
+            const now = new Date();
+            const handoff = {
+                ts: now.toISOString(),
+                completed_tasks,
+                remaining_tasks,
+                files_changed,
+                instructions,
+                context_summary,
+                blocked_on,
+            };
+            // Store handoff — never expires until next handoff overwrites it
+            await redis.set('cachly:session:handoff', JSON.stringify(handoff));
+            // Also append to history
+            await redis.lpush('cachly:session:handoff:history', JSON.stringify(handoff));
+            await redis.ltrim('cachly:session:handoff:history', 0, 19);
+            const totalTasks = completed_tasks.length + remaining_tasks.length;
+            const pct = totalTasks > 0 ? Math.round((completed_tasks.length / totalTasks) * 100) : 0;
+            const brokenFiles = files_changed.filter(f => f.status === 'broken' || f.status === 'partial');
+            return [
+                `🤝 **Handoff saved** — ${completed_tasks.length}/${totalTasks} tasks done (${pct}%)`,
+                ``,
+                completed_tasks.length > 0 ? `✅ **Completed:**\n${completed_tasks.map(t => `  - ${t}`).join('\n')}` : '',
+                remaining_tasks.length > 0 ? `\n⏳ **Remaining for next window:**\n${remaining_tasks.map(t => `  - ${t}`).join('\n')}` : '',
+                brokenFiles.length > 0 ? `\n⚠️ **Needs attention:** ${brokenFiles.map(f => `\`${f.path}\` (${f.status})`).join(', ')}` : '',
+                blocked_on ? `\n🚫 **Blocked on:** ${blocked_on}` : '',
+                instructions ? `\n📝 **Instructions:** ${instructions}` : '',
+                ``,
+                `💡 The next \`session_start\` will include this handoff automatically.`,
+            ].filter(l => l !== '').join('\n');
+        }
+        // ── auto_learn_session ────────────────────────────────────────────────────
+        case 'auto_learn_session': {
+            const { instance_id, observations } = args;
+            const redis = await getConnection(instance_id);
+            const stored = [];
+            const skipped = [];
+            for (const obs of observations) {
+                // Auto-generate topic from action if not provided
+                const rawTopic = obs.topic ?? obs.action
+                    .toLowerCase()
+                    .replace(/[^a-z0-9:\-_\s]/g, '')
+                    .trim()
+                    .split(/\s+/)
+                    .slice(0, 4)
+                    .join('-');
+                const topic = rawTopic.includes(':') ? rawTopic : `auto:${rawTopic}`;
+                const key = `cachly:lesson:best:${topic}`;
+                // Only overwrite if this is a success and existing is failure, or topic is new
+                const existing = await redis.get(key);
+                if (existing) {
+                    const existingLesson = JSON.parse(existing);
+                    if (existingLesson.outcome === 'success' && obs.outcome !== 'success') {
+                        skipped.push(topic);
+                        continue;
+                    }
+                }
+                const lesson = {
+                    topic,
+                    outcome: obs.outcome,
+                    what_worked: obs.outcome === 'success' ? obs.action : (obs.details ?? obs.action),
+                    what_failed: obs.outcome === 'failure' ? obs.action : undefined,
+                    context: obs.details,
+                    severity: obs.severity ?? 'minor',
+                    ts: new Date().toISOString(),
+                    recall_count: 0,
+                    auto_learned: true,
+                    version: 2,
+                };
+                await redis.set(key, JSON.stringify(lesson));
+                stored.push(`${obs.outcome === 'success' ? '✅' : obs.outcome === 'partial' ? '⚠️' : '❌'} \`${topic}\``);
+            }
+            const lines = [
+                `🤖 **Auto-learn complete**: ${stored.length} stored, ${skipped.length} skipped`,
+                '',
+            ];
+            if (stored.length > 0)
+                lines.push('**Stored:**', ...stored.map(s => '  ' + s), '');
+            if (skipped.length > 0)
+                lines.push(`**Skipped** (better lesson already exists): ${skipped.map(t => `\`${t}\``).join(', ')}`);
+            return lines.join('\n');
+        }
+        // ── sync_file_changes ─────────────────────────────────────────────────────
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=brain.js.map