@cachly-dev/mcp-server 0.10.62 → 0.10.65

package/src/handlers/brain.ts

@@ -4,7 +4,7 @@ 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 type { CKGEdge, CKGNode, PersonNode } from '../ckg.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein,
          indexVocab as _indexVocab } from '../search.js';
@@ -12,8 +12,14 @@ import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.62';
+const MCP_VERSION = '0.10.65';
 const WHATS_NEW: Record<string, string[]> = {
+  '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!)`,
@@ -94,7 +100,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(
@@ -272,6 +278,10 @@ export async function handleBrainTool(
       };
       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);
@@ -598,7 +608,8 @@ export async function handleBrainTool(
         instance_id,
         query,
         threshold = 0.78,
-      } = args as { instance_id: string; query: string; threshold?: number };
+        author: requester = '',
+      } = args as { instance_id: string; query: string; threshold?: number; author?: string };
 
       const redis = await getConnection(instance_id);
 
@@ -618,16 +629,28 @@ export async function handleBrainTool(
       type RecalledLesson = { topic: string; severity: string; recall_count: number; savedMins: number };
       const savedHere: RecalledLesson[] = [];
       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) {
-          const lesson = safeJsonParse(existing, null as null | { recall_count?: number; outcome?: string; severity?: string; [k: string]: unknown });
+          const lesson = safeJsonParse(existing, null as null | { recall_count?: number; outcome?: string; severity?: string; author?: string; [k: string]: unknown });
           if (lesson) {
             const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: new Date().toISOString() };
             redis.set(m.key, JSON.stringify(updated)).catch(() => {});
             const sev = lesson.severity as string;
             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({
@@ -641,6 +664,12 @@ export async function handleBrainTool(
         }
       }
 
+      // 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<Instance | null>(`/api/v1/instances/${instance_id}`).catch(() => null);
       type SemHit = { key: string; similarity: number; content: string };
@@ -771,6 +800,9 @@ export async function handleBrainTool(
       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);
@@ -2230,13 +2262,8 @@ export async function handleBrainTool(
         }
         // Also: exact file_paths match via lesson scan
         if (relatedLessons.length < 2) {
-          const scanKeys: string[] = [];
-          const stream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 200 });
-          await new Promise<void>((res, rej) => {
-            stream.on('data', (b: string[]) => 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;
             const ld = safeJsonParse<{
@@ -2280,13 +2307,8 @@ export async function handleBrainTool(
 
       const redis = await getConnection(instance_id);
 
-      // Scan all person nodes
-      const personKeys: string[] = [];
-      const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
-      await new Promise<void>((res, rej) => {
-        pStream.on('data', (b: string[]) => 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 [
@@ -2362,13 +2384,8 @@ export async function handleBrainTool(
 
       const redis = await getConnection(instance_id);
 
-      // Scan all best lessons
-      const lessonKeys: string[] = [];
-      const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 500 });
-      await new Promise<void>((res, rej) => {
-        lStream.on('data', (b: string[]) => 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 });
 
       type DomainStats = { successes: number; failures: number; attributed: number; topics: string[] };
       const domainMap = new Map<string, DomainStats>();
@@ -2412,14 +2429,6 @@ export async function handleBrainTool(
         }
       }
 
-      // Check for domains with person nodes but no lessons (contributors without lessons)
-      const personKeys: string[] = [];
-      const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
-      await new Promise<void>((res, rej) => {
-        pStream.on('data', (b: string[]) => personKeys.push(...b));
-        pStream.on('end', res); pStream.on('error', rej);
-      });
-
       const lines = [
         `## 🔍 Skill Gaps — Knowledge Blind Spots`,
         ``,
@@ -2463,29 +2472,12 @@ export async function handleBrainTool(
 
       const redis = await getConnection(instance_id);
 
-      // Count lessons
-      const lessonKeys: string[] = [];
-      const lStream = redis.scanStream({ match: 'cachly:lesson:best:*', count: 500 });
-      await new Promise<void>((res, rej) => {
-        lStream.on('data', (b: string[]) => lessonKeys.push(...b));
-        lStream.on('end', res); lStream.on('error', rej);
-      });
-
-      // Count person nodes
-      const personKeys: string[] = [];
-      const pStream = redis.scanStream({ match: 'cachly:ckg:node:person:*', count: 200 });
-      await new Promise<void>((res, rej) => {
-        pStream.on('data', (b: string[]) => personKeys.push(...b));
-        pStream.on('end', res); pStream.on('error', rej);
-      });
-
-      // Count file nodes in CKG
-      const fileKeys: string[] = [];
-      const fStream = redis.scanStream({ match: 'cachly:ckg:node:file:*', count: 500 });
-      await new Promise<void>((res, rej) => {
-        fStream.on('data', (b: string[]) => 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;
@@ -2553,6 +2545,75 @@ export async function handleBrainTool(
       ].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 as { instance_id: string };
+      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(() => [] as string[]),
+        ]);
+
+      // ── Metric 1: Time-to-first-recall ──────────────────────────────────────
+      let ttfrLine: string;
+      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:

package/src/handlers/fedbrain.ts

@@ -3,7 +3,7 @@ import type { Redis } from 'ioredis';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge,
          ckgUpsertPersonNode, ckgUpsertFileNode } from '../ckg.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
-import { safeJsonParse } from '../utils.js';
+import { safeJsonParse, normalizeGitPath } from '../utils.js';
 
 // Last brain_from_git category counts — set after each run so index.ts can include them in telemetry
 export let _lastBrainFromGitCounts: { fixes: number; features: number; refactors: number; total: number } | null = null;
@@ -945,7 +945,8 @@ export async function handleFedbrainTool(
           const [, sha, subject, date, author] = line.split('|||');
           current = { sha: (sha ?? '').trim(), subject: (subject ?? '').trim(), date: (date ?? '').trim(), author: (author ?? '').trim(), files: [] };
         } else if (line && current) {
-          current.files.push(line);
+          const norm = normalizeGitPath(line);
+          if (norm) current.files.push(norm);
         }
       }
       if (current) commits.push(current);

package/src/index.ts

@@ -73,7 +73,7 @@ import { Redis } from 'ioredis';
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 let JWT = process.env.CACHLY_JWT ?? '';
 const _EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.10.62';
+const CURRENT_VERSION = '0.10.65';
 
 // Max time to wait for a freshly-provisioned instance to become "running" before
 // giving up. Free-tier provisioning in high-latency regions can take 45–90s, so the
@@ -572,7 +572,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         '',
         'After sign-in: call **any tool again** — your Brain activates instantly.',
         '',
-        '✨ Free forever · No credit card · 100 MCP tools · GDPR · EU servers',
+        '✨ Free forever · No credit card · 101 MCP tools · GDPR · EU servers',
       ].join('\n');
     }
 
@@ -1816,7 +1816,7 @@ if (!process.argv[2] && process.stdout.isTTY) {
   console.log('  \x1b[36m  npx @cachly-dev/mcp-server@latest upgrade\x1b[0m  ← Check for updates');
   console.log('');
   console.log('  \x1b[90mWorks with: Claude Code · Cursor · Windsurf · GitHub Copilot · Cline · Zed\x1b[0m');
-  console.log('  \x1b[90mFree forever · GDPR · German servers · 100 MCP tools\x1b[0m');
+  console.log('  \x1b[90mFree forever · GDPR · German servers · 101 MCP tools\x1b[0m');
   console.log('');
   process.exit(0);
 }

package/src/tools.ts

@@ -617,6 +617,7 @@ const TOOLS = [
         instance_id: { type: 'string', description: 'UUID of the cache instance' },
         query: { type: 'string', description: 'Natural language query to find relevant cached context' },
         threshold: { type: 'number', description: 'Similarity threshold 0-1 (default: 0.78)' },
+        author: { type: 'string', description: 'Handle of the person doing the recall (optional). Enables team-knowledge-reuse tracking: when you recall a lesson written by a teammate, cachly counts it as cross-author reuse — the value only a shared brain delivers.' },
       },
       required: ['instance_id', 'query'],
     },
@@ -893,6 +894,22 @@ const TOOLS = [
       required: ['instance_id'],
     },
   },
+  {
+    name: 'brain_metrics',
+    description:
+      'Report the three decisive Brain metrics: (1) time-to-first-recall (onboarding friction), ' +
+      '(2) recall-lift vs. raw BM25 (the moat proof, from Cachly-Bench), and ' +
+      '(3) team-knowledge-reuse — what % of proven recalls used a teammate\'s lesson. ' +
+      'Use to track whether the Brain is delivering its core value. ' +
+      'Pass author="handle" to smart_recall so cross-author reuse can be measured.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the cache instance' },
+      },
+      required: ['instance_id'],
+    },
+  },
   {
     name: 'sync_file_changes',
     description:

package/src/utils.ts

@@ -8,3 +8,83 @@ export function safeJsonParse<T>(raw: string | null | undefined, fallback: T): T
     return fallback;
   }
 }
+
+/**
+ * Runs a promise with a hard timeout. If it doesn't settle within `ms`, resolves
+ * with `fallback` instead of hanging. A memory tool must NEVER block the agent's
+ * turn — a slow Redis scan or unreachable backend degrades gracefully to a fallback.
+ */
+export async function withTimeout<T>(p: Promise<T>, ms: number, fallback: T): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const guard = new Promise<T>((resolve) => {
+    timer = setTimeout(() => resolve(fallback), ms);
+  });
+  try {
+    return await Promise.race([p, guard]);
+  } catch {
+    return fallback;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// Minimal structural type for the Redis scan API we depend on — avoids importing
+// the full ioredis type into a leaf utility module.
+interface ScanCapable {
+  scanStream(opts: { match: string; count?: number }): {
+    on(event: 'data', cb: (batch: string[]) => void): void;
+    on(event: 'end', cb: () => void): void;
+    on(event: 'error', cb: (err: Error) => void): void;
+  };
+}
+
+/**
+ * Collects keys matching a pattern with a hard cap and timeout. Prevents a tool
+ * from hanging on a huge keyspace: stops early at `max` keys, and resolves with
+ * whatever was gathered if the scan exceeds `timeoutMs`. Never rejects.
+ */
+export function scanKeys(
+  redis: ScanCapable,
+  pattern: string,
+  opts: { max?: number; count?: number; timeoutMs?: number } = {},
+): Promise<string[]> {
+  const max = opts.max ?? 1000;
+  const timeoutMs = opts.timeoutMs ?? 3000;
+  return new Promise<string[]>((resolve) => {
+    const keys: string[] = [];
+    let done = false;
+    const finish = () => { if (!done) { done = true; resolve(keys); } };
+    const timer = setTimeout(finish, timeoutMs);
+    try {
+      const stream = redis.scanStream({ match: pattern, count: opts.count ?? 200 });
+      stream.on('data', (batch: string[]) => {
+        for (const k of batch) {
+          keys.push(k);
+          if (keys.length >= max) { clearTimeout(timer); finish(); return; }
+        }
+      });
+      stream.on('end', () => { clearTimeout(timer); finish(); });
+      stream.on('error', () => { clearTimeout(timer); finish(); });
+    } catch {
+      clearTimeout(timer);
+      finish();
+    }
+  });
+}
+
+/**
+ * Normalizes a git path that may come from `--name-only` with rename notation,
+ * e.g. `src/{old => new}/file.ts` → `src/new/file.ts`, and `a => b` → `b`.
+ * Returns the post-rename path so file nodes don't fragment on renames.
+ */
+export function normalizeGitPath(raw: string): string {
+  let p = raw.trim();
+  if (!p) return p;
+  // Brace rename: dir/{old => new}/file  →  dir/new/file
+  p = p.replace(/\{[^}]*=>\s*([^}]*)\}/g, (_m, after: string) => after.trim());
+  // Bare rename: old => new  →  new
+  const arrow = p.split('=>');
+  if (arrow.length === 2) p = arrow[1]!.trim();
+  // Collapse any double slashes introduced by an empty rename segment.
+  return p.replace(/\/{2,}/g, '/').replace(/^\/|\/$/g, '');
+}