@cachly-dev/mcp-server 0.10.62 → 0.10.65

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.65",
   "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.65",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.10.62",
+      "version": "0.10.65",
       "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__/rerank.test.ts

@@ -127,4 +127,15 @@ describe('Cachly-Bench regression guard', () => {
     // 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

@@ -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/bench/cachly-bench.ts

@@ -102,14 +102,45 @@ export interface BenchMetrics {
 }
 
 export interface BenchResult {
+  /** Flat-file memory simulation: naive term-overlap, no IDF, no quality signal. */
+  flatfile: BenchMetrics;
   baseline: BenchMetrics;
   cachly: BenchMetrics;
-  /** Relative lift per metric, e.g. { mrr: 0.23 } = +23%. */
+  /** 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 {
@@ -139,34 +170,45 @@ function scoreRanking(ranked: string[], relevant: Set<string>): BenchMetrics {
 /** 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);
 
-    // Same candidate set for both rankers — isolates the ranking contribution.
+    // 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 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),
-  };
+  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 { baseline, cachly, lift, queryCount: BENCH_QUERIES.length, corpusSize: BENCH_LESSONS.length };
+  return {
+    flatfile, baseline, cachly,
+    lift: liftBetween(baseline),
+    liftVsFlatfile: liftBetween(flatfile),
+    queryCount: BENCH_QUERIES.length,
+    corpusSize: BENCH_LESSONS.length,
+  };
 }
 
 // ── Reporting ──────────────────────────────────────────────────────────────────
@@ -174,22 +216,26 @@ 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)}`;
+  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 (BM25 baseline vs quality-aware rerank)',
-    '────────────────────────────────────────────────────────────────────────',
+    '🧠  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(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)}`,
+    `  ${'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');
 }