@cachly-dev/mcp-server 0.10.62 → 0.10.64

package/dist/src/utils.js

@@ -10,4 +10,80 @@ export function safeJsonParse(raw, fallback) {
         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(p, ms, fallback) {
+    let timer;
+    const guard = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(fallback), ms);
+    });
+    try {
+        return await Promise.race([p, guard]);
+    }
+    catch {
+        return fallback;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * 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, pattern, opts = {}) {
+    const max = opts.max ?? 1000;
+    const timeoutMs = opts.timeoutMs ?? 3000;
+    return new Promise((resolve) => {
+        const keys = [];
+        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) => {
+                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) {
+    let p = raw.trim();
+    if (!p)
+        return p;
+    // Brace rename: dir/{old => new}/file  →  dir/new/file
+    p = p.replace(/\{[^}]*=>\s*([^}]*)\}/g, (_m, after) => 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, '');
+}
 //# sourceMappingURL=utils.js.map

package/dist/src/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gFAAgF;AAChF,MAAM,UAAU,aAAa,CAAI,GAA8B,EAAE,QAAW;IAC1E,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAM,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC;IAClB,CAAC;AACH,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.10.62",
+  "version": "0.10.64",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
-  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. Persistent memory + causal root-cause analysis for Claude Code, Cursor, Copilot & Windsurf. Learns from every bug fix, git commit, and CI run automatically. Arrives pre-briefed. Predicts failures before they happen. 100 MCP tools · Free tier forever · GDPR · EU servers.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. Persistent memory + causal root-cause analysis for Claude Code, Cursor, Copilot & Windsurf. Learns from every bug fix, git commit, and CI run automatically. Arrives pre-briefed. Predicts failures before they happen. 101 MCP tools · Free tier forever · GDPR · EU servers.",
   "type": "module",
   "bin": {
     "cachly-mcp": "dist/src/index.js"

package/server.json

@@ -1,18 +1,18 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.cachly-dev/cachly-mcp",
-  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 100 MCP tools · Free tier · EU servers · GDPR.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 101 MCP tools · Free tier · EU servers · GDPR.",
   "repository": {
     "url": "https://github.com/cachly-dev/cachly-mcp",
     "source": "github"
   },
-  "version": "0.10.62",
+  "version": "0.10.64",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.10.62",
+      "version": "0.10.64",
       "transport": {
         "type": "stdio"
       }

package/src/__tests__/brain-flow.test.ts

@@ -33,11 +33,19 @@ class MockRedis {
     return this.store.get(key) ?? null;
   }
 
-  async set(key: string, value: string): Promise<'OK'> {
+  async set(key: string, value: string, ...opts: unknown[]): Promise<'OK' | null> {
+    // Honor a trailing 'NX' flag so first-wins semantics (born_at, first_recall_at) work.
+    if (opts.includes('NX') && this.store.has(key)) return null;
     this.store.set(key, value);
     return 'OK';
   }
 
+  async incr(key: string): Promise<number> {
+    const next = parseInt(this.store.get(key) ?? '0', 10) + 1;
+    this.store.set(key, String(next));
+    return next;
+  }
+
   async rpush(key: string, ...values: string[]): Promise<number> {
     const list = this.lists.get(key) ?? [];
     list.push(...values);
@@ -1389,3 +1397,76 @@ describe('Phase 3 stability: input guards', () => {
     expect(out).toContain('Pass at least one file path');
   });
 });
+
+describe('Phase 3C: brain_metrics — the three decisive metrics', () => {
+  let redis: MockRedis;
+  const iid = 'i1';
+  const getConn = async () => redis as unknown as Redis;
+
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('reports "not enough data" before any learning', async () => {
+    const out = await handleBrainTool('brain_metrics', { instance_id: iid }, getConn, noopApiFetch);
+    expect(out).toContain('Brain Metrics');
+    expect(out).toContain('Not enough data');
+  });
+
+  it('always shows the published recall-lift moat number', async () => {
+    const out = await handleBrainTool('brain_metrics', { instance_id: iid }, getConn, noopApiFetch);
+    expect(out).toContain('+22.2 % Precision@1');
+  });
+
+  it('records born_at on first learn (first-wins NX semantics)', async () => {
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:a', outcome: 'success', what_worked: 'x', author: 'alice',
+    }, getConn, noopApiFetch);
+    const born1 = await redis.get(`cachly:stats:born_at:${iid}`);
+    expect(born1).not.toBeNull();
+    // Second learn must NOT overwrite born_at
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:b', outcome: 'success', what_worked: 'y', author: 'bob',
+    }, getConn, noopApiFetch);
+    const born2 = await redis.get(`cachly:stats:born_at:${iid}`);
+    expect(born2).toBe(born1);
+  });
+
+  it('tracks cross-author reuse when one person recalls another\'s lesson', async () => {
+    // Alice stores a proven lesson, recalled once so it counts as "proven"
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:race', outcome: 'success',
+      what_worked: 'add mutex around xyzzy counter', author: 'alice',
+    }, getConn, noopApiFetch);
+    // Bob recalls it (twice → first recall marks proven, second counts reuse on a proven lesson)
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'xyzzy counter mutex', author: 'bob' }, getConn, noopApiFetch);
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'xyzzy counter mutex', author: 'bob' }, getConn, noopApiFetch);
+
+    const cross = await redis.get(`cachly:stats:cross_author_recalls:${iid}`);
+    expect(Number(cross)).toBeGreaterThanOrEqual(1);
+
+    const out = await handleBrainTool('brain_metrics', { instance_id: iid }, getConn, noopApiFetch);
+    expect(out).toContain('Team-knowledge-reuse');
+    expect(out).toContain('distinct reuse relationship');
+  });
+
+  it('does not count self-recall as cross-author reuse', async () => {
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:solo', outcome: 'success',
+      what_worked: 'fixed the wibble myself', author: 'alice',
+    }, getConn, noopApiFetch);
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'wibble', author: 'alice' }, getConn, noopApiFetch);
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'wibble', author: 'alice' }, getConn, noopApiFetch);
+    const cross = await redis.get(`cachly:stats:cross_author_recalls:${iid}`);
+    expect(Number(cross ?? 0)).toBe(0);
+  });
+
+  it('surfaces the team-reuse banner inline in smart_recall', async () => {
+    await handleBrainTool('learn_from_attempts', {
+      instance_id: iid, topic: 'fix:plimsoll', outcome: 'success',
+      what_worked: 'adjust the plimsoll threshold', author: 'carol',
+    }, getConn, noopApiFetch);
+    // First recall by dave marks it proven; second recall shows the reuse banner
+    await handleBrainTool('smart_recall', { instance_id: iid, query: 'plimsoll threshold', author: 'dave' }, getConn, noopApiFetch);
+    const out = await handleBrainTool('smart_recall', { instance_id: iid, query: 'plimsoll threshold', author: 'dave' }, getConn, noopApiFetch);
+    expect(out).toContain('Team knowledge reuse');
+  });
+});

package/src/__tests__/utils.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { EventEmitter } from 'node:events';
+import { safeJsonParse, withTimeout, normalizeGitPath, scanKeys } from '../utils.js';
+
+describe('safeJsonParse', () => {
+  it('parses valid JSON', () => {
+    expect(safeJsonParse('{"a":1}', {})).toEqual({ a: 1 });
+  });
+  it('returns fallback on null/empty/malformed', () => {
+    expect(safeJsonParse(null, 'fb')).toBe('fb');
+    expect(safeJsonParse('', 'fb')).toBe('fb');
+    expect(safeJsonParse('{not json', 'fb')).toBe('fb');
+  });
+});
+
+describe('withTimeout', () => {
+  it('resolves with the promise value when it settles in time', async () => {
+    const out = await withTimeout(Promise.resolve('ok'), 1000, 'fallback');
+    expect(out).toBe('ok');
+  });
+  it('resolves with fallback when the promise is too slow', async () => {
+    const slow = new Promise<string>((r) => setTimeout(() => r('late'), 100));
+    const out = await withTimeout(slow, 10, 'fallback');
+    expect(out).toBe('fallback');
+  });
+  it('resolves with fallback when the promise rejects', async () => {
+    const out = await withTimeout(Promise.reject(new Error('boom')), 1000, 'fallback');
+    expect(out).toBe('fallback');
+  });
+});
+
+describe('normalizeGitPath', () => {
+  it('passes a normal path through', () => {
+    expect(normalizeGitPath('src/auth/jwt.ts')).toBe('src/auth/jwt.ts');
+  });
+  it('resolves brace rename notation to the post-rename path', () => {
+    expect(normalizeGitPath('src/{old => new}/file.ts')).toBe('src/new/file.ts');
+  });
+  it('resolves bare rename notation', () => {
+    expect(normalizeGitPath('old/path.ts => new/path.ts')).toBe('new/path.ts');
+  });
+  it('collapses an empty rename segment cleanly', () => {
+    // dir/{ => sub}/f.ts → dir/sub/f.ts
+    expect(normalizeGitPath('dir/{ => sub}/f.ts')).toBe('dir/sub/f.ts');
+  });
+  it('trims whitespace', () => {
+    expect(normalizeGitPath('  src/x.ts  ')).toBe('src/x.ts');
+  });
+});
+
+// Minimal scan-capable mock
+class ScanMock {
+  constructor(private keys: string[], private opts: { hang?: boolean } = {}) {}
+  scanStream(_o: { match: string; count?: number }) {
+    const em = new EventEmitter();
+    if (this.opts.hang) return em; // never emits — exercises the timeout path
+    setImmediate(() => {
+      em.emit('data', this.keys);
+      em.emit('end');
+    });
+    return em;
+  }
+}
+
+describe('scanKeys', () => {
+  it('collects all matching keys', async () => {
+    const mock = new ScanMock(['a', 'b', 'c']);
+    const out = await scanKeys(mock, 'pattern:*');
+    expect(out).toEqual(['a', 'b', 'c']);
+  });
+  it('caps at max keys', async () => {
+    const mock = new ScanMock(['a', 'b', 'c', 'd', 'e']);
+    const out = await scanKeys(mock, 'pattern:*', { max: 3 });
+    expect(out).toHaveLength(3);
+  });
+  it('resolves with gathered keys on timeout instead of hanging', async () => {
+    const mock = new ScanMock([], { hang: true });
+    const out = await scanKeys(mock, 'pattern:*', { timeoutMs: 20 });
+    expect(out).toEqual([]);
+  });
+});

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.64';
 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.64';
 
 // 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);
 }