@cachly-dev/mcp-server 0.10.65 → 0.10.66

package/src/__tests__/namespace.test.ts

@@ -1,126 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { detectNamespace } from '../namespace.js';
-
-// ── Namespace Auto-Detection ───────────────────────────────────────────────
-
-describe('detectNamespace', () => {
-  // ── Code ────────────────────────────────────────────────────────────────────
-  describe('code detection', () => {
-    it.each([
-      ['python def',        'def process(data): return data * 2'],
-      ['js const arrow',    'const handler = () => response.send(200)'],
-      ['ts class',          'class UserService { constructor(private repo: Repo) {} }'],
-      ['import statement',  'import { useState } from "react"'],
-      ['shebang line',      '#!/usr/bin/env python3\nprint("hello")'],
-      ['go func',           'func main() { fmt.Println("hello") }'],
-      ['cpp include',       '#include <iostream>\nint main() { return 0; }'],
-      ['interface block',   'interface ICache { get(key: string): void; }'],
-      ['struct block',      'struct Config { host string }'],
-      ['async def',         'async def fetch_data(url: str) -> dict:'],
-      ['lambda',            'fn = lambda x: x * 2'],
-      ['package decl',      'package com.example.service;'],
-    ])('detects code: %s', (_, prompt) => {
-      expect(detectNamespace(prompt)).toBe('cachly:sem:code');
-    });
-  });
-
-  // ── Translation ─────────────────────────────────────────────────────────────
-  describe('translation detection', () => {
-    it.each([
-      ['translate',         'translate this paragraph to Spanish'],
-      ['übersetze',         'übersetze diesen Text bitte'],
-      ['auf deutsch',       'Schreib das auf deutsch'],
-      ['in english',        'Please write this in english'],
-      ['ins deutsche',      'Bitte übersetze ins Deutsche'],
-      ['traduce',           'traduce este texto al alemán'],
-      ['traduis',           'traduis ce texte en anglais'],
-      ['vertaal',           'vertaal dit naar het Nederlands'],
-    ])('detects translation: %s', (_, prompt) => {
-      expect(detectNamespace(prompt)).toBe('cachly:sem:translation');
-    });
-  });
-
-  // ── Summary ──────────────────────────────────────────────────────────────────
-  describe('summary detection', () => {
-    it.each([
-      ['summarize',         'summarize this article for me'],
-      ['summarise',         'summarise the key points'],
-      ['tl;dr',             'tl;dr of the following blog post:'],
-      ['tldr',              'tldr of this document'],
-      ['key points',        'what are the key points?'],
-      ['zusammenfass',      'fasse zusammen worum es geht'],
-      ['give me a brief',   'give me a brief overview'],
-      ['in a nutshell',     'explain machine learning in a nutshell'],
-      ['stichpunkte',       'Gib mir die wichtigsten Stichpunkte'],
-    ])('detects summary: %s', (_, prompt) => {
-      expect(detectNamespace(prompt)).toBe('cachly:sem:summary');
-    });
-  });
-
-  // ── Q&A ──────────────────────────────────────────────────────────────────────
-  describe('qa detection', () => {
-    it.each([
-      ['what is',           'what is the capital of France?'],
-      ['how does',          'how does photosynthesis work?'],
-      ['why is',            'why is the sky blue?'],
-      ['who invented',      'who invented the internet?'],
-      ['where is',          'where is Mount Everest located?'],
-      ['when was',          'when was the Eiffel Tower built?'],
-      ['can you',           'can you explain recursion?'],
-      ['is redis',          'is Redis single-threaded?'],
-      ['does postgres',     'does postgres support JSON natively?'],
-      ['wer ist',           'wer ist der aktuelle Bundeskanzler?'],
-      ['wie funktioniert',  'wie funktioniert ein JWT Token?'],
-      ['trailing ?',        'Redis vs Memcached?'],
-    ])('detects q&a: %s', (_, prompt) => {
-      expect(detectNamespace(prompt)).toBe('cachly:sem:qa');
-    });
-  });
-
-  // ── Creative ─────────────────────────────────────────────────────────────────
-  describe('creative fallback', () => {
-    it.each([
-      ['poem request',     'Write a short poem about autumn leaves'],
-      ['story request',    'Tell me a fantasy story about dragons'],
-      ['product copy',     'Generate a product description for running shoes'],
-      ['greeting',         'Good morning, how are you today'],
-      ['general task',     'Help me brainstorm names for my startup'],
-    ])('falls back to creative: %s', (_, prompt) => {
-      expect(detectNamespace(prompt)).toBe('cachly:sem:creative');
-    });
-  });
-
-  // ── Edge cases ────────────────────────────────────────────────────────────────
-  describe('edge cases', () => {
-    it('is case-insensitive', () => {
-      expect(detectNamespace('CONST x = 1')).toBe('cachly:sem:code');
-      expect(detectNamespace('TRANSLATE THIS')).toBe('cachly:sem:translation');
-      expect(detectNamespace('SUMMARIZE PLEASE')).toBe('cachly:sem:summary');
-      expect(detectNamespace('WHAT IS GRAVITY?')).toBe('cachly:sem:qa');
-    });
-
-    it('trims surrounding whitespace', () => {
-      expect(detectNamespace('   what is Redis?   ')).toBe('cachly:sem:qa');
-      expect(detectNamespace('  const x = 1  ')).toBe('cachly:sem:code');
-    });
-
-    it('code keyword takes priority over translation', () => {
-      // Both "translate" and "def" present – code wins (checked first)
-      expect(detectNamespace('translate this function: def foo(): pass')).toBe('cachly:sem:code');
-    });
-
-    it('code keyword takes priority over summary', () => {
-      expect(detectNamespace('summarize this class MyService { }'))
-        .toBe('cachly:sem:code');
-    });
-
-    it('handles empty string as creative', () => {
-      expect(detectNamespace('')).toBe('cachly:sem:creative');
-    });
-
-    it('a single ? at end is qa', () => {
-      expect(detectNamespace('Interesting concept?')).toBe('cachly:sem:qa');
-    });
-  });
-});
-

package/src/__tests__/rerank.test.ts

@@ -1,141 +0,0 @@
-/**
- * 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', review_level: 'senior', reviewed_by: 'x', endorsements: 99 });
-    const lo = qualityMultiplier({ outcome: 'failure', confidence: 0, recall_count: 0, severity: 'minor' });
-    expect(hi).toBeLessThanOrEqual(2.5);
-    expect(lo).toBeGreaterThanOrEqual(0.5);
-  });
-
-  it('boosts a human-reviewed lesson above an unreviewed equal', () => {
-    const base = { outcome: 'success', confidence: 0.8, recall_count: 3 } as const;
-    const unreviewed = qualityMultiplier({ ...base });
-    const peer = qualityMultiplier({ ...base, reviewed_by: 'alice', review_level: 'peer', endorsements: 1 });
-    const senior = qualityMultiplier({ ...base, reviewed_by: 'bob', review_level: 'senior', endorsements: 1 });
-    expect(peer).toBeGreaterThan(unreviewed);
-    expect(senior).toBeGreaterThan(peer);
-  });
-
-  it('rewards additional distinct endorsements but saturates', () => {
-    const base = { outcome: 'success', confidence: 0.8, recall_count: 3, reviewed_by: 'a', review_level: 'peer' } as const;
-    const one = qualityMultiplier({ ...base, endorsements: 1 });
-    const three = qualityMultiplier({ ...base, endorsements: 3 });
-    const fifty = qualityMultiplier({ ...base, endorsements: 50 });
-    expect(three).toBeGreaterThan(one);
-    expect(fifty).toBeGreaterThan(three);
-    expect(fifty - three).toBeLessThan(three - one + 0.1);
-  });
-});
-
-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);
-  });
-
-  it('beats a flat-file memory on the decisive metrics (right answer first)', async () => {
-    const r = await runBenchmark();
-    // Even when the flat-file memory is steelmanned (recency tiebreak), cachly puts
-    // the single best answer first more often — Precision@1 and MRR are what matter
-    // for an agent that acts on the top result.
-    expect(r.cachly.precisionAt1).toBeGreaterThanOrEqual(r.flatfile.precisionAt1 - 1e-9);
-    expect(r.cachly.mrr).toBeGreaterThanOrEqual(r.flatfile.mrr - 1e-9);
-    // The flat-file simulation is honest: it isn't trivially terrible.
-    expect(r.flatfile.mrr).toBeGreaterThan(0.5);
-  });
-});

package/src/__tests__/utils.test.ts

@@ -1,81 +0,0 @@
-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/auth.ts

@@ -1,46 +0,0 @@
-import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-
-export function jwtExpiryMs(token: string): number | null {
-  try {
-    const parts = token.split('.');
-    if (parts.length !== 3) return null;
-    const payload = JSON.parse(
-      Buffer.from(parts[1], 'base64url').toString('utf-8'),
-    ) as { exp?: number };
-    return payload.exp ? payload.exp * 1000 : null;
-  } catch {
-    return null;
-  }
-}
-
-export function checkJwt(jwt: string): void {
-  if (!jwt) {
-    throw new McpError(
-      ErrorCode.InvalidRequest,
-      'CACHLY_JWT env var not set.\n\nGet your token at https://cachly.dev/setup-ai and add it to your MCP config:\n  CACHLY_JWT=<your-token>',
-    );
-  }
-  const expMs = jwtExpiryMs(jwt);
-  if (expMs !== null && expMs < Date.now()) {
-    throw new McpError(
-      ErrorCode.InvalidRequest,
-      `CACHLY_JWT expired at ${new Date(expMs).toISOString()}.\n\nGet a fresh token at https://cachly.dev/setup-ai and update CACHLY_JWT in your MCP config.`,
-    );
-  }
-}
-
-export function handleApiError(status: number, detail: string): never {
-  if (status === 401) {
-    throw new McpError(
-      ErrorCode.InvalidRequest,
-      `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at https://cachly.dev/setup-ai`,
-    );
-  }
-  if (status === 403) {
-    throw new McpError(
-      ErrorCode.InvalidRequest,
-      `Access denied (403): ${detail}\n\nCheck that your CACHLY_JWT belongs to an account with access to this resource.`,
-    );
-  }
-  throw new McpError(ErrorCode.InternalError, `cachly API error ${status}: ${detail}`);
-}

package/src/bench/cachly-bench.ts

@@ -1,263 +0,0 @@
-/**
- * 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 {
-  /** Flat-file memory simulation: naive term-overlap, no IDF, no quality signal. */
-  flatfile: BenchMetrics;
-  baseline: BenchMetrics;
-  cachly: BenchMetrics;
-  /** Relative lift of cachly vs the BM25 baseline. */
-  lift: BenchMetrics;
-  /** Relative lift of cachly vs a flat-file memory (the head-to-head that matters). */
-  liftVsFlatfile: BenchMetrics;
-  queryCount: number;
-  corpusSize: number;
-}
-
-/**
- * Simulates how a flat-file memory (e.g. an LLM reading a `/memories` directory)
- * actually surfaces knowledge: it has NO ranking engine. Practical retrieval is
- * naive lexical overlap — count how many distinct query terms appear in the file's
- * text — with NO inverse-document-frequency, NO length normalization, and crucially
- * NO quality signal (a proven fix and a failed attempt are just text). Ties break by
- * recency, mimicking "most recently edited note first". This is a fair, and honestly
- * weaker, stand-in for "Claude reads its own memory files".
- */
-function flatFileRank(lessons: BenchLesson[], query: string): string[] {
-  const qTerms = new Set(
-    query.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/).filter(t => t.length >= 3),
-  );
-  const scored = lessons.map(l => {
-    const blob = [l.topic, l.what_worked, l.what_failed ?? '', l.context ?? '', (l.tags ?? []).join(' ')]
-      .join(' ').toLowerCase();
-    let overlap = 0;
-    for (const t of qTerms) if (blob.includes(t)) overlap++;
-    const recency = l.ts ? new Date(l.ts).getTime() : 0;
-    return { topic: l.topic, overlap, recency };
-  });
-  return scored
-    .filter(s => s.overlap > 0)
-    .sort((a, b) => (b.overlap - a.overlap) || (b.recency - a.recency))
-    .map(s => s.topic);
-}
-
-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 flatfileRows: BenchMetrics[] = [];
-  const baselineRows: BenchMetrics[] = [];
-  const cachlyRows: BenchMetrics[] = [];
-
-  for (const q of BENCH_QUERIES) {
-    const relevant = new Set(q.relevant);
-
-    // BM25 baseline + cachly share the same candidate set — isolates ranking quality.
-    const matches = await keywordSearch(redis as never, [`${LESSON_PREFIX}*`], q.query, 10);
-    const baselineRanked = matches.map(matchTopic);
-    const cachlyRanked = rerankByQuality(matches).map(matchTopic);
-
-    // Flat-file memory sees the whole corpus but has no ranking engine.
-    const flatfileRanked = flatFileRank(BENCH_LESSONS, q.query);
-
-    flatfileRows.push(scoreRanking(flatfileRanked, relevant));
-    baselineRows.push(scoreRanking(baselineRanked, relevant));
-    cachlyRows.push(scoreRanking(cachlyRanked, relevant));
-  }
-
-  const flatfile = aggregate(flatfileRows);
-  const baseline = aggregate(baselineRows);
-  const cachly = aggregate(cachlyRows);
-  const liftOf = (b: number, c: number) => (b === 0 ? (c > 0 ? 1 : 0) : (c - b) / b);
-  const liftBetween = (from: BenchMetrics): BenchMetrics => ({
-    precisionAt1: liftOf(from.precisionAt1, cachly.precisionAt1),
-    precisionAt3: liftOf(from.precisionAt3, cachly.precisionAt3),
-    recallAt3: liftOf(from.recallAt3, cachly.recallAt3),
-    mrr: liftOf(from.mrr, cachly.mrr),
-    ndcgAt5: liftOf(from.ndcgAt5, cachly.ndcgAt5),
-  });
-
-  return {
-    flatfile, baseline, cachly,
-    lift: liftBetween(baseline),
-    liftVsFlatfile: liftBetween(flatfile),
-    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, f: number, b: number, c: number, lf: number) =>
-    `  ${label.padEnd(12)} ${pct(f).padStart(8)} ${pct(b).padStart(8)} ${pct(c).padStart(8)}   ${signedPct(lf).padStart(8)}`;
-  return [
-    '',
-    '🧠  Cachly-Bench — recall quality head-to-head',
-    '──────────────────────────────────────────────────────────────────────────',
-    `  corpus: ${r.corpusSize} lessons · queries: ${r.queryCount}`,
-    '  flat-file = naive term-overlap, no quality signal (≈ LLM reading memory files)',
-    '  baseline  = raw BM25+ keyword ranking',
-    '  cachly    = BM25+ followed by quality-aware reranking',
-    '',
-    `  ${'metric'.padEnd(12)} ${'flatfile'.padStart(8)} ${'baseline'.padStart(8)} ${'cachly'.padStart(8)}   ${'vs flat'.padStart(8)}`,
-    row('Precision@1', r.flatfile.precisionAt1, r.baseline.precisionAt1, r.cachly.precisionAt1, r.liftVsFlatfile.precisionAt1),
-    row('Precision@3', r.flatfile.precisionAt3, r.baseline.precisionAt3, r.cachly.precisionAt3, r.liftVsFlatfile.precisionAt3),
-    row('Recall@3', r.flatfile.recallAt3, r.baseline.recallAt3, r.cachly.recallAt3, r.liftVsFlatfile.recallAt3),
-    row('MRR', r.flatfile.mrr, r.baseline.mrr, r.cachly.mrr, r.liftVsFlatfile.mrr),
-    row('nDCG@5', r.flatfile.ndcgAt5, r.baseline.ndcgAt5, r.cachly.ndcgAt5, r.liftVsFlatfile.ndcgAt5),
-    '──────────────────────────────────────────────────────────────────────────',
-    `  vs BM25 baseline : MRR ${signedPct(r.lift.mrr)} · Precision@1 ${signedPct(r.lift.precisionAt1)}`,
-    `  vs flat-file mem : MRR ${signedPct(r.liftVsFlatfile.mrr)} · Precision@1 ${signedPct(r.liftVsFlatfile.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);
-  });
-}