@cachly-dev/mcp-server 0.8.3 → 0.9.1

package/dist/index.js

@@ -2976,6 +2976,21 @@ const TOOLS = [
             required: ['instance_id'],
         },
     },
+    // ── crystal_view — inspect current Memory Crystal ──────────────────────
+    {
+        name: 'crystal_view',
+        description: 'View the current Memory Crystal — the distilled snapshot of everything your AI brain has learned. ' +
+            'Shows all top patterns grouped by category, lesson count, crystal age, and when to refresh. ' +
+            'A crystal is created by memory_crystalize and injected into every session_start automatically. ' +
+            'Call this to review what institutional knowledge is preserved, or to decide if a refresh is due.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the cache instance' },
+            },
+            required: ['instance_id'],
+        },
+    },
     // ── Roadmap — Persistent project plan tracker ───────────────────────────
     {
         name: 'roadmap_add',
@@ -3465,6 +3480,60 @@ const TOOLS = [
             required: [],
         },
     },
+    // ── v0.9 — compact_recover ─────────────────────────────────────────────────
+    {
+        name: 'compact_recover',
+        description: 'FAST context recovery after Claude/Cursor/Copilot context window compaction. ' +
+            'Call this as the FIRST tool call after any context limit hit or window restart — before reading any files. ' +
+            'Returns: last checkpoint (task + files + next_step), session handoff if any, last 5 recalled lessons, open TODOs. ' +
+            'Unlike session_start, this is instant — no full brain scan, no streak logic, just the critical recovery data. ' +
+            'Typical use in CLAUDE.md: "If context is compacted, call compact_recover immediately."',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the cache instance' },
+                focus: {
+                    type: 'string',
+                    description: 'What you are trying to recover context for — used to surface relevant lessons (optional)',
+                },
+            },
+            required: ['instance_id'],
+        },
+    },
+    // ── v0.9 — brain_from_git ─────────────────────────────────────────────────
+    {
+        name: 'brain_from_git',
+        description: 'Bootstrap the AI Brain from git history — reads commit messages and automatically stores lessons. ' +
+            'Scans the last N days of commits, extracts actionable knowledge (fixes, reverts, deploys, migrations), ' +
+            'and bulk-loads them into the Brain as lessons. ' +
+            'Run once to pre-load months of team knowledge before the first session_start. ' +
+            'Skips commits already in the Brain (safe to re-run). ' +
+            'Example: brain_from_git(instance_id="...", workspace_path="/home/you/project", days=180) ' +
+            '→ "📊 Scanned 342 commits · ✅ 28 lessons stored · ❌ 9 failure lessons · 0 duplicates skipped"',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                instance_id: { type: 'string', description: 'UUID of the cache instance' },
+                workspace_path: {
+                    type: 'string',
+                    description: 'Absolute path to the git repository root (e.g. "/home/you/myproject")',
+                },
+                days: {
+                    type: 'number',
+                    description: 'How many days of history to scan (default: 180, max: 365)',
+                },
+                max_commits: {
+                    type: 'number',
+                    description: 'Maximum number of commits to process (default: 200, max: 500)',
+                },
+                author: {
+                    type: 'string',
+                    description: 'Filter to commits by this git author email or name (optional — omit to scan all authors)',
+                },
+            },
+            required: ['instance_id', 'workspace_path'],
+        },
+    },
 ];
 // ── Handlers ──────────────────────────────────────────────────────────────────
 function formatInstance(inst) {
@@ -5186,6 +5255,22 @@ async function handleTool(name, args) {
                 }
                 catch { /* git not available or not a repo — silent skip */ }
             }
+            // ── Crystal age check — remind if > 30 days old or missing ──────────────
+            let crystalReminder = '';
+            try {
+                const crystalRaw = await redis.get('cachly:crystal:latest');
+                if (!crystalRaw) {
+                    crystalReminder = `💎 **Memory Crystal:** None exists yet. Run \`memory_crystalize(instance_id="${instance_id}")\` to distill your brain into a permanent snapshot — injected into every future session automatically.`;
+                }
+                else {
+                    const crystal = JSON.parse(crystalRaw);
+                    const crystalAgeDays = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
+                    if (crystalAgeDays >= 30) {
+                        crystalReminder = `💎 **Memory Crystal is ${crystalAgeDays} days old** (${crystal.label ?? 'unnamed'}). Run \`memory_crystalize(instance_id="${instance_id}")\` to refresh it with your latest ${crystal.lesson_count ?? '?'} lessons.`;
+                    }
+                }
+            }
+            catch { /* non-critical */ }
             const durationStr = durationMin !== undefined ? ` · ${durationMin} min` : '';
             return [
                 `✅ **Session saved**${durationStr}`,
@@ -5195,6 +5280,7 @@ async function handleTool(name, args) {
                 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 ? '…' : ''})` : '',
+                crystalReminder,
                 ``,
                 `💡 Next session: \`session_start(focus="...")\` to see this summary.`,
             ].filter(l => l !== '').join('\n');
@@ -5583,6 +5669,52 @@ async function handleTool(name, args) {
             ];
             return lines.join('\n');
         }
+        // ── crystal_view — show current Memory Crystal ───────────────────────────
+        case 'crystal_view': {
+            const { instance_id } = args;
+            const redis = await getConnection(instance_id);
+            const crystalRaw = await redis.get('cachly:crystal:latest');
+            if (!crystalRaw) {
+                return [
+                    `💎 **No Memory Crystal yet**`,
+                    ``,
+                    `Your brain has no crystal — all knowledge lives in raw lessons only.`,
+                    ``,
+                    `Run \`memory_crystalize(instance_id="${instance_id}")\` to:`,
+                    `  • Distill everything learned into a permanent, compact snapshot`,
+                    `  • Inject it into every future \`session_start\` automatically`,
+                    `  • Preserve team knowledge even after lesson TTLs expire`,
+                    ``,
+                    `💡 Recommended: run monthly or after any major milestone.`,
+                ].join('\n');
+            }
+            const crystal = JSON.parse(crystalRaw);
+            const ageDays = Math.round((Date.now() - new Date(crystal.ts).getTime()) / 86_400_000);
+            const ageStr = ageDays === 0 ? 'today' : ageDays === 1 ? '1 day ago' : `${ageDays} days ago`;
+            const freshness = ageDays < 14 ? '🟢 Fresh' : ageDays < 30 ? '🟡 Aging' : '🔴 Stale — refresh recommended';
+            const lines = [
+                `💎 **Memory Crystal: ${crystal.label}**`,
+                ``,
+                `📅 Created: **${ageStr}** · Freshness: ${freshness}`,
+                `📊 Compressed: **${crystal.session_count} sessions** + **${crystal.lesson_count} lessons** → ${crystal.top_patterns.length} patterns`,
+                `🗂️  Categories: ${crystal.categories.slice(0, 10).join(', ')}${crystal.categories.length > 10 ? `… +${crystal.categories.length - 10}` : ''}`,
+                ``,
+                `**Top patterns by category:**`,
+                ``,
+            ];
+            for (const p of crystal.top_patterns) {
+                lines.push(`**${p.category}** (${p.count} lesson${p.count > 1 ? 's' : ''})`);
+                lines.push(`  → ${p.insight.slice(0, 150)}${p.insight.length > 150 ? '…' : ''}`);
+                lines.push('');
+            }
+            if (ageDays >= 30) {
+                lines.push(`---`, `⚠️ Crystal is ${ageDays} days old. Run \`memory_crystalize(instance_id="${instance_id}")\` to refresh with your latest lessons.`);
+            }
+            else {
+                lines.push(`---`, `💡 This crystal is injected automatically into every \`session_start\`. Refresh monthly with \`memory_crystalize\`.`);
+            }
+            return lines.filter(l => l !== undefined).join('\n');
+        }
         case 'brain_doctor': {
             const { instance_id, workspace_path: drWorkspacePath = '' } = args;
             const redis = await getConnection(instance_id);
@@ -6982,9 +7114,11 @@ async function handleBulkLockStream(name, args) {
 > Sessions are fully automatic. The Brain starts when you call any tool and saves a summary when you close.
 
 ### MANDATORY hooks (always fire, no exceptions):
+- **Context compacted** → call \`compact_recover(instance_id="${instance_id}", focus="<current task>")\` FIRST
 - **Window opens** → call \`session_start(instance_id="${instance_id}", focus="<today's goal>")\`
 - **Bug fixed / deployed / discovered** → call \`learn_from_attempts(instance_id="${instance_id}", topic="fix:<area>", outcome="success", what_worked="...")\`
 - **Window closes** → call \`session_end(instance_id="${instance_id}", summary="...", files_changed=[...])\`
+- **Monthly** → call \`memory_crystalize(instance_id="${instance_id}")\` to distill knowledge into a permanent Crystal
 `;
             const full = `## Cachly AI Brain — Autopilot for ${project_name}
 
@@ -7044,18 +7178,40 @@ smart_recall(
 
 ---
 
-## ⚡ Cognitive Tools (v0.6)
+## ⚡ Context Recovery (MANDATORY after compaction)
+
+**If your context window was compacted**, call this FIRST — before reading any file:
+\`\`\`
+compact_recover(
+  instance_id = "${instance_id}",
+  focus       = "<what you were working on>",
+)
+\`\`\`
+Returns: last checkpoint, pending tasks, top lessons. Instant — no full brain scan.
+
+---
+
+## 🔁 Scheduled Maintenance (run on schedule)
+
+| When | Call |
+|---|---|
+| **Monthly** | \`memory_crystalize(instance_id="${instance_id}")\` — distill brain into a permanent snapshot |
+| Weekly review | \`brain_diff(instance_id="${instance_id}", since="7d")\` — see what your AI learned this week |
+| Before big refactor | \`knowledge_decay(instance_id="${instance_id}")\` — see which lessons to still trust |
+| After major milestone | \`memory_crystalize(instance_id="${instance_id}", label="v2 launch")\` — preserve milestone knowledge |
+
+## 🧠 Cognitive Tools (use anytime)
 
 | When | Call |
 |---|---|
 | Brain feeling cluttered | \`memory_consolidate(instance_id="${instance_id}")\` |
-| Weekly review | \`brain_diff(instance_id="${instance_id}", since="7d")\` |
 | Weird bug, no idea why | \`causal_trace(instance_id="${instance_id}", problem="<symptom>")\` |
-| Before big refactor | \`knowledge_decay(instance_id="${instance_id}")\` |
+| Unknown error | \`syndicate_search(q="<error message>")\` — global community solutions |
+| Unknown error that you solved | \`syndicate(instance_id="${instance_id}", topic="fix:<area>", what_worked="...")\` |
 
 ---
 
-*Cachly v0.6 · Generated ${new Date().toISOString().slice(0, 10)}*
+*Cachly v0.9 · Generated ${new Date().toISOString().slice(0, 10)}*
 `;
             const content = style === 'minimal' ? minimal : full;
             const filename = editor === 'copilot'
@@ -7214,6 +7370,173 @@ smart_recall(
             lines.push(`---`, `**Confirm** (if this helped you): \`syndicate(topic="${res.results[0]?.topic ?? '...'}", what_worked="...")\` → auto-deduped, trust +1`, `**All trending:** \`syndicate_trending(limit=50)\`  |  **Search:** \`syndicate_search(q="...")\``);
             return lines.filter(l => l !== '').join('\n');
         }
+        // ── v0.9 compact_recover — fast context recovery ──────────────────────────
+        case 'compact_recover': {
+            const { instance_id, focus = '' } = args;
+            const redis = await getConnection(instance_id);
+            const lines = ['⚡ **Context Recovered**', ''];
+            // 1. Latest checkpoint
+            const checkpointRaw = await redis.get('cachly:session:checkpoint');
+            if (checkpointRaw) {
+                try {
+                    const cp = JSON.parse(checkpointRaw);
+                    const ago = Math.round((Date.now() - new Date(cp.ts).getTime()) / 60000);
+                    const agoStr = ago < 60 ? `${ago}m ago` : `${Math.round(ago / 60)}h ago`;
+                    lines.push(`📌 **Last checkpoint** (${agoStr}): ${cp.task}`);
+                    if (cp.files_touched && cp.files_touched.length > 0) {
+                        lines.push(`   Files: ${cp.files_touched.slice(0, 5).join(', ')}${cp.files_touched.length > 5 ? '…' : ''}`);
+                    }
+                    if (cp.next_step)
+                        lines.push(`📍 **Resume with:** ${cp.next_step}`);
+                    lines.push('');
+                }
+                catch { /* ignore corrupt */ }
+            }
+            // 2. Handoff (if any, from a different window)
+            const handoffRaw = await redis.get('cachly:session:handoff');
+            if (handoffRaw) {
+                try {
+                    const hf = JSON.parse(handoffRaw);
+                    const remaining = hf.remaining_tasks ?? [];
+                    if (remaining.length > 0) {
+                        lines.push(`⏳ **Remaining tasks:**`);
+                        remaining.slice(0, 5).forEach(t => lines.push(`  - ${t}`));
+                        if (remaining.length > 5)
+                            lines.push(`  …and ${remaining.length - 5} more`);
+                        lines.push('');
+                    }
+                    if (hf.blocked_on) {
+                        lines.push(`🚫 **Blocked on:** ${hf.blocked_on}`, '');
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            // 3. Top recently recalled lessons (BM25 if focus, else recency)
+            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 allLessons = [];
+            for (const k of lessonKeys) {
+                const raw = await redis.get(k);
+                if (!raw)
+                    continue;
+                try {
+                    allLessons.push(JSON.parse(raw));
+                }
+                catch { /* skip */ }
+            }
+            const focusTerms = focus.toLowerCase().split(/\s+/).filter(Boolean);
+            let topLessons = focusTerms.length > 0
+                ? allLessons.filter(l => focusTerms.some(t => l.topic.toLowerCase().includes(t) || (l.tags ?? []).some((tag) => tag.toLowerCase().includes(t)))).slice(0, 5)
+                : allLessons.sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0)).slice(0, 5);
+            if (topLessons.length > 0) {
+                lines.push(`🧠 **Top lessons${focus ? ` for "${focus}"` : ''}:**`);
+                for (const l of topLessons) {
+                    const icon = l.outcome === 'success' ? '✅' : l.outcome === 'failure' ? '❌' : '⚠️';
+                    lines.push(`  ${icon} \`${l.topic}\` — ${l.what_worked.slice(0, 120)}${l.what_worked.length > 120 ? '…' : ''}`);
+                }
+                lines.push('');
+            }
+            lines.push(`💡 Call \`session_start\` for the full briefing, or resume work directly.`);
+            return lines.filter(l => l !== '').join('\n');
+        }
+        // ── v0.9 brain_from_git — bulk-load git history as lessons ───────────────
+        case 'brain_from_git': {
+            const { instance_id, workspace_path, days = 180, max_commits = 200, author = '', } = args;
+            const redis = await getConnection(instance_id);
+            const { execSync } = await import('node:child_process');
+            const clampedDays = Math.min(Math.max(1, days), 365);
+            const clampedMax = Math.min(Math.max(1, max_commits), 500);
+            const authorArg = author ? `--author="${author}"` : '';
+            let gitRaw = '';
+            try {
+                gitRaw = execSync(`git -C "${workspace_path}" log --since="${clampedDays} days ago" ${authorArg} --oneline --format="%H|||%s|||%ai|||%ae" -n ${clampedMax}`, { timeout: 15000, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+            }
+            catch {
+                return `❌ **brain_from_git failed**: Could not read git log from \`${workspace_path}\`.\nMake sure the path exists and is a git repository.`;
+            }
+            if (!gitRaw) {
+                return `📭 **No commits found** in the last ${clampedDays} days${author ? ` by "${author}"` : ''}.\nTry increasing \`days\` or removing the \`author\` filter.`;
+            }
+            const commitLines = gitRaw.split('\n');
+            const now = new Date();
+            const actionRe = /\b(fix|add|remove|refactor|migrate|update|resolve|implement|improve|optimize|configure|create|delete|disable|enable|debug|patch|upgrade|rewrite|deploy|feat|revert|break|merge|bump)\b/i;
+            const failRe = /\b(revert|broken|broke|breaking|rollback|undo|hotfix|crash|oops|wrong|mistake|bad)\b/i;
+            let stored = 0;
+            let skipped = 0;
+            let failures = 0;
+            const topLessons = [];
+            for (const line of commitLines) {
+                const parts = line.split('|||');
+                if (parts.length < 2)
+                    continue;
+                const [hash, msg, dateStr] = parts;
+                if (!msg || !actionRe.test(msg))
+                    continue;
+                const isFail = failRe.test(msg);
+                const cleanMsg = msg
+                    .replace(/^(fix|feat|chore|docs|test|ci|perf|refactor|build|revert|hotfix|bump)[:(\s!]+/i, '')
+                    .trim();
+                if (!cleanMsg || cleanMsg.length < 5)
+                    continue;
+                const slug = cleanMsg
+                    .toLowerCase()
+                    .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) {
+                    skipped++;
+                    continue;
+                }
+                const lesson = {
+                    topic,
+                    outcome: isFail ? 'failure' : 'success',
+                    what_worked: isFail ? '' : cleanMsg.slice(0, 300),
+                    what_failed: isFail ? cleanMsg.slice(0, 300) : undefined,
+                    context: `Auto-learned from git commit ${(hash ?? '').slice(0, 7)}${dateStr ? ` at ${dateStr}` : ''} in ${workspace_path}${author ? ` (author: ${author})` : ''}`,
+                    severity: 'minor',
+                    ts: dateStr ? new Date(dateStr).toISOString() : now.toISOString(),
+                    recall_count: 0,
+                    auto_learned: true,
+                    source: 'brain_from_git',
+                    version: 3,
+                };
+                await redis.set(key, JSON.stringify(lesson));
+                await redis.expire(key, 90 * 86400); // 90-day TTL for git-sourced lessons
+                stored++;
+                if (isFail)
+                    failures++;
+                if (topLessons.length < 5)
+                    topLessons.push(`  ${isFail ? '❌' : '✅'} \`${topic}\` — ${cleanMsg.slice(0, 80)}`);
+            }
+            const lines = [
+                `🧠 **Brain bootstrapped from git history**`,
+                ``,
+                `📊 **Scanned:** ${commitLines.filter(l => l.trim()).length} commits over last ${clampedDays} days`,
+                `✅ **Success lessons stored:** ${stored - failures}`,
+                `❌ **Failure/revert lessons:** ${failures}`,
+                skipped > 0 ? `⏭️  **Already in brain (skipped):** ${skipped}` : '',
+                ``,
+            ];
+            if (topLessons.length > 0) {
+                lines.push(`**Top lessons extracted:**`);
+                lines.push(...topLessons);
+                if (stored > 5)
+                    lines.push(`  …and ${stored - 5} more`);
+                lines.push('');
+            }
+            lines.push(`💡 **Next step:** Call \`session_start(focus="...")\` to see these lessons in your briefing.`, `🔄 **Re-run anytime** — duplicates are safely skipped.`);
+            return lines.filter(l => l !== '').join('\n');
+        }
         default:
             return null;
     }