brainbank 0.4.1 → 0.6.0

package/README.md

@@ -5,13 +5,14 @@
 BrainBank gives LLMs a long-term memory that persists between sessions.
 
 - **All-in-one** — core + code + git + docs + CLI in a single `brainbank` package
-- **Pluggable indexers** — `.use()` only what you need (code, git, docs, or custom)
+- **Pluggable plugins** — `.use()` only what you need (code, git, docs, or custom)
 - **Dynamic collections** — `brain.collection('errors')` for any structured data
 - **Hybrid search** — vector + BM25 fused with Reciprocal Rank Fusion
 - **Pluggable embeddings** — local WASM (free), OpenAI, or Perplexity (standard & contextualized)
 - **Multi-repo** — index multiple repositories into one shared database
 - **Portable** — single `.brainbank/brainbank.db` file
-- **Optional packages** — [`@brainbank/memory`](#memory) (fact extraction + entity graph), [`@brainbank/reranker`](#reranker) (Qwen3 cross-encoder), [`@brainbank/mcp`](#mcp-server) (MCP server)
+- **Optional packages** — [`@brainbank/memory`](#memory) (fact extraction + entity graph), [`@brainbank/mcp`](#mcp-server) (MCP server)
+- **Optional reranker** — Qwen3-0.6B cross-encoder via `Qwen3Reranker` (opt-in)
 
 ![BrainBank Architecture](assets/architecture.png)
 
@@ -28,7 +29,7 @@ Most AI memory solutions (mem0, Zep, LangMem) require cloud services, external d
 | Infrastructure | **SQLite file** | Vector DB + cloud | Neo4j + cloud | LangGraph Platform |
 | LLM required to write | **No**¹ | Yes | Yes | Yes |
 | Code-aware | **19 AST-parsed languages (tree-sitter), git, co-edits** | ✗ | ✗ | ✗ |
-| Custom indexers | **`.use()` plugin system** | ✗ | ✗ | ✗ |
+| Custom plugins | **`.use()` plugin system** | ✗ | ✗ | ✗ |
 | Search | **Vector + BM25 + RRF** | Vector + graph² | Vector + BM25 + graph | Vector only |
 | Framework lock-in | **None** | Optional | Zep cloud | LangChain |
 | Portable | **Copy one file** | Tied to DB | Tied to cloud | Tied to platform |
@@ -50,12 +51,12 @@ Most AI memory solutions (mem0, Zep, LangMem) require cloud services, external d
 - [Quick Start](#quick-start)
 - [CLI](#cli)
 - [Programmatic API](#programmatic-api)
-  - [Indexers](#indexers)
+  - [Plugins](#plugins)
   - [Collections](#collections)
   - [Search](#search)
   - [Document Collections](#document-collections)
   - [Context Generation](#context-generation)
-  - [Custom Indexers](#custom-indexers)
+  - [Custom Plugins](#custom-plugins)
   - [AI Agent Integration](#ai-agent-integration)
   - [Examples](#examples)
   - [Watch Mode](#watch-mode)
@@ -73,6 +74,7 @@ Most AI memory solutions (mem0, Zep, LangMem) require cloud services, external d
 - [Benchmarks](#benchmarks)
   - [Search Quality: AST vs Sliding Window](#search-quality-ast-vs-sliding-window)
   - [Grammar Support](#grammar-support)
+  - [RAG Retrieval Quality](#rag-retrieval-quality) · [Full Results →](./BENCHMARKS.md)
 
 ---
 
@@ -87,20 +89,48 @@ npm install brainbank
 | Package | When to install |
 |---------|----------------|
 | `@brainbank/memory` | Deterministic memory extraction + entity graph for LLM conversations |
-| `@brainbank/reranker` | Cross-encoder reranker (Qwen3-0.6B, ~640MB model) |
 | `@brainbank/mcp` | MCP server for AI tool integration |
 
 ```bash
 # Memory — automatic fact extraction & dedup for chatbots/agents
 npm install @brainbank/memory
 
-# Reranker — improves search ranking with local neural inference
-npm install @brainbank/reranker node-llama-cpp
+# Reranker — built-in, install the runtime dependency to enable
+npm install node-llama-cpp
 
 # MCP server — for Antigravity, Claude Desktop, etc.
 npm install @brainbank/mcp
 ```
 
+### Tree-Sitter Grammars
+
+BrainBank uses [tree-sitter](https://tree-sitter.github.io/) for AST-aware code chunking. **JavaScript and TypeScript grammars are included by default.** Other languages require installing the corresponding grammar package:
+
+```bash
+# Install only the grammars you need
+npm install tree-sitter-python tree-sitter-go tree-sitter-rust
+```
+
+If you index a file whose grammar isn't installed, BrainBank will throw a clear error:
+
+```
+BrainBank: Grammar 'tree-sitter-python' is not installed. Run: npm install tree-sitter-python
+```
+
+<details>
+<summary>All available grammars (19 languages)</summary>
+
+| Category | Packages |
+|----------|----------|
+| **Included** | `tree-sitter-javascript`, `tree-sitter-typescript` |
+| Web | `tree-sitter-html`, `tree-sitter-css` |
+| Systems | `tree-sitter-go`, `tree-sitter-rust`, `tree-sitter-c`, `tree-sitter-cpp`, `tree-sitter-swift` |
+| JVM | `tree-sitter-java`, `tree-sitter-kotlin`, `tree-sitter-scala` |
+| Scripting | `tree-sitter-python`, `tree-sitter-ruby`, `tree-sitter-php`, `tree-sitter-lua`, `tree-sitter-bash`, `tree-sitter-elixir` |
+| .NET | `tree-sitter-c-sharp` |
+
+</details>
+
 ---
 
 ## Quick Start
@@ -177,10 +207,10 @@ brainbank watch                             # Watch repo, auto re-index on save
 #   Watching /path/to/repo for changes...
 #   14:30:02 ✓ code: src/api.ts
 #   14:30:05 ✓ code: src/routes.ts
-#   14:30:08 ✓ csv: data/metrics.csv       ← custom indexer
+#   14:30:08 ✓ csv: data/metrics.csv       ← custom plugin
 ```
 
-> Watch mode monitors **code files** by default. [Custom indexers](#custom-indexers) that implement `watchPatterns()` and `onFileChange()` are automatically picked up — their name appears in the console output alongside the built-in `code` indexer. Git history and document collections are not affected by file-system changes and must be re-indexed explicitly with `brainbank index` / `brainbank docs`.
+> Watch mode monitors **code files** by default. [Custom plugins](#custom-plugins) that implement `watchPatterns()` and `onFileChange()` are automatically picked up — their name appears in the console output alongside the built-in `code` plugin. Git history and document collections are not affected by file-system changes and must be re-indexed explicitly with `brainbank index` / `brainbank docs`.
 
 ### Document Collections
 
@@ -234,11 +264,11 @@ brainbank serve                             # Start MCP server (stdio)
 
 Use BrainBank as a library in your TypeScript/Node.js project.
 
-### Indexers
+### Plugins
 
-BrainBank uses pluggable indexers. Register only what you need with `.use()`:
+BrainBank uses pluggable plugins. Register only what you need with `.use()`:
 
-| Indexer | Import | Description |
+| Plugin | Import | Description |
 |---------|--------|-------------|
 | `code` | `brainbank/code` | AST-aware code chunking via tree-sitter (19 languages) |
 | `git` | `brainbank/git` | Git commit history, diffs, co-edit relationships |
@@ -250,7 +280,7 @@ import { code } from 'brainbank/code';
 import { git } from 'brainbank/git';
 import { docs } from 'brainbank/docs';
 
-// Pick only the indexers you need
+// Pick only the plugins you need
 const brain = new BrainBank({ repoPath: '.' })
   .use(code())
   .use(git())
@@ -291,7 +321,7 @@ decisions.prune({ olderThan: '30d' });  // remove older than 30 days
 brain.listCollectionNames();            // → ['decisions', ...]
 ```
 
-> 📂 See [examples/collections](examples/collections/) for a complete runnable demo with cross-collection linking and metadata.
+> 📂 See [examples/collection](examples/collection/) for a complete runnable demo with cross-collection linking and metadata.
 
 ### Watch Mode
 
@@ -301,7 +331,7 @@ Auto-re-index when files change:
 // API
 const watcher = brain.watch({
   debounceMs: 2000,
-  onIndex: (file, indexer) => console.log(`${indexer}: ${file}`),
+  onIndex: (file, plugin) => console.log(`${plugin}: ${file}`),
   onError: (err) => console.error(err.message),
 });
 
@@ -317,15 +347,15 @@ brainbank watch
 # 14:30:05 ✓ code: src/routes.ts
 ```
 
-#### Custom Indexer Watch
+#### Custom Plugin Watch
 
-Custom indexers can hook into watch mode by implementing `onFileChange` and `watchPatterns`:
+Custom plugins can hook into watch mode by implementing `onFileChange` and `watchPatterns`:
 
 ```typescript
-import type { Indexer, IndexerContext } from 'brainbank';
+import type { Plugin, PluginContext } from 'brainbank';
 
-function csvIndexer(): Indexer {
-  let ctx: IndexerContext;
+function csvPlugin(): Plugin {
+  let ctx: PluginContext;
 
   return {
     name: 'csv',
@@ -334,7 +364,7 @@ function csvIndexer(): Indexer {
       ctx = context;
     },
 
-    // Tell watch which files this indexer cares about
+    // Tell watch which files this plugin cares about
     watchPatterns() {
       return ['**/*.csv', '**/*.tsv'];
     },
@@ -356,7 +386,7 @@ function csvIndexer(): Indexer {
 
 const brain = new BrainBank({ dbPath: './brain.db' })
   .use(code())
-  .use(csvIndexer());
+  .use(csvPlugin());
 
 await brain.initialize();
 brain.watch(); // Now watches .ts, .py, etc. AND .csv, .tsv
@@ -423,16 +453,16 @@ const context = await brain.getContext('add rate limiting to the API', {
 // Returns: ## Relevant Code, ## Git History, ## Relevant Documents
 ```
 
-### Custom Indexers
+### Custom Plugins
 
-Implement the `Indexer` interface to build your own:
+Implement the `Plugin` interface to build your own:
 
 ```typescript
-import type { Indexer, IndexerContext } from 'brainbank';
+import type { Plugin, PluginContext } from 'brainbank';
 
-const myIndexer: Indexer = {
+const myPlugin: Plugin = {
   name: 'custom',
-  async initialize(ctx: IndexerContext) {
+  async initialize(ctx: PluginContext) {
     // ctx.db            — shared SQLite database
     // ctx.embedding     — shared embedding provider
     // ctx.collection()  — create dynamic collections
@@ -441,10 +471,10 @@ const myIndexer: Indexer = {
   },
 };
 
-brain.use(myIndexer);
+brain.use(myPlugin);
 ```
 
-#### Using custom indexers with the CLI
+#### Using custom plugins with the CLI
 
 Drop `.ts` files into `.brainbank/indexers/` — the CLI auto-discovers them:
 
@@ -456,11 +486,11 @@ Drop `.ts` files into `.brainbank/indexers/` — the CLI auto-discovers them:
     └── jira.ts
 ```
 
-Each file exports a default `Indexer`:
+Each file exports a default `Plugin`:
 
 ```typescript
 // .brainbank/indexers/slack.ts
-import type { Indexer } from 'brainbank';
+import type { Plugin } from 'brainbank';
 
 export default {
   name: 'slack',
@@ -468,14 +498,14 @@ export default {
     const msgs = ctx.collection('slack_messages');
     // ... fetch and index slack messages
   },
-} satisfies Indexer;
+} satisfies Plugin;
 ```
 
-That's it — all CLI commands automatically pick up your indexers:
+That's it — all CLI commands automatically pick up your plugins:
 
 ```bash
 brainbank index                             # runs code + git + docs + slack + jira
-brainbank stats                             # shows all indexers
+brainbank stats                             # shows all plugins
 brainbank kv search slack_messages "deploy"  # search slack data
 ```
 
@@ -493,18 +523,18 @@ export default {
 };
 ```
 
-Everything lives in `.brainbank/` — DB, config, and custom indexers:
+Everything lives in `.brainbank/` — DB, config, and custom plugins:
 
 ```
 .brainbank/
 ├── brainbank.db        # SQLite database (auto-created)
 ├── config.ts           # Optional project config
-└── indexers/           # Optional custom indexer files
+└── indexers/           # Optional custom plugin files
     ├── slack.ts
     └── jira.ts
 ```
 
-No folder and no config file? The CLI uses the built-in indexers (`code`, `git`, `docs`).
+No folder and no config file? The CLI uses the built-in plugins (`code`, `git`, `docs`).
 
 ---
 
@@ -555,19 +585,19 @@ Teach your AI coding agent to use BrainBank as persistent memory. Add an `AGENTS
 | **Cursor** | Add rules in `.cursor/rules` |
 | **MCP** (any agent) | See [MCP Server](#mcp-server) config below |
 
-#### Custom Indexer: Auto-Ingest Conversation Logs
+#### Custom Plugin: Auto-Ingest Conversation Logs
 
 For agents that produce structured logs (e.g. Antigravity's `brain/` directory), auto-index them:
 
 ```typescript
 // .brainbank/indexers/conversations.ts
-import type { Indexer, IndexerContext } from 'brainbank';
+import type { Plugin, PluginContext } from 'brainbank';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 export default {
   name: 'conversations',
-  async initialize(ctx: IndexerContext) {
+  async initialize(ctx: PluginContext) {
     const conversations = ctx.collection('conversations');
     const logsDir = path.join(ctx.config.repoPath, '.gemini/antigravity/brain');
     if (!fs.existsSync(logsDir)) return;
@@ -583,7 +613,7 @@ export default {
       });
     }
   },
-} satisfies Indexer;
+} satisfies Plugin;
 ```
 
 ```bash
@@ -595,8 +625,9 @@ brainbank kv search conversations "what did we decide about auth"
 
 | Example | Description | Run |
 |---------|-------------|-----|
-| [chatbot](examples/chatbot/) | CLI chatbot with streaming + persistent memory (context injection + function calling) | `OPENAI_API_KEY=sk-... npx tsx examples/chatbot/chatbot.ts` |
-| [collections](examples/collections/) | Collections, semantic search, tags, metadata linking | `npx tsx examples/collections/collections.ts` |
+| [rag](examples/rag/) | RAG chatbot — docs retrieval + generation | `OPENAI_API_KEY=sk-... PERPLEXITY_API_KEY=pplx-... npx tsx examples/rag/rag.ts --docs <path>` |
+| [memory](examples/memory/) | Memory chatbot — fact extraction + entity graph | `OPENAI_API_KEY=sk-... npx tsx examples/memory/memory.ts` |
+| [collection](examples/collection/) | Collections, semantic search, tags, metadata linking | `npx tsx examples/collection/collection.ts` |
 
 ---
 
@@ -617,48 +648,36 @@ Add to your MCP config (`~/.gemini/antigravity/mcp_config.json` or Claude Deskto
   "mcpServers": {
     "brainbank": {
       "command": "npx",
-      "args": ["-y", "@brainbank/mcp"],
-      "env": {
-        "BRAINBANK_EMBEDDING": "openai"
-      }
+      "args": ["-y", "@brainbank/mcp"]
     }
   }
 }
 ```
 
-The agent passes the `repo` parameter on each tool call based on the active workspace — no hardcoded paths needed.
+**Zero-config.** The MCP server auto-detects:
+- **Repo path** — from `repo` tool param > `BRAINBANK_REPO` env > `findRepoRoot(cwd)`
+- **Embedding provider** — from `provider_key` stored in the DB (set during `brainbank index --embedding openai`)
 
-> Set `BRAINBANK_EMBEDDING` to `openai`, `perplexity`, or `perplexity-context` for higher quality search. Omit to use the free local WASM embeddings.
+> [!TIP]
+> Index your repo once with the CLI to set up the embedding provider:
+> ```bash
+> brainbank index . --embedding openai   # stores provider_key=openai in DB
+> ```
+> After that, the MCP server (and any future CLI runs) auto-resolve the correct provider from the DB — no env vars needed.
 
-> Optionally set `BRAINBANK_REPO` as a default fallback repo. If omitted, every tool call must include the `repo` parameter (recommended for multi-workspace setups).
-
-> [!CAUTION]
-> **Embedding Provider Consistency is Critical**
->
-> The embedding provider used by the MCP server **must match** the one used during indexing. Mismatched dimensions cause `initialize()` to throw or search to return empty results.
->
-> **Common failure scenario:**
-> 1. You index via CLI with `BRAINBANK_EMBEDDING=openai` (1536 dims)
-> 2. MCP server starts without `BRAINBANK_EMBEDDING` env var → defaults to local (384 dims)
-> 3. **Result:** BrainBank throws `Embedding dimension mismatch` on every search
->
-> **Fix:** Always set `BRAINBANK_EMBEDDING` consistently in your MCP config, CLI, and API usage. If you indexed with OpenAI, your MCP config **must** include `"BRAINBANK_EMBEDDING": "openai"`. Same for `perplexity` or `perplexity-context`. If you switch providers, run `brainbank reembed` to regenerate all vectors.
+> [!NOTE]
+> If you switch embedding providers (e.g. local → OpenAI), run `brainbank reembed` to regenerate all vectors. BrainBank auto-detects dimension mismatches and warns you.
 
 ### Available Tools
 
 | Tool | Description |
 |------|-------------|
-| `brainbank_hybrid_search` | Best quality: vector + BM25 + reranker |
-| `brainbank_search` | Semantic vector search |
-| `brainbank_keyword_search` | Instant BM25 full-text |
-| `brainbank_context` | Formatted context for a task |
-| `brainbank_index` | Trigger code/git indexing |
-| `brainbank_stats` | Index statistics |
-| `brainbank_history` | Git history for a file |
-| `brainbank_coedits` | Files that change together |
-| `brainbank_collection_add` | Add item to a KV collection |
-| `brainbank_collection_search` | Search a KV collection |
-| `brainbank_collection_trim` | Trim a KV collection |
+| `brainbank_search` | Unified search — `mode: hybrid` (default), `vector`, or `keyword` |
+| `brainbank_context` | Formatted context block for a task (code + git + co-edits) |
+| `brainbank_index` | Trigger incremental code/git/docs indexing |
+| `brainbank_stats` | Index statistics (files, commits, chunks, collections) |
+| `brainbank_history` | Git history for a specific file |
+| `brainbank_collection` | KV collection ops — `action: add`, `search`, or `trim` |
 
 ---
 
@@ -666,7 +685,7 @@ The agent passes the `repo` parameter on each tool call based on the active work
 
 ```typescript
 import { BrainBank, OpenAIEmbedding } from 'brainbank';
-import { Qwen3Reranker } from '@brainbank/reranker';  // separate package
+import { Qwen3Reranker } from 'brainbank';  // built-in, requires node-llama-cpp
 
 const brain = new BrainBank({
   repoPath: '.',
@@ -752,7 +771,12 @@ Real benchmarks on a production NestJS backend (1052 code chunks + git history):
 
 ### Reranker
 
-BrainBank includes an optional cross-encoder reranker using **Qwen3-Reranker-0.6B** via `node-llama-cpp`. It runs 100% locally — no API keys needed. The reranker is **disabled by default**.
+BrainBank ships with an optional cross-encoder reranker using **Qwen3-Reranker-0.6B** via `node-llama-cpp`. It runs 100% locally — no API keys needed. The reranker is **disabled by default**.
+
+```bash
+# Only requirement — the LLM runtime (model auto-downloads on first use)
+npm install node-llama-cpp
+```
 
 #### When to Use It
 
@@ -775,7 +799,7 @@ The reranker runs local neural inference on every search result, which improves
 
 ```typescript
 import { BrainBank } from 'brainbank';
-import { Qwen3Reranker } from '@brainbank/reranker';
+import { Qwen3Reranker } from 'brainbank';
 
 const brain = new BrainBank({
   reranker: new Qwen3Reranker(),  // ~640MB model, auto-downloaded on first use
@@ -835,7 +859,7 @@ const brain = new BrainBank({ repoPath: '.' });
 brain.use(notes());
 await brain.initialize();
 
-const notesPlugin = brain.indexer('notes');
+const notesPlugin = brain.plugin('notes');
 
 // Store a conversation digest
 await notesPlugin.remember({
@@ -877,7 +901,7 @@ const brain = new BrainBank({ repoPath: '.' });
 brain.use(memory());
 await brain.initialize();
 
-const mem = brain.indexer('memory');
+const mem = brain.plugin('memory');
 
 // Record a learning pattern
 await mem.learn({
@@ -961,7 +985,7 @@ The `LLMProvider` interface works with any framework:
 | Vercel AI SDK | `generateText()` → string |
 | Any LLM | Implement `{ generate(messages) → string }` |
 
-> 📂 See [examples/chatbot](examples/chatbot/) for runnable demos with all three frameworks.
+> 📂 See [examples/memory](examples/memory/) for a runnable demo. All three LLM backends supported via `--llm` flag.
 
 > 📦 Full docs: [packages/memory/README.md](packages/memory/README.md)
 
@@ -972,10 +996,12 @@ The `LLMProvider` interface works with any framework:
 | Variable | Description |
 |----------|-------------|
 | `BRAINBANK_REPO` | Default repository path (optional — auto-detected from `.git/` or passed per tool call) |
-| `BRAINBANK_EMBEDDING` | Embedding provider: `local` (default), `openai`, `perplexity`, `perplexity-context` |
+| `BRAINBANK_RERANKER` | Reranker: `none` (default), `qwen3` |
 | `BRAINBANK_DEBUG` | Show full stack traces |
-| `OPENAI_API_KEY` | Required when using `BRAINBANK_EMBEDDING=openai` |
-| `PERPLEXITY_API_KEY` | Required when using `BRAINBANK_EMBEDDING=perplexity` or `perplexity-context` |
+| `OPENAI_API_KEY` | Required when using `--embedding openai` |
+| `PERPLEXITY_API_KEY` | Required when using `--embedding perplexity` or `perplexity-context` |
+
+> **Note:** `BRAINBANK_EMBEDDING` env var has been removed. Use `brainbank index --embedding <provider>` on first index — the provider is stored in the DB and auto-resolved on subsequent runs.
 
 ---
 
@@ -985,7 +1011,7 @@ BrainBank can index multiple repositories into a **single shared database**. Thi
 
 ### How It Works
 
-When you point BrainBank at a directory that contains multiple Git repositories (subdirectories with `.git/`), the CLI **auto-detects** them and creates namespaced indexers:
+When you point BrainBank at a directory that contains multiple Git repositories (subdirectories with `.git/`), the CLI **auto-detects** them and creates namespaced plugins:
 
 ```bash
 ~/projects/
@@ -1019,9 +1045,9 @@ brainbank hsearch "cancel job confirmation" --repo ~/projects
 #   and shared utilities — all in one search.
 ```
 
-### Namespaced Indexers
+### Namespaced Plugins
 
-Each sub-repository gets its own namespaced indexer instances (e.g., `code:frontend`, `git:backend`). Same-type indexers share a single HNSW vector index for efficient memory usage and unified search.
+Each sub-repository gets its own namespaced plugin instances (e.g., `code:frontend`, `git:backend`). Same-type plugins share a single HNSW vector index for efficient memory usage and unified search.
 
 ### Programmatic API
 
@@ -1084,7 +1110,7 @@ For large classes (>80 lines), the chunker descends into the class body and extr
 
 All indexing is **incremental by default** — only new or changed content is processed:
 
-| Indexer | How it detects changes | What gets skipped |
+| Plugin | How it detects changes | What gets skipped |
 |---------|----------------------|-------------------|
 | **Code** | FNV-1a hash of file content | Unchanged files |
 | **Git** | Unique commit hash | Already-indexed commits |
@@ -1233,6 +1259,41 @@ All 9 core grammars verified, each parsing in **<0.05ms**:
 
 > Additional grammars available: C++, Swift, C#, Kotlin, Scala, Lua, Elixir, Bash, HTML, CSS
 
+### RAG Retrieval Quality
+
+BrainBank's hybrid search pipeline (Vector + BM25 → RRF) with Perplexity Context embeddings (2560d):
+
+| Benchmark | Metric | Score |
+|---|---|:---:|
+| **BEIR SciFact** (5,183 docs, 300 queries) | NDCG@10 | **0.761** |
+| **Custom semantic** (69 docs, 20 queries) | R@5 | **83%** |
+
+The hybrid pipeline improved R@5 by **+26pp over vector-only** retrieval on our custom eval.
+
+#### BrainBank vs QMD (Head-to-Head)
+
+Compared against [QMD](https://github.com/tobi/qmd), a local-first search engine using GGUF models (embeddinggemma-300M + query expansion + reranker) — same corpus, same 20 queries:
+
+| Metric | BrainBank + Reranker | QMD + Reranker |
+|---|:---:|:---:|
+| **R@5** | **83%** | 65% |
+| **MRR** | **0.57** | 0.45 |
+| **Misses** | **1/20** | 6/20 |
+
+> BrainBank wins by +18pp R@5. QMD is competitive on semantic queries (81% vs 94%) and ties on broad queries (83% vs 83%) — impressive for a fully local pipeline with zero API calls.
+
+See **[BENCHMARKS.md](./BENCHMARKS.md)** for full pipeline progression, per-technique impact, QMD comparison details, and reproduction instructions.
+
+#### Running the RAG Eval
+
+```bash
+# Custom eval on your own docs
+PERPLEXITY_API_KEY=pplx-... npx tsx test/benchmarks/rag/eval.ts --docs ~/path/to/docs
+
+# BEIR standard benchmark
+PERPLEXITY_API_KEY=pplx-... npx tsx test/benchmarks/rag/beir-eval.ts --dataset scifact
+```
+
 ### Running Benchmarks
 
 ```bash
@@ -1241,6 +1302,9 @@ node test/benchmarks/grammar-support.mjs
 
 # Search quality A/B (uses BrainBank's own source files)
 node test/benchmarks/search-quality.mjs
+
+# RAG retrieval quality (requires Perplexity API key + docs folder)
+PERPLEXITY_API_KEY=pplx-... npx tsx test/benchmarks/rag/eval.ts --docs ~/path/to/docs
 ```
 
 ---
@@ -1259,7 +1323,7 @@ node test/benchmarks/search-quality.mjs
 │                                                      │
 │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────────┐│
 │  │  Code   │ │   Git   │ │  Docs   │ │ Collection ││
-│  │ Indexer │ │ Indexer │ │ Indexer │ │ (dynamic)  ││
+│  │ Plugin  │ │ Indexer │ │ Indexer │ │ (dynamic)  ││
 │  └────┬────┘ └────┬────┘ └────┬────┘ └─────┬──────┘│
 │       │           │           │             │        │
 │  ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌─────▼──────┐│
@@ -1309,7 +1373,7 @@ Final results (sorted by blended score)
 
 ### Data Flow
 
-1. **Index** — Indexers parse files into chunks (tree-sitter AST for code, heading-based for docs)
+1. **Index** — Plugins parse files into chunks (tree-sitter AST for code, heading-based for docs)
 2. **Embed** — Each chunk gets a vector (local WASM or OpenAI)
 3. **Store** — Chunks + vectors → SQLite, vectors → HNSW index
 4. **Search** — Query → HNSW k-NN + BM25 keyword → RRF fusion → optional reranker
@@ -1320,8 +1384,8 @@ Final results (sorted by blended score)
 ## Testing
 
 ```bash
-npm test                    # Unit tests (129 tests)
-npm test -- --integration   # Full suite (211 tests, includes real models + all domains)
+npm test                    # Unit tests (172 tests)
+npm test -- --integration   # Full suite (includes real models + all domains)
 npm test -- --filter code   # Filter by test name
 npm test -- --verbose       # Show assertion details
 ```