brainbank 0.5.0 → 0.7.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)
 
@@ -19,29 +20,16 @@ BrainBank gives LLMs a long-term memory that persists between sessions.
 
 ## Why BrainBank?
 
-Built for a multi-repo codebase that needed unified AI context. Zero infrastructure, zero ongoing cost.
+BrainBank is a **code-aware knowledge engine** — not just a memory layer. It parses your codebase with tree-sitter ASTs, indexes git history and co-edit patterns, and makes everything searchable with hybrid vector + keyword retrieval. Optional packages add conversational memory (`@brainbank/memory`) and MCP integration (`@brainbank/mcp`).
 
-Most AI memory solutions (mem0, Zep, LangMem) require cloud services, external databases, or LLM calls just to store a memory. BrainBank takes a different approach:
-
-| | **BrainBank** | **mem0** | **Zep** | **LangMem** |
+| | **BrainBank** | **QMD** | **mem0 / Zep** | **LangChain** |
 |---|:---:|:---:|:---:|:---:|
-| 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** | ✗ | ✗ | ✗ |
-| 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 |
-
-> ¹ mem0 and Zep use LLMs to auto-extract memories from raw text. BrainBank is explicit — you decide what gets stored. Less magic, more control.
->
-> ² mem0's graph store (mem0g) is available in the paid platform version.
-
-**In short:**
-- **Code-first** — the only memory layer that understands code structure, git history, and file co-edit relationships
-- **Framework-agnostic** — plain TypeScript, works with any agent framework (LangChain, Vercel AI SDK, custom) or none at all. Unopinionated — doesn't force you into a specific pattern
-- **$0 memory bill** — no LLM calls to extract/consolidate. You store what you want, BrainBank embeds deterministically
-- **Truly portable** — `.brainbank/brainbank.db` is a normal file. Copy it, back it up, `git lfs` it
+| Code-aware (AST) | **19 languages** (tree-sitter) | ✗ | ✗ | ✗ |
+| Git + co-edits | ✓ | ✗ | ✗ | ✗ |
+| Search | **Vector + BM25 + RRF** | Vector + reranker | Vector + graph | Vector only |
+| Infra | **SQLite file** | Local GGUF | Vector DB + cloud | Vector DB |
+| Plugins | **`.use()` builder** | ✗ | ✗ | ✗ |
+| Memory | **`@brainbank/memory`** (opt-in) | ✗ | **Core feature** | ✗ |
 
 ### Table of Contents
 
@@ -50,16 +38,17 @@ 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)
 - [MCP Server](#mcp-server)
+- [Project Config](#project-config)
 - [Configuration](#configuration)
   - [Embedding Providers](#embedding-providers)
   - [Reranker](#reranker)
@@ -73,7 +62,8 @@ 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)
+  - [RAG Retrieval Quality](#rag-retrieval-quality)
+    · [Full Results →](./BENCHMARKS.md)
 
 ---
 
@@ -88,20 +78,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, TypeScript, and Python grammars are included by default.** Other languages require installing the corresponding grammar package:
+
+```bash
+# Install only the grammars you need
+npm install tree-sitter-go tree-sitter-rust tree-sitter-ruby
+```
+
+If you index a file whose grammar isn't installed, BrainBank will throw a clear error:
+
+```
+BrainBank: Grammar 'tree-sitter-go' is not installed. Run: npm install tree-sitter-go
+```
+
+<details>
+<summary>All available grammars (19 languages)</summary>
+
+| Category | Packages |
+|----------|----------|
+| **Included** | `tree-sitter-javascript`, `tree-sitter-typescript`, `tree-sitter-python` |
+| 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-ruby`, `tree-sitter-php`, `tree-sitter-lua`, `tree-sitter-bash`, `tree-sitter-elixir` |
+| .NET | `tree-sitter-c-sharp` |
+
+</details>
+
 ---
 
 ## Quick Start
@@ -178,10 +196,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
 
@@ -235,34 +253,44 @@ 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 |
 | `docs` | `brainbank/docs` | Document collections (markdown, wikis) |
 
 ```typescript
-import { BrainBank } from 'brainbank';
+import { BrainBank, OpenAIEmbedding } from 'brainbank';
 import { code } from 'brainbank/code';
 import { git } from 'brainbank/git';
 import { docs } from 'brainbank/docs';
 
-// Pick only the indexers you need
-const brain = new BrainBank({ repoPath: '.' })
-  .use(code())
-  .use(git())
-  .use(docs());
+// Each plugin can use a different embedding provider
+const brain = new BrainBank({ repoPath: '.' })       // default: local WASM (384d, free)
+  .use(code({ embeddingProvider: new OpenAIEmbedding() }))  // code: OpenAI (1536d)
+  .use(git())                                               // git: local (384d)
+  .use(docs());                                             // docs: local (384d)
 
 // Index code + git (incremental — only processes changes)
 await brain.index();
 
-// Index document collections
+// Register and index document collections
 await brain.addCollection({ name: 'wiki', path: '~/docs', pattern: '**/*.md' });
 await brain.indexDocs();
+
+// Dynamic collections — store anything
+const decisions = brain.collection('decisions');
+await decisions.add(
+  'Use SQLite with WAL mode instead of PostgreSQL. Portable, zero infra.',
+  { tags: ['architecture'] }
+);
+const hits = await decisions.search('why not postgres');
+
+brain.close();
 ```
 
 ### Collections
@@ -302,7 +330,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),
 });
 
@@ -318,15 +346,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',
@@ -335,7 +363,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'];
     },
@@ -357,7 +385,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
@@ -424,16 +452,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
@@ -442,10 +470,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:
 
@@ -457,11 +485,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',
@@ -469,43 +497,83 @@ 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
 ```
 
-#### Advanced: config file
+---
 
-For fine-grained control, create a `.brainbank/config.ts`:
+## Project Config
 
-```typescript
-// .brainbank/config.ts
-export default {
-  builtins: ['code', 'docs'],   // exclude git (default: all three)
-  brainbank: {                   // BrainBank constructor options
-    dbPath: '.brainbank/brain.db',
+Drop a `.brainbank/config.json` in your repo root. Every `brainbank index` reads it automatically — no CLI flags needed.
+
+```jsonc
+// .brainbank/config.json
+{
+  // Which built-in plugins to load (default: all three)
+  "plugins": ["code", "git", "docs"],
+
+  // Per-plugin options
+  "code": {
+    "embedding": "openai",         // use OpenAI embeddings for code
+    "maxFileSize": 512000
   },
-};
+  "git": {
+    "depth": 200                    // index last 200 commits
+  },
+  "docs": {
+    "embedding": "perplexity-context",
+    "collections": [
+      { "name": "docs", "path": "./docs", "pattern": "**/*.md" },
+      { "name": "wiki", "path": "~/team-wiki", "pattern": "**/*.md", "ignore": ["drafts/**"] }
+    ]
+  },
+
+  // Global defaults
+  "embedding": "local",            // default for plugins without their own
+  "reranker": "qwen3"
+}
 ```
 
-Everything lives in `.brainbank/` — DB, config, and custom indexers:
+**Embedding keys:** `"local"` (default, free), `"openai"`, `"perplexity"`, `"perplexity-context"`.
+
+**Per-plugin embeddings** — each plugin creates its own HNSW index with the correct dimensions. A plugin without an `embedding` key uses the global default.
+
+**Docs collections** — registered automatically on every `brainbank index` run. No need for `--docs` flags.
+
+**Custom plugins** — auto-discovered from `.brainbank/indexers/`:
 
 ```
 .brainbank/
 ├── brainbank.db        # SQLite database (auto-created)
-├── config.ts           # Optional project config
-└── indexers/           # Optional custom indexer files
+├── config.json         # Project config (optional)
+└── indexers/           # Custom plugin files (optional)
     ├── slack.ts
     └── jira.ts
 ```
 
-No folder and no config file? The CLI uses the built-in indexers (`code`, `git`, `docs`).
+Custom plugins can also have their own config section:
+
+```jsonc
+{
+  "plugins": ["code", "git"],
+  "slack": { "embedding": "openai" },   // matched by plugin name
+  "jira": { "embedding": "perplexity" }
+}
+```
+
+**Config priority:** CLI flags > `config.json` > auto-resolve from DB > defaults.
+
+> `.brainbank/config.ts` (or `.js`, `.mjs`) is still supported for programmatic config with custom plugin instances. JSON is preferred for declarative setups.
+
+No config file? The CLI uses all built-in plugins with local embeddings — zero config required.
 
 ---
 
@@ -556,19 +624,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;
@@ -584,7 +652,7 @@ export default {
       });
     }
   },
-} satisfies Indexer;
+} satisfies Plugin;
 ```
 
 ```bash
@@ -619,48 +687,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` |
 
 ---
 
@@ -668,7 +724,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: '.',
@@ -691,6 +747,50 @@ const brain = new BrainBank({
 | **Perplexity** | `PerplexityEmbedding` | 2560 (4b) / 1024 (0.6b) | ~100ms | $0.02/1M tokens |
 | **Perplexity Context** | `PerplexityContextEmbedding` | 2560 (4b) / 1024 (0.6b) | ~100ms | $0.06/1M tokens |
 
+#### How It Works
+
+BrainBank **auto-resolves** the embedding provider. Set it once → it's stored in the DB → every future run uses the same provider automatically.
+
+**Programmatic API** — pass `embeddingProvider` to the constructor:
+
+```typescript
+import { BrainBank, OpenAIEmbedding } from 'brainbank';
+
+const brain = new BrainBank({
+  repoPath: '.',
+  embeddingProvider: new OpenAIEmbedding(),  // stored in DB on first index
+});
+```
+
+**CLI** — use the `--embedding` flag on first index:
+
+```bash
+brainbank index . --embedding openai        # stores provider_key=openai in DB
+brainbank index .                            # auto-resolves openai from DB
+brainbank hsearch "auth middleware"           # uses the same provider
+```
+
+**MCP** — zero-config. Reads the provider from the DB automatically.
+
+> The provider key is persisted in the `embedding_meta` table. Priority on startup: explicit `embeddingProvider` in config > stored `provider_key` in DB > local WASM (default).
+
+**Per-plugin override** — each plugin can use a different embedding provider:
+
+```typescript
+import { BrainBank, OpenAIEmbedding } from 'brainbank';
+import { PerplexityContextEmbedding } from 'brainbank';
+import { code } from 'brainbank/code';
+import { git } from 'brainbank/git';
+import { docs } from 'brainbank/docs';
+
+const brain = new BrainBank({ repoPath: '.' })       // default: local WASM (384d)
+  .use(code({ embeddingProvider: new OpenAIEmbedding() }))              // code: OpenAI (1536d)
+  .use(git())                                                           // git: local (384d)
+  .use(docs({ embeddingProvider: new PerplexityContextEmbedding() }));  // docs: Perplexity (2560d)
+```
+
+> Each plugin creates its own HNSW index with the correct dimensions. The global `embeddingProvider` (or local default) is used for any plugin that doesn't specify one.
+
 #### OpenAI
 
 ```typescript
@@ -754,7 +854,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
 
@@ -777,7 +882,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
@@ -837,7 +942,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({
@@ -879,7 +984,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({
@@ -974,10 +1079,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.
 
 ---
 
@@ -987,7 +1094,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/
@@ -1021,9 +1128,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
 
@@ -1080,13 +1187,13 @@ BrainBank uses **native tree-sitter** to parse source code into ASTs and extract
 
 For large classes (>80 lines), the chunker descends into the class body and extracts each method as a separate chunk. For unsupported languages, it falls back to a sliding window with overlap.
 
-> Tree-sitter grammars are **optional dependencies**. If a grammar isn't installed, that language falls back to the generic sliding window. Install only the grammars you need: `npm install tree-sitter-ruby tree-sitter-go` etc.
+> Tree-sitter grammars are **optional dependencies** (except JS and TS, which are included). If you index a file whose grammar isn't installed, BrainBank throws a clear error with the exact `npm install` command. See [Tree-Sitter Grammars](#tree-sitter-grammars) for the full list.
 
 ### Incremental Indexing
 
 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 |
@@ -1242,7 +1349,7 @@ BrainBank's hybrid search pipeline (Vector + BM25 → RRF) with Perplexity Conte
 | Benchmark | Metric | Score |
 |---|---|:---:|
 | **BEIR SciFact** (5,183 docs, 300 queries) | NDCG@10 | **0.761** |
-| **Custom semantic** (127 docs, 20 queries) | R@5 | **83%** |
+| **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.
 
@@ -1287,7 +1394,7 @@ PERPLEXITY_API_KEY=pplx-... npx tsx test/benchmarks/rag/eval.ts --docs ~/path/to
 │                                                      │
 │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────────┐│
 │  │  Code   │ │   Git   │ │  Docs   │ │ Collection ││
-│  │ Indexer │ │ Indexer │ │ Indexer │ │ (dynamic)  ││
+│  │ Plugin  │ │ Indexer │ │ Indexer │ │ (dynamic)  ││
 │  └────┬────┘ └────┬────┘ └────┬────┘ └─────┬──────┘│
 │       │           │           │             │        │
 │  ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ ┌─────▼──────┐│
@@ -1337,7 +1444,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
@@ -1348,8 +1455,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
 ```