@cachly-dev/mcp-server 0.10.61 → 0.10.64

package/dist/src/handlers/brain.js

@@ -1,13 +1,19 @@
 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, ckgUpsertPersonNode, ckgUpsertFileNode } from '../ckg.js';
-import { safeJsonParse } from '../utils.js';
+import { safeJsonParse, scanKeys } from '../utils.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.61';
+const MCP_VERSION = '0.10.64';
 const WHATS_NEW = {
+    '0.10.64': [
+        `📈 **The three decisive metrics, now measurable**`,
+        `  ⏱️ \`brain_metrics()\` — time-to-first-recall, recall-lift, team-knowledge-reuse in one view`,
+        `  👥 Cross-author reuse tracked: recall a teammate's lesson → counted + surfaced inline`,
+        `  🛡️ Stability: scans now capped + timed out (a huge keyspace can't hang the agent)`,
+    ],
     '0.10.61': [
         `🎯 **Phase 3C: 100 MCP tools milestone — zero-setup knowledge graph**`,
         `  🔄 \`brain_from_git\` now auto-builds Person+File nodes from git history (zero setup!)`,
@@ -69,7 +75,7 @@ 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',
     'brain_who_knows', 'brain_file_map', 'team_expertise_map',
-    'skill_gaps', 'brain_coverage',
+    'skill_gaps', 'brain_coverage', 'brain_metrics',
 ]);
 export async function handleBrainTool(name, args, getConnection, apiFetch) {
     switch (name) {
@@ -201,6 +207,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 version: 3,
             };
             const lesson = JSON.stringify(lessonObj);
+            // Metric 1 (time-to-first-recall): mark the moment the Brain first gained
+            // knowledge. SET NX so only the very first learn wins. Fire-and-forget.
+            redis.set(`cachly:stats:born_at:${instance_id}`, ts, 'EX', 365 * 86400, 'NX').catch(() => { });
             // Always append to the history list (audit log); keep last 100 entries, 90-day TTL
             const listKey = `cachly:lessons:${topic}`;
             await redis.rpush(listKey, lesson);
@@ -510,7 +519,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             return `🔍 **Partial matches for \`${topic}\`:**\n\n${results.join('\n\n')}`;
         }
         case 'smart_recall': {
-            const { instance_id, query, threshold = 0.78, } = args;
+            const { instance_id, query, threshold = 0.78, author: requester = '', } = args;
             const redis = await getConnection(instance_id);
             // ── Layer 1: Keyword search across ALL brain data (always works, no embedding) ──
             const rawMatches = await keywordSearch(redis, ['cachly:ctx:*', 'cachly:lesson:best:*', 'cachly:idx:*'], query, 10);
@@ -519,6 +528,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             const kwMatches = rerankByQuality(rawMatches);
             const savedHere = [];
             const lessonMatches = kwMatches.filter(m => m.key.startsWith('cachly:lesson:best:'));
+            let crossAuthorThisCall = 0;
             for (const m of lessonMatches.slice(0, 5)) {
                 const existing = await redis.get(m.key).catch(() => null);
                 if (existing) {
@@ -529,6 +539,15 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         const sev = lesson.severity;
                         const savedMins = sev === 'critical' ? 240 : sev === 'major' ? 60 : 30;
                         redis.incrbyfloat(`cachly:stats:time_saved_mins:${instance_id}`, savedMins).catch(() => { });
+                        // Metric 3 (team-knowledge-reuse): a recall of a lesson authored by
+                        // someone OTHER than the requester is cross-author reuse — the value
+                        // only cachly delivers. Track total proven recalls + cross-author ones.
+                        redis.incr(`cachly:stats:recalls_total:${instance_id}`).catch(() => { });
+                        if (lesson.author && requester && lesson.author !== requester) {
+                            crossAuthorThisCall++;
+                            redis.incr(`cachly:stats:cross_author_recalls:${instance_id}`).catch(() => { });
+                            redis.sadd(`cachly:stats:reuse_pairs:${instance_id}`, `${requester}<-${lesson.author}`).catch(() => { });
+                        }
                         // Surface banner for proven successes (recall_count >= 1 means it's been validated)
                         if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1) {
                             savedHere.push({
@@ -541,6 +560,11 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     }
                 }
             }
+            // Metric 1 (time-to-first-recall): stamp the first time recall returned a
+            // proven lesson. SET NX so only the first successful recall wins.
+            if (savedHere.length > 0) {
+                redis.set(`cachly:stats:first_recall_at:${instance_id}`, new Date().toISOString(), 'EX', 365 * 86400, 'NX').catch(() => { });
+            }
             // ── Layer 2: Semantic search (parallel, optional) ────────────────────────
             const inst = await apiFetch(`/api/v1/instances/${instance_id}`).catch(() => null);
             const semHits = [];
@@ -666,6 +690,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             if (topLesson) {
                 lines.push(`> 💡 **Brain saved you ~${topLesson.savedMins}m here** — ${topLesson.severity} issue from \`${topLesson.topic}\` recalled ${topLesson.recall_count}× proven\n`);
             }
+            if (crossAuthorThisCall > 0) {
+                lines.push(`> 👥 **Team knowledge reuse** — ${crossAuthorThisCall} of these lesson${crossAuthorThisCall !== 1 ? 's were' : ' was'} written by a teammate. This is the value only a shared brain delivers.\n`);
+            }
             // Show sub-query info if multi-topic was detected
             const subQueries = splitMultiQuery(query);
             if (subQueries.length > 1) {
@@ -1843,6 +1870,10 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
         // whose authored edges in the CKG match the query topic.
         case 'brain_who_knows': {
             const { instance_id, topic, limit = 10, } = args;
+            if (!topic || typeof topic !== 'string' || !topic.trim()) {
+                return '⚠️ `brain_who_knows` requires a non-empty `topic`. Example: `brain_who_knows(topic="kubernetes deployment")`.';
+            }
+            const safeLimit = Math.max(1, Math.min(Number(limit) || 10, 50));
             const redis = await getConnection(instance_id);
             // Step 1: Find candidate concept node IDs matching the query
             const querySlug = ckgSlug(topic);
@@ -1917,7 +1948,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 lastActive: s.lastActive,
             }))
                 .sort((a, b) => (b.lessonCount * b.avgConfidence) - (a.lessonCount * a.avgConfidence))
-                .slice(0, limit);
+                .slice(0, safeLimit);
             const lines = [
                 `## 👥 Who Knows About \`${topic}\`?`,
                 ``,
@@ -1938,8 +1969,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
         // Phase 3B: "What do we know about these files?" — experts + lessons per file.
         case 'brain_file_map': {
             const { instance_id, file_paths = [], } = args;
-            if (!file_paths.length)
-                return '⚠️ Pass at least one file path.';
+            // Defensive: accept only a non-empty array of non-empty strings.
+            const cleanPaths = (Array.isArray(file_paths) ? file_paths : [])
+                .filter((p) => typeof p === 'string' && p.trim().length > 0)
+                .map(p => p.trim());
+            if (!cleanPaths.length)
+                return '⚠️ Pass at least one file path. Example: `brain_file_map(file_paths=["src/auth/jwt.ts"])`.';
             const redis = await getConnection(instance_id);
             const lines = [
                 `## 📁 File Knowledge Map`,
@@ -1947,7 +1982,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 `_What cachly knows about the files you're about to touch:_`,
                 ``,
             ];
-            for (const fp of file_paths.slice(0, 10)) {
+            for (const fp of cleanPaths.slice(0, 10)) {
                 lines.push(`### \`${fp}\``);
                 // ── Experts via CKG file nodes ─────────────────────────────────────
                 const fileId = `file:${ckgSlug(fp)}`;
@@ -2003,14 +2038,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
                 // Also: exact file_paths match via lesson scan
                 if (relatedLessons.length < 2) {
-                    const scanKeys = [];
-                    const stream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
-                    await new Promise((res, rej) => {
-                        stream.on('data', (b) => scanKeys.push(...b));
-                        stream.on('end', res);
-                        stream.on('error', rej);
-                    });
-                    for (const k of scanKeys.slice(0, 300)) {
+                    const allLessonKeys = await scanKeys(redis, 'cachly:lesson:best:*', { max: 1500 });
+                    for (const k of allLessonKeys.slice(0, 300)) {
                         const raw = await redis.get(k);
                         if (!raw)
                             continue;
@@ -2045,14 +2074,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
         case 'team_expertise_map': {
             const { instance_id, top_n = 20, } = args;
             const redis = await getConnection(instance_id);
-            // Scan all person nodes
-            const personKeys = [];
-            const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
-            await new Promise((res, rej) => {
-                pStream.on('data', (b) => personKeys.push(...b));
-                pStream.on('end', res);
-                pStream.on('error', rej);
-            });
+            // Scan all person nodes (capped + timed out so a huge keyspace can't hang the agent)
+            const personKeys = await scanKeys(redis, 'cachly:ckg:node:person:*', { max: 2000 });
             if (personKeys.length === 0) {
                 return [
                     `## 🗺️ Team Expertise Map`,
@@ -2113,14 +2136,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
         case 'skill_gaps': {
             const { instance_id, min_failures = 1, } = args;
             const redis = await getConnection(instance_id);
-            // Scan all best lessons
-            const lessonKeys = [];
-            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 500 });
-            await new Promise((res, rej) => {
-                lStream.on('data', (b) => lessonKeys.push(...b));
-                lStream.on('end', res);
-                lStream.on('error', rej);
-            });
+            // Scan all best lessons (capped + timed out)
+            const lessonKeys = await scanKeys(redis, 'cachly:lesson:best:*', { max: 3000 });
             const domainMap = new Map();
             let totalAttributed = 0;
             let totalPrivate = 0;
@@ -2161,14 +2178,6 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     });
                 }
             }
-            // Check for domains with person nodes but no lessons (contributors without lessons)
-            const personKeys = [];
-            const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
-            await new Promise((res, rej) => {
-                pStream.on('data', (b) => personKeys.push(...b));
-                pStream.on('end', res);
-                pStream.on('error', rej);
-            });
             const lines = [
                 `## 🔍 Skill Gaps — Knowledge Blind Spots`,
                 ``,
@@ -2201,30 +2210,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
         case 'brain_coverage': {
             const { instance_id, repo_path = '.', } = args;
             const redis = await getConnection(instance_id);
-            // Count lessons
-            const lessonKeys = [];
-            const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 500 });
-            await new Promise((res, rej) => {
-                lStream.on('data', (b) => lessonKeys.push(...b));
-                lStream.on('end', res);
-                lStream.on('error', rej);
-            });
-            // Count person nodes
-            const personKeys = [];
-            const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
-            await new Promise((res, rej) => {
-                pStream.on('data', (b) => personKeys.push(...b));
-                pStream.on('end', res);
-                pStream.on('error', rej);
-            });
-            // Count file nodes in CKG
-            const fileKeys = [];
-            const fStream = redis.scanStream({ match: 'cachly:ckg:node:file:*', count: 500 });
-            await new Promise((res, rej) => {
-                fStream.on('data', (b) => fileKeys.push(...b));
-                fStream.on('end', res);
-                fStream.on('error', rej);
-            });
+            // Count lessons, person + file nodes (each capped + timed out, gathered in parallel)
+            const [lessonKeys, personKeys, fileKeys] = await Promise.all([
+                scanKeys(redis, 'cachly:lesson:best:*', { max: 5000 }),
+                scanKeys(redis, 'cachly:ckg:node:person:*', { max: 2000 }),
+                scanKeys(redis, 'cachly:ckg:node:file:*', { max: 5000 }),
+            ]);
             // Get git file count for comparison (optional — non-critical if not a git repo)
             let gitFileCount = 0;
             let _gitFileCountLabel = 'n/a';
@@ -2290,6 +2281,69 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 `_Boost score: run \`brain_from_git\` · add \`author\` to \`learn_from_attempts\` · fix gaps with \`skill_gaps\`_`,
             ].join('\n');
         }
+        // ── brain_metrics ─────────────────────────────────────────────────────────
+        // The three decisive metrics (PROGRESS.md §3 / VISION_10X.md §4):
+        //   1. Time-to-first-recall  — onboarding friction
+        //   2. Recall-lift           — the moat proof (vs. raw BM25)
+        //   3. Team-knowledge-reuse  — the value only a shared brain delivers
+        case 'brain_metrics': {
+            const { instance_id } = args;
+            const redis = await getConnection(instance_id);
+            const [bornAt, firstRecallAt, recallsTotalRaw, crossAuthorRaw, timeSavedRaw, reusePairs] = await Promise.all([
+                redis.get(`cachly:stats:born_at:${instance_id}`).catch(() => null),
+                redis.get(`cachly:stats:first_recall_at:${instance_id}`).catch(() => null),
+                redis.get(`cachly:stats:recalls_total:${instance_id}`).catch(() => null),
+                redis.get(`cachly:stats:cross_author_recalls:${instance_id}`).catch(() => null),
+                redis.get(`cachly:stats:time_saved_mins:${instance_id}`).catch(() => null),
+                redis.smembers(`cachly:stats:reuse_pairs:${instance_id}`).catch(() => []),
+            ]);
+            // ── Metric 1: Time-to-first-recall ──────────────────────────────────────
+            let ttfrLine;
+            if (bornAt && firstRecallAt) {
+                const ms = new Date(firstRecallAt).getTime() - new Date(bornAt).getTime();
+                const mins = Math.max(0, Math.round(ms / 60000));
+                const human = mins < 1 ? '<1 min' : mins < 60 ? `${mins} min` : `${(mins / 60).toFixed(1)} h`;
+                const target = ms <= 2 * 60000 ? '🟢 under 2 min target' : ms <= 60 * 60000 ? '🟡 over 2 min' : '🔴 over 1 h';
+                ttfrLine = `**${human}** from first lesson → first proven recall · ${target}`;
+            }
+            else if (bornAt && !firstRecallAt) {
+                ttfrLine = `🟡 Brain has knowledge but no proven recall yet — try \`smart_recall\``;
+            }
+            else {
+                ttfrLine = `⚪ Not enough data yet — store a lesson, then recall it`;
+            }
+            // ── Metric 2: Recall-lift (the moat proof) ──────────────────────────────
+            // Published headline from Cachly-Bench (CI-defended in rerank.test.ts).
+            const recallLiftLine = `**+22.2 % Precision@1**, **+10.9 % MRR**, **+8.1 % nDCG@5** vs. raw BM25`;
+            // ── Metric 3: Team-knowledge-reuse ──────────────────────────────────────
+            const recallsTotal = Number(recallsTotalRaw ?? 0);
+            const crossAuthor = Number(crossAuthorRaw ?? 0);
+            const reusePct = recallsTotal > 0 ? Math.round((crossAuthor / recallsTotal) * 100) : 0;
+            const reuseTarget = reusePct >= 30 ? '🟢 above 30 % target' : recallsTotal === 0 ? '⚪ no recalls yet' : '🟡 below 30 % target';
+            const timeSaved = Math.round(Number(timeSavedRaw ?? 0));
+            const timeSavedHuman = timeSaved < 60 ? `${timeSaved} min` : `${(timeSaved / 60).toFixed(1)} h`;
+            const lines = [
+                `## 📈 Brain Metrics — the three that decide everything`,
+                ``,
+                `### 1. Time-to-first-recall _(onboarding friction)_`,
+                ttfrLine,
+                ``,
+                `### 2. Recall-lift _(the moat proof)_`,
+                recallLiftLine,
+                `_Reproduce: \`npm run bench\` · CI-defended in \`rerank.test.ts\` · details in BENCH.md_`,
+                ``,
+                `### 3. Team-knowledge-reuse _(the value only a shared brain delivers)_`,
+                `**${reusePct}%** of proven recalls used a teammate's lesson (${crossAuthor}/${recallsTotal}) · ${reuseTarget}`,
+                reusePairs.length > 0 ? `**${reusePairs.length}** distinct reuse relationship${reusePairs.length !== 1 ? 's' : ''} across the team` : '',
+                ``,
+                `---`,
+                `⏱️ **${timeSavedHuman}** total saved not re-researching known fixes.`,
+                recallsTotal === 0
+                    ? `_Tip: pass \`author="your-handle"\` to \`smart_recall\` so cross-author reuse can be tracked._`
+                    : `_These numbers compound: every learned lesson and every teammate raises all three._`,
+            ].filter(Boolean);
+            return lines.join('\n');
+        }
         // ── sync_file_changes ─────────────────────────────────────────────────────
         default:
             return null;