brainbank 0.5.0 → 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)
@@ -88,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
@@ -178,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
 
@@ -235,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 |
@@ -251,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())
@@ -302,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),
 });
 
@@ -318,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',
@@ -335,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'];
     },
@@ -357,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
@@ -424,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
@@ -442,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:
 
@@ -457,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',
@@ -469,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
 ```
 
@@ -494,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`).
 
 ---
 
@@ -556,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;
@@ -584,7 +613,7 @@ export default {
       });
     }
   },
-} satisfies Indexer;
+} satisfies Plugin;
 ```
 
 ```bash
@@ -619,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` |
 
 ---
 
@@ -668,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: '.',
@@ -754,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
 
@@ -777,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
@@ -837,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({
@@ -879,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({
@@ -974,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.
 
 ---
 
@@ -987,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/
@@ -1021,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
 
@@ -1086,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 |
@@ -1242,11 +1266,23 @@ 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.
 
-See **[BENCHMARKS.md](./BENCHMARKS.md)** for full pipeline progression, per-technique impact, and reproduction instructions.
+#### 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
 
@@ -1287,7 +1323,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 +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
@@ -1348,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
 ```

package/dist/{base-DZWtdgIf.d.ts → base-B_vJSAbj.d.ts}

@@ -521,12 +521,12 @@ declare class Collection {
 }
 
 /**
- * BrainBank — Indexer System
+ * BrainBank — Plugin System
  *
- * Indexers are pluggable strategies that scan external data sources
- * and push content into BrainBank. Built-in indexers handle code,
+ * Plugins are pluggable strategies that scan external data sources
+ * and push content into BrainBank. Built-in plugins handle code,
  * git, and docs. Third-party frameworks (LangChain, etc.)
- * can implement custom indexers.
+ * can implement custom plugins.
  *
  *   import { BrainBank } from 'brainbank';
  *   import { code } from 'brainbank/indexers/code';
@@ -535,8 +535,8 @@ declare class Collection {
  *     .use(code({ repoPath: '.' }));
  */
 
-interface IndexerContext {
-    /** SQLite database (shared across all indexers). */
+interface PluginContext {
+    /** SQLite database (shared across all plugins). */
     db: Database;
     /** Embedding provider (shared). */
     embedding: EmbeddingProvider;
@@ -555,31 +555,31 @@ interface IndexerContext {
     /** Get or create a dynamic collection. */
     collection(name: string): Collection;
 }
-interface Indexer {
-    /** Unique indexer name (e.g. 'code', 'git', 'docs'). */
+interface Plugin {
+    /** Unique plugin name (e.g. 'code', 'git', 'docs'). */
     readonly name: string;
-    /** Initialize the indexer (create HNSW, load vectors, etc.). */
-    initialize(ctx: IndexerContext): Promise<void>;
-    /** Return stats for this indexer. */
+    /** Initialize the plugin (create HNSW, load vectors, etc.). */
+    initialize(ctx: PluginContext): Promise<void>;
+    /** Return stats for this plugin. */
     stats?(): Record<string, any>;
     /** Clean up resources. */
     close?(): void;
 }
-/** Indexers that can scan and index content (code, git). */
-interface IndexablePlugin extends Indexer {
+/** Plugins that can scan and index content (code, git). */
+interface IndexablePlugin extends Plugin {
     index(options?: any): Promise<any>;
 }
-/** Indexers that can search indexed content (docs). */
-interface SearchablePlugin extends Indexer {
+/** Plugins that can search indexed content (docs). */
+interface SearchablePlugin extends Plugin {
     search(query: string, options?: any): Promise<SearchResult[]>;
 }
-/** Indexers that support file watch mode. */
-interface WatchablePlugin extends Indexer {
+/** Plugins that support file watch mode. */
+interface WatchablePlugin extends Plugin {
     onFileChange(filePath: string, event: 'create' | 'update' | 'delete'): Promise<boolean>;
     watchPatterns(): string[];
 }
-/** Indexers that manage document collections. */
-interface CollectionPlugin extends Indexer {
+/** Plugins that manage document collections. */
+interface CollectionPlugin extends Plugin {
     addCollection(collection: DocumentCollection): void;
     removeCollection(name: string): void;
     listCollections(): DocumentCollection[];
@@ -590,4 +590,4 @@ interface CollectionPlugin extends Indexer {
     listContexts?(): any[];
 }
 
-export { type SearchResultType as A, type BrainBankConfig as B, Collection as C, type DocumentCollection as D, type EmbeddingProvider as E, type SearchablePlugin as F, type GitCommitRecord as G, HNSWIndex as H, type Indexer as I, isCodeResult as J, isCollectionResult as K, type LearningPattern as L, isCommitResult as M, isDocumentResult as N, isPatternResult as O, type ProgressCallback as P, matchResult as Q, type ResolvedConfig as R, type StageProgressCallback as S, type VectorIndex as V, type WatchablePlugin as W, type IndexResult as a, type SearchResult as b, type ContextOptions as c, type CoEditSuggestion as d, type IndexStats as e, type SearchHit as f, type CodeChunk as g, Database as h, type Reranker as i, type CodeResult as j, type CodeResultMetadata as k, type CollectionAddOptions as l, type CollectionItem as m, type CollectionPlugin as n, type CollectionResult as o, type CollectionSearchOptions as p, type CommitResult as q, type CommitResultMetadata as r, type DistilledStrategy as s, type DocChunk as t, type DocumentResult as u, type DocumentResultMetadata as v, type IndexablePlugin as w, type IndexerContext as x, type PatternResult as y, type PatternResultMetadata as z };
+export { type SearchResultType as A, type BrainBankConfig as B, Collection as C, type DocumentCollection as D, type EmbeddingProvider as E, type SearchablePlugin as F, type GitCommitRecord as G, HNSWIndex as H, type IndexResult as I, isCodeResult as J, isCollectionResult as K, type LearningPattern as L, isCommitResult as M, isDocumentResult as N, isPatternResult as O, type Plugin as P, matchResult as Q, type ResolvedConfig as R, type StageProgressCallback as S, type VectorIndex as V, type WatchablePlugin as W, type ProgressCallback as a, type SearchResult as b, type ContextOptions as c, type CoEditSuggestion as d, type IndexStats as e, type Reranker as f, type SearchHit as g, type CodeChunk as h, Database as i, type CodeResult as j, type CodeResultMetadata as k, type CollectionAddOptions as l, type CollectionItem as m, type CollectionPlugin as n, type CollectionResult as o, type CollectionSearchOptions as p, type CommitResult as q, type CommitResultMetadata as r, type DistilledStrategy as s, type DocChunk as t, type DocumentResult as u, type DocumentResultMetadata as v, type IndexablePlugin as w, type PatternResult as x, type PatternResultMetadata as y, type PluginContext as z };

package/dist/chunk-424UFCY7.js

@@ -0,0 +1,78 @@
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/providers/embeddings/local-embedding.ts
+var LocalEmbedding = class {
+  static {
+    __name(this, "LocalEmbedding");
+  }
+  dims = 384;
+  _pipeline = null;
+  _modelName;
+  _cacheDir;
+  constructor(options = {}) {
+    this._modelName = options.model ?? "Xenova/all-MiniLM-L6-v2";
+    this._cacheDir = options.cacheDir ?? ".model-cache";
+  }
+  _pipelinePromise = null;
+  /**
+   * Lazy-load the transformer pipeline.
+   * Singleton — created once and reused.
+   * Promise-deduped to prevent concurrent downloads.
+   */
+  async _getPipeline() {
+    if (this._pipeline) return this._pipeline;
+    if (this._pipelinePromise) return this._pipelinePromise;
+    this._pipelinePromise = (async () => {
+      const { pipeline, env } = await import("@xenova/transformers");
+      env.cacheDir = this._cacheDir;
+      env.allowLocalModels = true;
+      this._pipeline = await pipeline("feature-extraction", this._modelName, {
+        quantized: true
+      });
+      return this._pipeline;
+    })();
+    try {
+      return await this._pipelinePromise;
+    } finally {
+      this._pipelinePromise = null;
+    }
+  }
+  /**
+   * Embed a single text string.
+   * Returns a normalized Float32Array of length 384.
+   */
+  async embed(text) {
+    const pipe = await this._getPipeline();
+    const output = await pipe(text, { pooling: "mean", normalize: true });
+    return output.data;
+  }
+  /**
+   * Embed multiple texts using real batch processing.
+   * Chunks into groups of BATCH_SIZE to balance throughput vs memory.
+   */
+  async embedBatch(texts) {
+    if (texts.length === 0) return [];
+    const BATCH_SIZE = 32;
+    const pipe = await this._getPipeline();
+    const results = [];
+    for (let i = 0; i < texts.length; i += BATCH_SIZE) {
+      const batch = texts.slice(i, i + BATCH_SIZE);
+      const output = await pipe(batch, { pooling: "mean", normalize: true });
+      for (let j = 0; j < batch.length; j++) {
+        const start = j * this.dims;
+        results.push(output.data.slice(start, start + this.dims));
+      }
+    }
+    return results;
+  }
+  async close() {
+    this._pipeline = null;
+  }
+};
+
+export {
+  LocalEmbedding
+};
+//# sourceMappingURL=chunk-424UFCY7.js.map