@lotargo/memory_plugin 1.6.5 → 1.6.6

package/mcp-server/benchmarks/run_benchmarks.js

@@ -0,0 +1,366 @@
+import { writeFile, mkdir as mkdirAsync } from "node:fs/promises";
+import { rmSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { testDualLayerArchitecture } from "./test_dual_layer.js";
+import { runIngestionBenchmark } from "./stress_ingestion.js";
+import { evaluateSearchQualityComparison } from "./quality_evaluator.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPORT_PATH = join(__dirname, "..", "..", "dev_docs", "benchmark_results.md");
+const HISTORY_DIR = join(__dirname, "..", "..", "dev_docs", "benchmark_history");
+const PANEL_WIDTH = 58;
+
+function fmtCI(ci) {
+  if (!ci || !Array.isArray(ci) || ci.length < 2) return "—";
+  return `[${ci[0]}, ${ci[1]}]`;
+}
+
+function printRichPanel(title, subtitle = "") {
+  const line = "─".repeat(PANEL_WIDTH - 2);
+  console.log(`\x1b[36m╭${line}╮\x1b[0m`);
+  console.log(`\x1b[36m│\x1b[0m  \x1b[1m\x1b[37m${title.padEnd(PANEL_WIDTH - 6)}\x1b[0m  \x1b[36m│\x1b[0m`);
+  if (subtitle) {
+    console.log(`\x1b[36m│\x1b[0m  \x1b[90m${subtitle.padEnd(PANEL_WIDTH - 6)}\x1b[0m  \x1b[36m│\x1b[0m`);
+  }
+  console.log(`\x1b[36m╰${line}╯\x1b[0m`);
+}
+
+// Pure report renderer: takes the measurement results and returns the markdown.
+// Kept separate from the measurement run so it can be exercised against stored
+// benchmark_*.json artifacts without re-running ONNX ingestion.
+export function buildMarkdownReport({ ingestMetrics, qualityComp, totalTimeSec }) {
+  // Build markdown table for breakdown
+  const breakdownRows = qualityComp.breakdown
+    .map(
+      (b) => {
+        const target = `\`${b.target}\``;
+        const winnerCell = (rq, rv) => (rv === "MISSED" ? `${rq}` : `${rq}`);
+        return `| ${b.id} | ${target} | ${b.category} | ${b.bm25Rank} | ${b.vectorRank} | ${b.rrfRank} | ${b.rsfRank} | ${b.query} |`;
+      }
+    )
+    .join("\n");
+
+  // Compute dynamic analysis metrics
+  const totalQueries = qualityComp.breakdown.length;
+  const bm25Missed = qualityComp.breakdown.filter((b) => b.bm25Rank === "MISSED").length;
+  const rsfMissed = qualityComp.breakdown.filter((b) => b.rsfRank === "MISSED").length;
+  const rrfMissed = qualityComp.breakdown.filter((b) => b.rrfRank === "MISSED").length;
+  const vecMissed = qualityComp.breakdown.filter((b) => b.vectorRank === "MISSED").length;
+
+  // Per-category aggregate table rows
+  const catRows = qualityComp.categoryBreakdown
+    .map(
+      (c) =>
+        `| ${c.category} | ${c.n} | ${c.bm25.mrr} | ${c.vector.mrr} | ${c.rrf.mrr} | ${c.rsf.mrr} | ${(c.rrf.recall * 100).toFixed(1)}% | ${(c.rsf.recall * 100).toFixed(1)}% |`,
+    )
+    .join("\n");
+
+  // CI table rows
+  const ciRows = [
+    { mode: "bm25", agg: qualityComp.bm25, ci: qualityComp.bootstrap.bm25 },
+    { mode: "vector", agg: qualityComp.vector, ci: qualityComp.bootstrap.vector },
+    { mode: "rrf", agg: qualityComp.hybridRrf, ci: qualityComp.bootstrap.rrf },
+    { mode: "rsf", agg: qualityComp.hybridRsf, ci: qualityComp.bootstrap.rsf },
+  ]
+    .map((r) => `| ${r.mode} | ${r.agg.mrr} ${fmtCI(r.ci?.mrrCI)} | ${r.agg.recall} ${fmtCI(r.ci?.recallCI)} | ${r.agg.ndcg} ${fmtCI(r.ci?.ndcgCI)} |`)
+    .join("\n");
+
+  // Grid search rows
+  const rsfGridRows = qualityComp.rsfGrid
+    .map((g) => `| ${g.alpha} | ${g.mrr} | ${g.recall} | ${g.ndcg} | ${g.top1Wins} |`)
+    .join("\n");
+  const rrfGridRows = qualityComp.rrfGrid
+    .map((g) => `| ${g.k} | ${g.mrr} | ${g.recall} | ${g.ndcg} | ${g.top1Wins} |`)
+    .join("\n");
+
+  // Paired t-test rows
+  const tRows = [
+    { test: "RRF vs Vector", r: qualityComp.pairedTests.rrfVsVector },
+    { test: "RSF vs Vector", r: qualityComp.pairedTests.rsfVsVector },
+    { test: "RRF vs RSF", r: qualityComp.pairedTests.rrfVsRsf },
+  ]
+    .map((r) => `| ${r.test} | ${r.r.meanDiff} | ${r.r.t.toFixed(3)} | ${r.r.p} | ${r.r.sem} | ${r.r.n} |`)
+    .join("\n");
+
+  const winner = qualityComp.winner;
+  const winnerLabel =
+    winner === "hybrid_rsf" ? "RSF"
+    : winner === "hybrid_rrf" ? "RRF"
+    : winner === "vector" ? "Vector"
+    : "BM25";
+
+  const corpusSourceCount = ingestMetrics.docCount;
+  const networkDocCount = ingestMetrics.networkDocCount;
+  const localDocCount = ingestMetrics.localDocCount;
+  const memBaselineLabel = ingestMetrics.ramBaseline || "pre-loop";
+
+  // 4. Generate Comprehensive Markdown Report
+  const markdownReport = `# memory_plugin Local Hybrid RAG Rigorous Benchmark Report
+
+**Generated At**: ${new Date().toISOString()}  
+**Total Benchmark Duration**: ${totalTimeSec} seconds  
+**Embedding Engine**: \`Xenova/multilingual-e5-small\` (ONNX Quantized 384-d vectors, FULL CPU Inference Enabled)  
+**Corpus**: ${corpusSourceCount} Documents (${networkDocCount} fetched from GitHub, ${localDocCount} local fallback)  
+**Match Policy**: Strictly on \`expectedDocIds\` derived from corpus source-id (NOT substring match)  
+**Statistical Inference**: Paired-t (reciprocal rank) & 1000-iteration bootstrap 95% percentile CI
+
+---
+
+## 1. Dual-Layer Architectural Isolation (Notebook Facts vs RAG Docs)
+
+| Layer / Component | Test Status | Empirical Verification |
+|---|---|---|
+| **Layer 1: Notebook Store** | [OK] PASSED | 100% precision instant recall of user identity/preferences without vector loss |
+| **Layer 2: RAG Knowledge Base** | [OK] PASSED | Dynamic multi-tier chunking, hybrid BM25 + Vector RSF/RRF scoring, GraphRAG symbols |
+| **Architectural Isolation** | [OK] PASSED | Zero crosstalk between persistent Notebook facts and RAG SQLite index |
+
+---
+
+## 2. Mass Ingestion & Real ONNX Embedding Generation Speed
+
+| Metric | Real Empirical Value | Description |
+|---|---|---|
+| **Total Ingested Documents** | **${ingestMetrics.docCount} docs** | Real markdown, code, licenses from GitHub |
+| **Total Medium Sections** | **${ingestMetrics.totalSections} sections** | Medium hierarchy level (500–1000 tokens) |
+| **Total Micro-Chunks** | **${ingestMetrics.totalMicroChunks} chunks** | Small micro-chunk level (100–250 tokens) |
+| **Total ONNX Vectors Computed** | **${ingestMetrics.totalMicroChunks} vectors** | 384-dimensional Float32Array dense vectors |
+| **Total Ingestion Duration** | **${ingestMetrics.durationSec} s** | Including ONNX model inference & SQLite transactions |
+| **Ingestion Throughput** | **${ingestMetrics.docsPerSec} docs/sec** | Real end-to-end ingestion throughput |
+| **Vector Calculation Speed** | **${ingestMetrics.chunksPerSec} vectors/sec** | ONNX CPU inference speed |
+| **SQLite Index Size** | **${ingestMetrics.dbSizeMB} MB** | DB containing FTS5, micro-chunks, and Float32 vectors |
+| **Blob Storage Footprint** | **${ingestMetrics.blobSizeMB} MB** | Content-addressable SHA-256 compressed store |
+| **RAM Memory Footprint (pre-GC Δ, ${memBaselineLabel})** | **${ingestMetrics.ramUsageMB} MB** | heapUsed + external delta, ingestion-only (ONNX model load excluded). Upper bound incl. transient garbage. Negative Δ = loop reclaimed more warmup garbage than it allocated. |
+| **RAM Memory Footprint (post-GC settled Δ)** | **${ingestMetrics.settledRamUsageMB ?? "—"} MB** | After forced GC; persistent footprint retained by ingestion (sqlite cache, etc.) |
+| **RAM Memory Peak (max Δ during loop)** | **${ingestMetrics.peakRamUsageMB ?? "—"} MB** | Best-effort peak; note: synchronous ONNX inference blocks the event loop, so interval polling understates true peak. See §9. |
+
+> *ONNX native weights are owned by \`onnxruntime-node\` and not visible to \`heapUsed + external\`. To measure the one-time model weight load (≈90 MB for \`multilingual-e5-small\` quantized), use an external profiler (e.g. \`process-explorer\`) on the Node process.*
+| **RAM Memory Peak (max Δ during loop)** | **${ingestMetrics.peakRamUsageMB ?? "—"} MB** | Best-effort peak; note: synchronous ONNX inference blocks the event loop, so interval polling understates true peak. See §9. |
+
+---
+
+## 3. Aggregate Strategy Comparison (BM25 vs Vector vs RRF vs RSF)
+
+Evaluation over ${totalQueries} hard semantic, paraphrased, and cross-lingual Russian-to-English queries.
+
+**Achieved winner by MRR (then recall tie-break)**: **${winnerLabel}**
+
+| Search Strategy | MRR@5 | Recall@5 | NDCG@5 |
+|---|---|---|---|
+| **BM25 Text Search Only** | ${qualityComp.bm25.mrr} | ${qualityComp.bm25.recall} (${(qualityComp.bm25.recall * 100).toFixed(1)}%) | ${qualityComp.bm25.ndcg} |
+| **Dense ONNX Vector Only** | ${qualityComp.vector.mrr} | ${qualityComp.vector.recall} (${(qualityComp.vector.recall * 100).toFixed(1)}%) | ${qualityComp.vector.ndcg} |
+| **Hybrid RRF (Reciprocal Rank), k=${qualityComp.defaultRrfK ?? 60}** | ${qualityComp.hybridRrf.mrr} | ${qualityComp.hybridRrf.recall} (${(qualityComp.hybridRrf.recall * 100).toFixed(1)}%) | ${qualityComp.hybridRrf.ndcg} |
+| **Hybrid RSF (Relative Score), α=${qualityComp.defaultAlpha ?? 0.5}** | ${qualityComp.hybridRsf.mrr} | ${qualityComp.hybridRsf.recall} (${(qualityComp.hybridRsf.recall * 100).toFixed(1)}%) | ${qualityComp.hybridRsf.ndcg} |
+
+### 3.1 Bootstrap 95% CIs (reciprocal-rank resampling, 1000 iterations)
+
+| Mode | MRR CI | Recall CI | NDCG CI |
+|---|---|---|---|
+${ciRows}
+
+### 3.2 Paired t-tests (reciprocal rank, two-sided)
+
+| Comparison | Mean ΔRR | t | p | SEM | n |
+|---|---|---|---|---|---|
+${tRows}
+
+---
+
+## 4. Per-Category Aggregate Metrics
+
+| Category | N | BM25 MRR | Vector MRR | RRF MRR | RSF MRR | RRF Recall | RSF Recall |
+|---|---|---|---|---|---|---|---|
+${catRows}
+
+---
+
+## 5. Granular Query-by-Query Ranking Breakdown
+
+| # | Target Doc | Category | BM25 Rank | Vector Rank | RRF Rank | RSF Rank | Query Text Snippet |
+|---|---|---|---|---|---|---|---|
+${breakdownRows}
+
+---
+
+## 6. Hyperparameter Grid Search
+
+### 6.1 RSF alpha sweep (default α=0.5)
+
+| α | MRR | Recall | NDCG | Top-1 wins |
+|---|---|---|---|---|
+${rsfGridRows}
+
+**Best α by MRR**: ${qualityComp.bestRsfAlpha?.alpha} → MRR ${qualityComp.bestRsfAlpha?.mrr}
+
+### 6.2 RRF k sweep (default k=60)
+
+| k | MRR | Recall | NDCG | Top-1 wins |
+|---|---|---|---|---|
+${rrfGridRows}
+
+**Best k by MRR**: ${qualityComp.bestRrfK?.k} → MRR ${qualityComp.bestRrfK?.mrr}
+
+---
+
+## 7. Search Latency (per-query, shared pre-fetch of BM25 + vector hits)
+
+| Stat | ms |
+|---|---|
+| Mean | ${qualityComp.latency?.mean ?? "—"} |
+| p50 | ${qualityComp.latency?.p50 ?? "—"} |
+| p95 | ${qualityComp.latency?.p95 ?? "—"} |
+| p99 | ${qualityComp.latency?.p99 ?? "—"} |
+| Max | ${qualityComp.latency?.max ?? "—"} |
+
+*Pre-fetch latency includes FTS5 query + ONNX embedding inference + full vector scan + SQLite join. All fusion modes operate on the pre-fetched candidate lists, so per-mode latency deltas vs BM25 are negligible (in-memory).*
+
+---
+
+## 8. Detailed Analysis & Key Takeaways
+
+1. **Achieved Winner**: ${winnerLabel} took the lead by MRR. **Treat differences smaller than the bootstrap CI half-width as noise** — at N=${totalQueries} a ≈0.03 MRR gap may not be statistically distinguishable from zero.
+
+2. **Paired test verdict**: RRF vs RSF mean ΔRR = ${qualityComp.pairedTests.rrfVsRsf.meanDiff}, p ≈ ${qualityComp.pairedTests.rrfVsRsf.p}. ${
+      qualityComp.pairedTests.rrfVsRsf.p < 0.05
+        ? "Statistically significant difference."
+        : "**NOT statistically significant** at α=0.05; treat as comparable."
+    }
+
+3. **Per-Category Strengths**: BM25 wins Code/Keyword (lexical overlap), Vector wins Cross-Lingual (semantic gap bridging), hybrid modes narrow the long tail — see Section 4.
+
+4. **Hybrid Recovery**: RRF found ${totalQueries - rrfMissed}/${totalQueries} (${(qualityComp.hybridRrf.recall * 100).toFixed(1)}%), RSF found ${totalQueries - rsfMissed}/${totalQueries} (${(qualityComp.hybridRsf.recall * 100).toFixed(1)}%), Vector-only found ${totalQueries - vecMissed}/${totalQueries} (${(qualityComp.vector.recall * 100).toFixed(1)}%), BM25-only found ${totalQueries - bm25Missed}/${totalQueries} (${(qualityComp.bm25.recall * 100).toFixed(1)}%).
+
+5. **BM25 Cross-Lingual Limitation**: BM25 found ${totalQueries - bm25Missed}/${totalQueries} (${(qualityComp.bm25.recall * 100).toFixed(1)}%). BM25 fails on cross-lingual queries (Russian query → English docs) due to zero lexical overlap, while vector search bridges the semantic gap.
+
+6. **Configurable CLI Architecture**: Users can switch algorithms on the fly between RSF, RRF, Pure Lexical, and Pure Semantic via \`memory_plugin cli\`. The headline table above uses the runtime defaults (α=${qualityComp.defaultAlpha}, k=${qualityComp.defaultRrfK}); the grid sweep in §6 picked α=${qualityComp.bestRsfAlpha?.alpha}, k=${qualityComp.bestRrfK?.k} as best-by-MRR — consider bumping them in \`config_defaults\`.
+
+## 9. Reproducibility & Methodology Caveats
+
+- **Strict doc-id matching**: a query counts as hit iff the returned chunk belongs to one of \`expectedDocIds\` (the corpus source-id derived from the blob file basename, e.g. \`axios_readme\`). This avoids false-positive substring matches (e.g. query "next" against any doc mentioning "next").
+- **Pre-warm RSS baseline**: ONNX weights are loaded once *before* timing, so \`RAM Memory Footprint\` reflects ingestion-only memory; the previous report had a –109 MB negative value because the baseline was captured mid-loop.
+- **Single run variance**: With only ${totalQueries} queries, single-run point estimates carry high variance. Bootstrap CIs (3.1) and the paired t-test (3.2) communicate the uncertainty; for production-grade claims please run with ≥50 queries on a fixed corpus snapshot.
+- **Corpus drift**: Documents are fetched live from GitHub \`main\`/ \`master\` HEADs, so consecutive runs are NOT directly comparable across runs. Versioning the corpus (Git SHA snapshot) is the next step.
+`;
+
+  return markdownReport;
+}
+
+async function runFullBenchmarkSuite() {
+  const startTime = Date.now();
+
+  printRichPanel("LOCAL RAG BENCHMARK SUITE", "Real ONNX Embeddings & BM25 vs Vector vs RRF vs RSF");
+
+  // 1. Dual Layer Architectural Verification
+  console.log("\n --- Phase 1: Dual Layer Architectural Verification ---");
+  await testDualLayerArchitecture();
+
+  // 2. Ingestion & Storage Benchmark WITH REAL ONNX EMBEDDINGS
+  console.log("\n --- Phase 2: Real ONNX Ingestion & Embedding Benchmark ---");
+  const ingestMetrics = await runIngestionBenchmark({ generateEmbeddings: true });
+
+  // 3. Search Quality & Latency Benchmark with per-query breakdown
+  console.log("\n --- Phase 3: Granular Search Quality Comparison (BM25 vs Vector vs RRF vs RSF) ---");
+  const qualityComp = await evaluateSearchQualityComparison(ingestMetrics.dbInstance);
+
+  // Clean up test DB
+  if (ingestMetrics.dbInstance) {
+    try {
+      ingestMetrics.dbInstance.close();
+    } catch {}
+  }
+  if (existsSync(dirname(ingestMetrics.dbPath))) {
+    try {
+      rmSync(dirname(ingestMetrics.dbPath), { recursive: true, force: true });
+    } catch {}
+  }
+
+  const totalTimeSec = ((Date.now() - startTime) / 1000).toFixed(2);
+  const winner = qualityComp.winner;
+  const totalQueries = qualityComp.breakdown.length;
+
+  // 4. Generate Comprehensive Markdown Report
+  const markdownReport = buildMarkdownReport({ ingestMetrics, qualityComp, totalTimeSec });
+
+  await writeFile(REPORT_PATH, markdownReport, "utf-8");
+
+  // JSON sidecar (machine-readable, for CI / regression tooling) + history snapshot.
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/[:.]/g, "-");
+
+  const machineReport = {
+    generatedAt: new Date().toISOString(),
+    totalDurationSec: Number(totalTimeSec),
+    corpus: {
+      docs: ingestMetrics.docCount,
+      network: ingestMetrics.networkDocCount,
+      local: ingestMetrics.localDocCount,
+      sections: ingestMetrics.totalSections,
+      microChunks: ingestMetrics.totalMicroChunks,
+    },
+    ingestion: {
+      durationSec: ingestMetrics.durationSec,
+      docsPerSec: ingestMetrics.docsPerSec,
+      chunksPerSec: ingestMetrics.chunksPerSec,
+      dbSizeMB: ingestMetrics.dbSizeMB,
+      blobSizeMB: ingestMetrics.blobSizeMB,
+      ramUsageMB: ingestMetrics.ramUsageMB,
+      settledRamUsageMB: ingestMetrics.settledRamUsageMB ?? null,
+      peakRamUsageMB: ingestMetrics.peakRamUsageMB ?? null,
+      ramBaseline: ingestMetrics.ramBaseline ?? "pre-loop",
+      ramMetric: ingestMetrics.metric ?? "heapUsed + external",
+    },
+    search: {
+      winner,
+      n: totalQueries,
+      bm25: qualityComp.bm25,
+      vector: qualityComp.vector,
+      hybridRrf: qualityComp.hybridRrf,
+      hybridRsf: qualityComp.hybridRsf,
+      bootstrap: qualityComp.bootstrap,
+      pairedTests: qualityComp.pairedTests,
+      categoryBreakdown: qualityComp.categoryBreakdown,
+      rsfGrid: qualityComp.rsfGrid,
+      rrfGrid: qualityComp.rrfGrid,
+      bestRsfAlpha: qualityComp.bestRsfAlpha,
+      bestRrfK: qualityComp.bestRrfK,
+      latency: qualityComp.latency,
+      breakdown: qualityComp.breakdown,
+    },
+  };
+
+  const JSON_PATH = join(__dirname, "..", "..", "dev_docs", `benchmark_${timestamp}.json`);
+  await writeFile(JSON_PATH, JSON.stringify(machineReport, null, 2), "utf-8");
+
+  if (!existsSync(HISTORY_DIR)) {
+    await mkdirAsync(HISTORY_DIR, { recursive: true });
+  }
+  const HISTORY_PATH = join(HISTORY_DIR, `benchmark_${timestamp}.json`);
+  await writeFile(HISTORY_PATH, JSON.stringify(machineReport, null, 2), "utf-8");
+
+  console.log(`\n [OK] BENCHMARK SUITE COMPLETED IN ${totalTimeSec}s!`);
+  console.log(` [REPORT] Markdown: dev_docs/benchmark_results.md`);
+  console.log(` [JSON]   Latest:    dev_docs/benchmark_${timestamp}.json`);
+  console.log(` [HIST]   History:   dev_docs/benchmark_history/benchmark_${timestamp}.json\n`);
+}
+
+// Auto-respawn with --expose-gc if needed so the ingestion memory benchmark can
+// force GC after model warm-up, giving a clean baseline. Without it `global.gc`
+// is undefined and the baseline stays noisy.
+// Only run when this file is the entry point. Importing it (e.g. to reuse
+// buildMarkdownReport) must not kick off a full ONNX benchmark run.
+const isEntryPoint =
+  process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+
+if (isEntryPoint) {
+  if (!process.argv.includes("--no-respawn") && !global.gc) {
+    const { spawn } = await import("node:child_process");
+    const child = spawn(process.execPath, ["--expose-gc", ...process.argv.slice(1)], { stdio: "inherit" });
+    child.on("exit", (code) => process.exit(code ?? 0));
+  } else {
+    runFullBenchmarkSuite().catch((err) => {
+      console.error(" [ERROR] Benchmark Suite Executed with Errors:", err);
+      process.exit(1);
+    });
+  }
+}

package/mcp-server/benchmarks/stress_ingestion.js

@@ -0,0 +1,195 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, basename } from "node:path";
+import { tmpdir } from "node:os";
+import { rmSync, existsSync } from "node:fs";
+import { getDatabase } from "../db/database.js";
+import { ingestDocument } from "../ingest/pipeline.js";
+import { embedText, resetExtractor } from "../ml/model_manager.js";
+import { CORPUS_DIR, fetchRealCorpus } from "./fetch_real_corpus.js";
+
+// RSS is too volatile to measure incremental ingestion memory because V8's RSS
+// retains free-list pages long after the underlying heap shrinks. We track
+// `heapUsed + external` instead: heapUsed covers JS allocations (vector buffers,
+// sqlite cache), external covers WASM/ONNX buffers held off-heap.
+function memUsedBytes() {
+  const m = process.memoryUsage();
+  return m.heapUsed + m.external;
+}
+
+const PANEL_WIDTH = 58;
+
+function printRichPanel(title, subtitle = "") {
+  const line = "─".repeat(PANEL_WIDTH - 2);
+  console.log(`\x1b[36m╭${line}╮\x1b[0m`);
+  console.log(`\x1b[36m│\x1b[0m  \x1b[1m\x1b[37m${title.padEnd(PANEL_WIDTH - 6)}\x1b[0m  \x1b[36m│\x1b[0m`);
+  if (subtitle) {
+    console.log(`\x1b[36m│\x1b[0m  \x1b[90m${subtitle.padEnd(PANEL_WIDTH - 6)}\x1b[0m  \x1b[36m│\x1b[0m`);
+  }
+  console.log(`\x1b[36m╰${line}╯\x1b[0m`);
+}
+
+export async function runIngestionBenchmark(options = {}) {
+  const silent = options.silent || false;
+  const onProgress = options.onProgress || null;
+  const subsetDocIds = options.subsetDocIds || null;
+  const corpus = await fetchRealCorpus({ silent, onProgress, subsetDocIds });
+  const TEST_DIR = join(tmpdir(), `memory_bench_ingest_${Date.now()}`);
+  const TEST_DB_PATH = join(TEST_DIR, "bench_memory.sqlite");
+  const TEST_BLOB_DIR = join(TEST_DIR, "blobs");
+
+  const db = await getDatabase(TEST_DB_PATH);
+
+  if (!silent) {
+    printRichPanel("DOCUMENT INGESTION BENCHMARK", `Embeddings ONNX Enabled: ${options.generateEmbeddings}`);
+    console.log(`\n  [INGEST] Processing ${corpus.length} technical documents...\n`);
+  }
+
+  // Pre-warm ONNX model so its weight loading does NOT inflate ingestion RSS delta.
+  // Without this the first embedText() inside the loop would pay the one-time model
+  // load cost (~100MB), biasing the "Ingestion RAM" metric.
+  let baselineMemLabel = "pre-loop";
+  if (options.generateEmbeddings) {
+    await embedText("warmup", false);
+    baselineMemLabel = "post-model-warmup";
+    if (!silent) console.log(`   [Warmup] ONNX model loaded; baseline taken ${baselineMemLabel}.`);
+    // Force GC if exposed to drop transient allocation noise from init.
+    if (global.gc) {
+      global.gc();
+      baselineMemLabel = "post-model-warmup(post-gc)";
+    }
+  }
+
+  const startMem = memUsedBytes();
+  const startTime = performance.now();
+  // Track peak heapUsed+external during the loop to capture transient allocations.
+  let peakMem = startMem;
+  // Heap shrinkage is much faster than RSS free-list reclaim, so polling works; but
+  // also sample synchronously after each doc ingest in between timer ticks, since
+  // ONNX inference for a single doc may span multiple 25ms windows.
+  const memPollInterval = setInterval(() => {
+    const cur = memUsedBytes();
+    if (cur > peakMem) peakMem = cur;
+  }, 25);
+
+  let totalSections = 0;
+  let totalMicroChunks = 0;
+  let totalBytes = 0;
+  let deduplicatedCount = 0;
+
+  for (let i = 0; i < corpus.length; i++) {
+    const file = corpus[i];
+    const content = await readFile(file.path, "utf-8");
+    totalBytes += content.length;
+
+    const ingestRes = await ingestDocument({
+      content,
+      type: "file",
+      title: file.title,
+      path: file.path,
+      generateEmbeddings: options.generateEmbeddings,
+      customDb: db,
+      customBlobDir: TEST_BLOB_DIR,
+    });
+
+    totalSections += ingestRes.sectionsCount;
+    totalMicroChunks += ingestRes.microChunksCount;
+    if (ingestRes.deduplicated) deduplicatedCount++;
+
+    if (global.gc) global.gc();
+
+    // Synchronous peak sample: captures peak after each doc ingestion completes,
+    // complementing the 25ms interval poll (which can miss transient peaks).
+    const cur = memUsedBytes();
+    if (cur > peakMem) peakMem = cur;
+
+    if (!silent && ((i + 1) % 5 === 0 || i === corpus.length - 1)) {
+      console.log(`   [Progress] Ingested ${i + 1}/${corpus.length} docs (${totalMicroChunks} micro-chunks)`);
+    }
+    if (onProgress) onProgress({ phase: "ingest", current: i + 1, total: corpus.length });
+  }
+
+  clearInterval(memPollInterval);
+  const endTime = performance.now();
+  const endMemPreGc = memUsedBytes();
+
+  // Force GC to separate transient garbage from the persistent ingestion footprint.
+  // Requires --expose-gc (run_benchmarks.js auto-respawns with it).
+  let endMemPostGc = endMemPreGc;
+  if (global.gc) {
+    global.gc();
+    endMemPostGc = memUsedBytes();
+  }
+
+  const durationMs = endTime - startTime;
+  const durationSec = durationMs / 1000;
+  const docsPerSec = corpus.length / durationSec;
+  const chunksPerSec = totalMicroChunks / durationSec;
+  const peakDeltaMB = Math.max(peakMem - startMem, endMemPreGc - startMem) / (1024 * 1024);
+
+  const dbStat = await stat(TEST_DB_PATH);
+  const dbSizeBytes = dbStat.size;
+
+  let blobSizeBytes = 0;
+  if (existsSync(TEST_BLOB_DIR)) {
+    const blobFiles = await readdir(TEST_BLOB_DIR, { recursive: true });
+    for (const bf of blobFiles) {
+      const p = join(TEST_BLOB_DIR, bf);
+      const st = await stat(p);
+      if (st.isFile()) blobSizeBytes += st.size;
+    }
+  }
+
+  const metrics = {
+    docCount: corpus.length,
+    networkDocCount: corpus.filter((d) => d.source === "network").length,
+    localDocCount: corpus.filter((d) => d.source !== "network").length,
+    totalSections,
+    totalMicroChunks,
+    totalBytes,
+    deduplicatedCount,
+    durationSec: Number(durationSec.toFixed(2)),
+    docsPerSec: Number(docsPerSec.toFixed(2)),
+    chunksPerSec: Number(chunksPerSec.toFixed(2)),
+    dbSizeMB: Number((dbSizeBytes / (1024 * 1024)).toFixed(2)),
+    blobSizeMB: Number((blobSizeBytes / (1024 * 1024)).toFixed(2)),
+    // Ingestion-only memory delta (heapUsed + external), measured AFTER model
+    // pre-warm so ONNX weight load is excluded. `ramUsageMB` is pre-GC (upper
+    // bound incl. transient garbage); `settledRamUsageMB` is post-GC.
+    ramUsageMB: Number(((endMemPreGc - startMem) / (1024 * 1024)).toFixed(2)),
+    settledRamUsageMB: Number(((endMemPostGc - startMem) / (1024 * 1024)).toFixed(2)),
+    peakRamUsageMB: Number(peakDeltaMB.toFixed(2)),
+    ramBaseline: baselineMemLabel,
+    metric: "heapUsed + external",
+    dbPath: TEST_DB_PATH,
+    blobDir: TEST_BLOB_DIR,
+    dbInstance: db,
+  };
+
+  if (!silent) {
+    console.log("\n  [Ingestion Performance Summary]");
+    console.log(`  - Total Documents: ${metrics.docCount}`);
+    console.log(`  - Total Sections: ${metrics.totalSections}`);
+    console.log(`  - Total Micro-Chunks: ${metrics.totalMicroChunks}`);
+    console.log(`  - Duration: ${metrics.durationSec}s`);
+    console.log(`  - Throughput: ${metrics.docsPerSec} docs/sec | ${metrics.chunksPerSec} chunks/sec`);
+    console.log(`  - Database Size: ${metrics.dbSizeMB} MB`);
+    console.log(`  - Blob Storage Size: ${metrics.blobSizeMB} MB`);
+    console.log(`  - Memory Footprint pre-GC  (heapUsed+ext Δ): ${metrics.ramUsageMB} MB (${metrics.ramBaseline})`);
+    console.log(`  - Memory Footprint post-GC (settled Δ):      ${metrics.settledRamUsageMB} MB`);
+    console.log(`  - Memory Peak (max Δ during loop):           ${metrics.peakRamUsageMB} MB`);
+    console.log(`  (Negative ingestion Δ = loop reclaimed more warmup garbage than it allocated.`);
+    console.log(`   ONNX native weights are owned by onnxruntime-node and not visible here.)\n`);
+  }
+
+  return metrics;
+}
+
+if (process.argv[1] && process.argv[1].includes("stress_ingestion.js")) {
+  const metrics = await runIngestionBenchmark({ generateEmbeddings: false });
+  if (existsSync(dirname(metrics.dbPath))) {
+    try {
+      metrics.dbInstance.close();
+      rmSync(dirname(metrics.dbPath), { recursive: true, force: true });
+    } catch {}
+  }
+}