@cachly-dev/mcp-server 0.10.48 → 0.10.50

package/packages/telegram-notify/telegram_notify/emojis.json

@@ -0,0 +1,22 @@
+{
+  "tool_call":             "🔧",
+  "tool_error":            "🔴",
+  "cache_hit":             "⚡",
+  "cache_miss":            "💭",
+  "auth_ok":               "🔑",
+  "auth_fail":             "🚫",
+  "startup":               "🚀",
+  "waitlist_signup":       "📬",
+  "parse_file":            "📄",
+  "parse_text":            "📝",
+  "parse_url":             "🔗",
+  "trip_created":          "🗺️",
+  "trip_deleted":          "🗑️",
+  "error":                 "🔴",
+  "stripe_payment":        "💳",
+  "stripe_checkout":       "🛒",
+  "new_user":              "🆕",
+  "pdf_export":            "📑",
+  "trip_search":           "🔍",
+  "default":               "🔔"
+}

package/scripts/generate-icons.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Converts SVG icon assets to PNG for Expo.
+ * Run: node scripts/generate-icons.js
+ * Requires: npm install -g sharp-cli  OR  npx sharp-cli
+ */
+const { execSync } = require('child_process');
+const path = require('path');
+
+const frontend = path.join(__dirname, '..', 'apps', 'travel-chaos-organizer', 'frontend');
+
+const conversions = [
+  { input: 'assets/icon.svg', output: 'assets/icon.png', width: 1024, height: 1024 },
+  { input: 'assets/adaptive-icon.svg', output: 'assets/adaptive-icon.png', width: 1024, height: 1024 },
+  { input: 'assets/icon.svg', output: 'assets/splash.png', width: 1284, height: 2778 },
+  { input: 'assets/icon.svg', output: 'assets/favicon.png', width: 32, height: 32 },
+];
+
+for (const { input, output, width, height } of conversions) {
+  const src = path.join(frontend, input);
+  const dst = path.join(frontend, output);
+  try {
+    execSync(`npx sharp-cli --input "${src}" --output "${dst}" resize ${width} ${height}`, { stdio: 'inherit' });
+    console.log(`✓ ${output}`);
+  } catch {
+    console.error(`✗ ${output} — install sharp-cli: npm i -g sharp-cli`);
+  }
+}

package/smithery.yaml

@@ -7,19 +7,15 @@ description: >
   BM25+ search in 11 languages. 80 MCP tools. Free tier. GDPR. German servers.
   Zero-config: sign in once via browser, auto-provisions your Brain instance.
 
-# Streamable HTTP — hosted on our infrastructure (mcp.cachly.dev).
-# Multi-tenant: per-request CACHLY_JWT + instance ID resolved from
-# Authorization header + X-Cachly-Instance-Id, or Smithery ?config= param.
 startCommand:
-  type: http
-  url: https://mcp.cachly.dev/mcp
+  type: stdio
   configSchema:
     type: object
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key"
-        description: "Get your free API key at https://cachly.dev/setup-ai (no credit card)."
+        title: "API Key (optional — sign in via browser on first use)"
+        description: "Leave blank for zero-config: on your first tool call the server opens a browser sign-in (OAuth Device Flow) and auto-provisions your Brain instance. Or pre-fill with your API key from cachly.dev/setup-ai."
         examples:
           - "cky_live_abc123..."
       CACHLY_BRAIN_INSTANCE_ID:
@@ -29,4 +25,21 @@ startCommand:
         pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
         examples:
           - "9d4077aa-bfa2-468b-89cd-0a8d8f3ec483"
-
+      CACHLY_API_URL:
+        type: string
+        title: "API URL (optional)"
+        description: "Leave blank unless you self-host Cachly."
+        default: "https://api.cachly.dev"
+    required: []
+  commandFunction: |-
+    (config) => ({
+      command: "npx",
+      args: ["-y", "@cachly-dev/mcp-server@latest"],
+      env: Object.fromEntries(
+        Object.entries({
+          CACHLY_JWT: config.CACHLY_JWT,
+          CACHLY_BRAIN_INSTANCE_ID: config.CACHLY_BRAIN_INSTANCE_ID,
+          CACHLY_API_URL: config.CACHLY_API_URL ?? "https://api.cachly.dev",
+        }).filter(([, v]) => v != null && v !== "")
+      )
+    })

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

@@ -17,6 +17,7 @@ import { EventEmitter } from 'node:events';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '../ckg.js';
 import { EMBED_PROVIDER, hasEmbedProvider, embedProviderHint, embedConfig, setEmbedJwt } from '../embeddings.js';
 import { keywordSearch } from '../search.js';
+import { handleBrainTool } from '../handlers/brain.js';
 import type { Redis } from 'ioredis';
 
 // ── In-memory Redis mock ──────────────────────────────────────────────────────
@@ -67,6 +68,21 @@ class MockRedis {
     return [...(this.sets.get(key) ?? [])];
   }
 
+  async mget(...keys: string[]): Promise<(string | null)[]> {
+    return keys.map(k => this.store.get(k) ?? null);
+  }
+
+  async exists(key: string): Promise<number> {
+    return this.store.has(key) ? 1 : 0;
+  }
+
+  async incrbyfloat(key: string, increment: number): Promise<string> {
+    const cur = parseFloat(this.store.get(key) ?? '0');
+    const next = cur + increment;
+    this.store.set(key, String(next));
+    return String(next);
+  }
+
   /** Simplified scanStream: returns all matching keys in a single 'data' event. */
   scanStream(opts: { match: string; count?: number }): EventEmitter {
     const emitter = new EventEmitter();
@@ -872,3 +888,161 @@ describe('Brain Flow: advanced scenarios', () => {
     });
   });
 });
+
+// ── New feature coverage (0.10.41 / 0.10.42) ─────────────────────────────────
+// Trust badges, Proven Laws crystallization, and focus-less predictive warning.
+// These exercise the REAL handleBrainTool code path with the MockRedis.
+
+const noopApiFetch = (async () => null) as unknown as Parameters<typeof handleBrainTool>[3];
+
+/** Seed a best-solution lesson with an explicit recall_count / authors / pinned. */
+async function seedLesson(
+  redis: MockRedis,
+  topic: string,
+  opts: {
+    outcome?: 'success' | 'failure' | 'partial';
+    what_worked?: string;
+    what_failed?: string;
+    recall_count?: number;
+    severity?: 'critical' | 'major' | 'minor';
+    pinned?: boolean;
+    author?: string;
+    tags?: string[];
+  } = {},
+): Promise<void> {
+  const ts = new Date().toISOString();
+  const obj = {
+    topic,
+    outcome: opts.outcome ?? 'success',
+    what_worked: opts.what_worked ?? `solution for ${topic}`,
+    what_failed: opts.what_failed,
+    severity: opts.severity ?? 'minor',
+    recall_count: opts.recall_count ?? 0,
+    ts,
+    verified_at: ts,
+    confidence: 1.0,
+    tags: opts.tags ?? [],
+    ...(opts.pinned ? { pinned: true } : {}),
+    ...(opts.author ? { author: opts.author } : {}),
+  };
+  await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(obj));
+}
+
+describe('Trust badges (recall_best_solution)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('shows "Battle-tested" when recall_count crosses 10', async () => {
+    await seedLesson(redis, 'redis:pool', { recall_count: 9, what_worked: 'set max_retries=3' });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'redis:pool' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Battle-tested');
+    expect(out).toContain('recalled 10×');
+  });
+
+  it('shows "Proven" when recall_count is between 5 and 9', async () => {
+    await seedLesson(redis, 'api:auth', { recall_count: 4 });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'api:auth' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven');
+    expect(out).toContain('recalled 5×');
+    expect(out).not.toContain('Battle-tested');
+  });
+
+  it('shows no trust badge for a fresh low-recall lesson', async () => {
+    await seedLesson(redis, 'misc:thing', { recall_count: 0 });
+    const out = (await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'misc:thing' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Battle-tested');
+    expect(out).not.toContain('Proven —');
+    expect(out).not.toContain('Team-verified');
+  });
+
+  it('increments recall_count and persists it', async () => {
+    await seedLesson(redis, 'deploy:x', { recall_count: 2 });
+    await handleBrainTool('recall_best_solution', { instance_id: 'i1', topic: 'deploy:x' }, getConn, noopApiFetch);
+    const stored = JSON.parse((await redis.get('cachly:lesson:best:deploy:x'))!);
+    expect(stored.recall_count).toBe(3);
+  });
+});
+
+describe('Proven Laws crystallization (session_start)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(async () => {
+    redis = new MockRedis();
+    // Provide a last session so session_start does not attempt git reconstruction.
+    await redis.set('cachly:session:last', JSON.stringify({ summary: 'prior work', ts: new Date().toISOString(), files_changed: [] }));
+  });
+
+  it('surfaces lessons recalled >= 5 in the Proven Laws section', async () => {
+    await seedLesson(redis, 'infra:k3s', { recall_count: 7, what_worked: 'add WireGuard IP to TLS-SAN' });
+    await seedLesson(redis, 'random:note', { recall_count: 1 });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven Laws');
+    expect(out).toContain('infra:k3s');
+    expect(out).toContain('recalled 7×');
+  });
+
+  it('surfaces an explicitly pinned lesson even with low recall', async () => {
+    await seedLesson(redis, 'team:convention', { recall_count: 0, pinned: true, what_worked: 'always snake_case handlers' });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('Proven Laws');
+    expect(out).toContain('team:convention');
+    expect(out).toContain('pinned');
+  });
+
+  it('omits the Proven Laws section when nothing qualifies', async () => {
+    await seedLesson(redis, 'small:thing', { recall_count: 1 });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Proven Laws');
+  });
+
+  it('does not crystallize failure lessons', async () => {
+    await seedLesson(redis, 'broken:flow', { recall_count: 9, outcome: 'failure', what_failed: 'never works' });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('Proven Laws');
+  });
+});
+
+describe('Predictive pre-warning without explicit focus (session_start)', () => {
+  let redis: MockRedis;
+  const getConn = async () => redis as unknown as Redis;
+  beforeEach(() => { redis = new MockRedis(); });
+
+  it('derives danger area from last session files and warns', async () => {
+    // Last session touched payment files → likely to continue there.
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'worked on payment integration',
+      ts: new Date().toISOString(),
+      files_changed: ['api/payment/stripe_webhook.go'],
+    }));
+    // A known failure in the payment area.
+    await seedLesson(redis, 'payment:webhook', { outcome: 'failure', what_failed: 'missed idempotency key → double charge', tags: ['payment'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).toContain('PRE-WARNING');
+    expect(out).toContain('payment:webhook');
+  });
+
+  it('does not warn when last-session area has no known failures', async () => {
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'wrote docs',
+      ts: new Date().toISOString(),
+      files_changed: ['docs/readme.md'],
+    }));
+    await seedLesson(redis, 'payment:webhook', { outcome: 'failure', what_failed: 'x', tags: ['payment'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('PRE-WARNING');
+  });
+
+  it('filters path noise so common segments do not trigger false matches', async () => {
+    // Last session only touched generic noise paths (src/lib/index).
+    await redis.set('cachly:session:last', JSON.stringify({
+      summary: 'refactor',
+      ts: new Date().toISOString(),
+      files_changed: ['src/lib/index.ts'],
+    }));
+    // A failure tagged 'src' — should NOT match because 'src' is noise.
+    await seedLesson(redis, 'src:thing', { outcome: 'failure', what_failed: 'noise', tags: ['src'] });
+    const out = (await handleBrainTool('session_start', { instance_id: 'i1' }, getConn, noopApiFetch))!;
+    expect(out).not.toContain('PRE-WARNING');
+  });
+});

package/src/__tests__/handlers-unit.test.ts

@@ -334,8 +334,7 @@ describe('handleRoadmapTool', () => {
       // Add and complete one item
       const addResult = await handleRoadmapTool('roadmap_add', { instance_id: INSTANCE, title: 'Finished task', priority: 'low' }, getConnection, apiFetch);
       const idMatch = addResult!.match(/`(rm_[a-z0-9_]+)`/);
-      if (!idMatch) throw new Error('expected roadmap id in add result');
-      const id = idMatch[1];
+      const id = idMatch![1];
       await handleRoadmapTool('roadmap_update', { instance_id: INSTANCE, id, status: 'done' }, getConnection, apiFetch);
 
       const result = await handleRoadmapTool('roadmap_list', { instance_id: INSTANCE, status: 'done' }, getConnection, apiFetch);

package/src/__tests__/rerank.test.ts

@@ -0,0 +1,111 @@
+/**
+ * Tests for quality-aware reranking and the Cachly-Bench regression guard.
+ */
+import { describe, it, expect } from 'vitest';
+import { qualityMultiplier, extractLessonQuality, rerankByQuality, type LessonQuality } from '../rerank.js';
+import type { KeywordMatch } from '../search.js';
+import { runBenchmark } from '../bench/cachly-bench.js';
+
+const lessonMatch = (topic: string, score: number, lesson: Partial<LessonQuality> & Record<string, unknown>): KeywordMatch => ({
+  key: `cachly:lesson:best:${topic}`,
+  content: JSON.stringify(lesson),
+  score,
+  matchedWords: ['x'],
+});
+
+describe('qualityMultiplier', () => {
+  it('returns neutral 1.0 for documents with no quality signal', () => {
+    expect(qualityMultiplier(null)).toBe(1.0);
+    expect(qualityMultiplier({})).toBe(1.0);
+  });
+
+  it('ranks a proven success above a fresh failure', () => {
+    const success = qualityMultiplier({ outcome: 'success', confidence: 0.95, recall_count: 12 });
+    const failure = qualityMultiplier({ outcome: 'failure', confidence: 0.3, recall_count: 0 });
+    expect(success).toBeGreaterThan(failure);
+  });
+
+  it('rewards proven-ness (recall_count) but saturates', () => {
+    const never = qualityMultiplier({ outcome: 'success', confidence: 0.8, recall_count: 0 });
+    const some = qualityMultiplier({ outcome: 'success', confidence: 0.8, recall_count: 5 });
+    const many = qualityMultiplier({ outcome: 'success', confidence: 0.8, recall_count: 500 });
+    expect(some).toBeGreaterThan(never);
+    expect(many).toBeGreaterThan(some);
+    expect(many - some).toBeLessThan(some - never + 0.2); // diminishing returns
+  });
+
+  it('clamps within [0.5, 2.5]', () => {
+    const hi = qualityMultiplier({ outcome: 'success', confidence: 1, recall_count: 100000, severity: 'critical' });
+    const lo = qualityMultiplier({ outcome: 'failure', confidence: 0, recall_count: 0, severity: 'minor' });
+    expect(hi).toBeLessThanOrEqual(2.5);
+    expect(lo).toBeGreaterThanOrEqual(0.5);
+  });
+});
+
+describe('extractLessonQuality', () => {
+  it('parses lesson JSON for lesson keys', () => {
+    const q = extractLessonQuality({ key: 'cachly:lesson:best:foo', content: '{"outcome":"success"}' });
+    expect(q?.outcome).toBe('success');
+  });
+  it('returns null for non-lesson keys (e.g. context)', () => {
+    expect(extractLessonQuality({ key: 'cachly:ctx:custom:foo', content: 'plain text' })).toBeNull();
+  });
+  it('returns null for corrupt lesson JSON', () => {
+    expect(extractLessonQuality({ key: 'cachly:lesson:best:foo', content: '{not json' })).toBeNull();
+  });
+});
+
+describe('rerankByQuality', () => {
+  it('promotes a proven success over a higher-BM25 failure distractor', () => {
+    const matches: KeywordMatch[] = [
+      lessonMatch('symptom-failure', 10, { outcome: 'failure', confidence: 0.2, recall_count: 0 }),
+      lessonMatch('proven-success', 8, { outcome: 'success', confidence: 0.95, recall_count: 12 }),
+    ];
+    const ranked = rerankByQuality(matches);
+    expect(ranked[0].key).toBe('cachly:lesson:best:proven-success');
+  });
+
+  it('keeps a strong text match competitive (does not bury it on quality alone)', () => {
+    const matches: KeywordMatch[] = [
+      lessonMatch('weak-but-perfect', 1, { outcome: 'success', confidence: 1, recall_count: 100 }),
+      lessonMatch('strong-text', 100, { outcome: 'partial', confidence: 0.6, recall_count: 0 }),
+    ];
+    const ranked = rerankByQuality(matches);
+    expect(ranked[0].key).toBe('cachly:lesson:best:strong-text');
+  });
+
+  it('is stable and returns every input', () => {
+    const matches: KeywordMatch[] = [
+      lessonMatch('a', 5, { outcome: 'success' }),
+      lessonMatch('b', 5, { outcome: 'success' }),
+    ];
+    const ranked = rerankByQuality(matches);
+    expect(ranked).toHaveLength(2);
+  });
+
+  it('handles empty input', () => {
+    expect(rerankByQuality([])).toEqual([]);
+  });
+});
+
+describe('Cachly-Bench regression guard', () => {
+  it('quality rerank never regresses headline metrics vs baseline', async () => {
+    const r = await runBenchmark();
+    // Cachly must be >= baseline on the headline metrics (the moat must not hurt).
+    expect(r.cachly.mrr).toBeGreaterThanOrEqual(r.baseline.mrr - 1e-9);
+    expect(r.cachly.precisionAt1).toBeGreaterThanOrEqual(r.baseline.precisionAt1 - 1e-9);
+    expect(r.cachly.ndcgAt5).toBeGreaterThanOrEqual(r.baseline.ndcgAt5 - 1e-9);
+  });
+
+  it('demonstrates a positive lift on Precision@1 and MRR (the proof)', async () => {
+    const r = await runBenchmark();
+    expect(r.lift.precisionAt1).toBeGreaterThan(0);
+    expect(r.lift.mrr).toBeGreaterThan(0);
+  });
+
+  it('baseline is already strong (corpus is not rigged to make rerank look good)', async () => {
+    const r = await runBenchmark();
+    // A fair benchmark: BM25 alone already gets most queries right.
+    expect(r.baseline.mrr).toBeGreaterThan(0.7);
+  });
+});

package/src/bench/cachly-bench.ts

@@ -0,0 +1,217 @@
+/**
+ * Cachly-Bench — the moat proof.
+ *
+ * Measures recall quality on a fixed, labeled corpus and compares two rankers
+ * over the *same* BM25 candidate set, so the comparison isolates ranking quality:
+ *
+ *   baseline  — raw BM25+ keyword ranking (what a text-only / flat-file memory does)
+ *   cachly    — BM25+ followed by quality-aware reranking (rerank.ts)
+ *
+ * It reports standard IR metrics (Precision@k, Recall@k, MRR, nDCG@k) and the
+ * relative lift. The corpus (fixtures.ts) is fair: gold answers are the lessons
+ * that actually solve each problem, while text-similar failed attempts act as
+ * distractors — exactly where ranking by quality should pull ahead.
+ *
+ * Run:  npm run bench        (pretty report)
+ *       npm run bench -- --json   (machine-readable)
+ */
+
+import { EventEmitter } from 'node:events';
+import { keywordSearch, type KeywordMatch } from '../search.js';
+import { rerankByQuality } from '../rerank.js';
+import { BENCH_LESSONS, BENCH_QUERIES, type BenchLesson } from './fixtures.js';
+
+const LESSON_PREFIX = 'cachly:lesson:best:';
+
+// ── Minimal in-memory Redis (only what keywordSearch needs) ────────────────────
+class MiniRedis {
+  private store = new Map<string, string>();
+
+  set(key: string, value: string): void { this.store.set(key, value); }
+  async get(key: string): Promise<string | null> { return this.store.get(key) ?? null; }
+
+  scanStream(opts: { match: string; count?: number }): EventEmitter {
+    const emitter = new EventEmitter();
+    const pattern = '^' + opts.match.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$';
+    const regex = new RegExp(pattern);
+    const matches = [...this.store.keys()].filter(k => regex.test(k));
+    setImmediate(() => { emitter.emit('data', matches); emitter.emit('end'); });
+    return emitter;
+  }
+
+  pipeline() {
+    const cmds: string[] = [];
+    const store = this.store;
+    return {
+      get(key: string) { cmds.push(key); return this; },
+      async exec(): Promise<Array<[null, string | null]>> {
+        return cmds.map(k => [null, store.get(k) ?? null] as [null, string | null]);
+      },
+    };
+  }
+}
+
+function indexCorpus(lessons: BenchLesson[]): MiniRedis {
+  const redis = new MiniRedis();
+  for (const l of lessons) {
+    redis.set(`${LESSON_PREFIX}${l.topic}`, JSON.stringify(l));
+  }
+  return redis;
+}
+
+// ── IR metrics ─────────────────────────────────────────────────────────────────
+function precisionAtK(ranked: string[], relevant: Set<string>, k: number): number {
+  const top = ranked.slice(0, k);
+  if (top.length === 0) return 0;
+  const hits = top.filter(t => relevant.has(t)).length;
+  return hits / Math.min(k, top.length);
+}
+
+function recallAtK(ranked: string[], relevant: Set<string>, k: number): number {
+  if (relevant.size === 0) return 0;
+  const top = ranked.slice(0, k);
+  const hits = top.filter(t => relevant.has(t)).length;
+  return hits / relevant.size;
+}
+
+function reciprocalRank(ranked: string[], relevant: Set<string>): number {
+  for (let i = 0; i < ranked.length; i++) {
+    if (relevant.has(ranked[i])) return 1 / (i + 1);
+  }
+  return 0;
+}
+
+function ndcgAtK(ranked: string[], relevant: Set<string>, k: number): number {
+  let dcg = 0;
+  for (let i = 0; i < Math.min(k, ranked.length); i++) {
+    if (relevant.has(ranked[i])) dcg += 1 / Math.log2(i + 2);
+  }
+  let idcg = 0;
+  for (let i = 0; i < Math.min(k, relevant.size); i++) {
+    idcg += 1 / Math.log2(i + 2);
+  }
+  return idcg === 0 ? 0 : dcg / idcg;
+}
+
+export interface BenchMetrics {
+  precisionAt1: number;
+  precisionAt3: number;
+  recallAt3: number;
+  mrr: number;
+  ndcgAt5: number;
+}
+
+export interface BenchResult {
+  baseline: BenchMetrics;
+  cachly: BenchMetrics;
+  /** Relative lift per metric, e.g. { mrr: 0.23 } = +23%. */
+  lift: BenchMetrics;
+  queryCount: number;
+  corpusSize: number;
+}
+
+const matchTopic = (m: KeywordMatch): string => m.key.replace(LESSON_PREFIX, '');
+
+function mean(xs: number[]): number {
+  return xs.length === 0 ? 0 : xs.reduce((a, b) => a + b, 0) / xs.length;
+}
+
+function aggregate(rows: BenchMetrics[]): BenchMetrics {
+  return {
+    precisionAt1: mean(rows.map(r => r.precisionAt1)),
+    precisionAt3: mean(rows.map(r => r.precisionAt3)),
+    recallAt3: mean(rows.map(r => r.recallAt3)),
+    mrr: mean(rows.map(r => r.mrr)),
+    ndcgAt5: mean(rows.map(r => r.ndcgAt5)),
+  };
+}
+
+function scoreRanking(ranked: string[], relevant: Set<string>): BenchMetrics {
+  return {
+    precisionAt1: precisionAtK(ranked, relevant, 1),
+    precisionAt3: precisionAtK(ranked, relevant, 3),
+    recallAt3: recallAtK(ranked, relevant, 3),
+    mrr: reciprocalRank(ranked, relevant),
+    ndcgAt5: ndcgAtK(ranked, relevant, 5),
+  };
+}
+
+/** Run the benchmark over the fixture corpus. Pure-ish: no network, no real Redis. */
+export async function runBenchmark(): Promise<BenchResult> {
+  const redis = indexCorpus(BENCH_LESSONS);
+  const baselineRows: BenchMetrics[] = [];
+  const cachlyRows: BenchMetrics[] = [];
+
+  for (const q of BENCH_QUERIES) {
+    const relevant = new Set(q.relevant);
+
+    // Same candidate set for both rankers — isolates the ranking contribution.
+    const matches = await keywordSearch(redis as never, [`${LESSON_PREFIX}*`], q.query, 10);
+
+    const baselineRanked = matches.map(matchTopic);
+    const cachlyRanked = rerankByQuality(matches).map(matchTopic);
+
+    baselineRows.push(scoreRanking(baselineRanked, relevant));
+    cachlyRows.push(scoreRanking(cachlyRanked, relevant));
+  }
+
+  const baseline = aggregate(baselineRows);
+  const cachly = aggregate(cachlyRows);
+  const liftOf = (b: number, c: number) => (b === 0 ? (c > 0 ? 1 : 0) : (c - b) / b);
+  const lift: BenchMetrics = {
+    precisionAt1: liftOf(baseline.precisionAt1, cachly.precisionAt1),
+    precisionAt3: liftOf(baseline.precisionAt3, cachly.precisionAt3),
+    recallAt3: liftOf(baseline.recallAt3, cachly.recallAt3),
+    mrr: liftOf(baseline.mrr, cachly.mrr),
+    ndcgAt5: liftOf(baseline.ndcgAt5, cachly.ndcgAt5),
+  };
+
+  return { baseline, cachly, lift, queryCount: BENCH_QUERIES.length, corpusSize: BENCH_LESSONS.length };
+}
+
+// ── Reporting ──────────────────────────────────────────────────────────────────
+const pct = (x: number) => `${(x * 100).toFixed(1)}%`;
+const signedPct = (x: number) => `${x >= 0 ? '+' : ''}${(x * 100).toFixed(1)}%`;
+
+export function formatReport(r: BenchResult): string {
+  const row = (label: string, b: number, c: number, l: number) =>
+    `  ${label.padEnd(14)} ${pct(b).padStart(8)}  →  ${pct(c).padStart(8)}   ${signedPct(l).padStart(8)}`;
+  return [
+    '',
+    '🧠  Cachly-Bench — recall quality (BM25 baseline vs quality-aware rerank)',
+    '────────────────────────────────────────────────────────────────────────',
+    `  corpus: ${r.corpusSize} lessons · queries: ${r.queryCount}`,
+    '',
+    `  ${'metric'.padEnd(14)} ${'baseline'.padStart(8)}     ${'cachly'.padStart(8)}      ${'lift'.padStart(8)}`,
+    row('Precision@1', r.baseline.precisionAt1, r.cachly.precisionAt1, r.lift.precisionAt1),
+    row('Precision@3', r.baseline.precisionAt3, r.cachly.precisionAt3, r.lift.precisionAt3),
+    row('Recall@3', r.baseline.recallAt3, r.cachly.recallAt3, r.lift.recallAt3),
+    row('MRR', r.baseline.mrr, r.cachly.mrr, r.lift.mrr),
+    row('nDCG@5', r.baseline.ndcgAt5, r.cachly.ndcgAt5, r.lift.ndcgAt5),
+    '────────────────────────────────────────────────────────────────────────',
+    `  Headline: MRR ${signedPct(r.lift.mrr)} · Precision@1 ${signedPct(r.lift.precisionAt1)}`,
+    '',
+  ].join('\n');
+}
+
+// ── CLI entry ───────────────────────────────────────────────────────────────────
+const isMain = (() => {
+  try {
+    return import.meta.url === `file://${process.argv[1]}`
+      || process.argv[1]?.endsWith('cachly-bench.ts')
+      || process.argv[1]?.endsWith('cachly-bench.js');
+  } catch { return false; }
+})();
+
+if (isMain) {
+  runBenchmark().then(result => {
+    if (process.argv.includes('--json')) {
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    } else {
+      process.stdout.write(formatReport(result));
+    }
+  }).catch(err => {
+    process.stderr.write(`bench failed: ${err instanceof Error ? err.stack : String(err)}\n`);
+    process.exit(1);
+  });
+}