🧠 BrainBank

Persistent, searchable memory for AI agents. Index your codebase, git history, documents, and any custom data into a single SQLite file — then search it all with hybrid vector + keyword retrieval.

BrainBank gives LLMs a long-term memory that persists between sessions.

• Pluggable — .use() only what you need: code, git, docs, or custom
• Hybrid search — vector + BM25 fused with Reciprocal Rank Fusion
• Dynamic collections — brain.collection('errors') for any structured data
• Pluggable embeddings — local WASM (free), OpenAI, or Perplexity
• Multi-process safe — concurrent CLI, MCP, and watch processes with automatic hot-reload
• Portable — single .brainbank/brainbank.db SQLite file
• Modular — lightweight core + optional @brainbank/* packages

Quick Start

npm i -g brainbank @brainbank/code @brainbank/git @brainbank/docs

[!IMPORTANT] Node 23+ users: @brainbank/code uses tree-sitter native bindings for AST parsing. On Node 23 and 24, V8 headers require C++20 but tree-sitter's binding.gyp defaults to C++17, causing the install to fail with "C++20 or later required.". Fix it by setting the C++ standard before install:

CXXFLAGS="-std=c++20" npm i -g brainbank

Node ≤22 is unaffected — prebuilt binaries are available and no compilation is needed.

If you get ERESOLVE errors, use npm i --legacy-peer-deps — tree-sitter grammars have overlapping peer dep ranges.

CLI — zero code

brainbank index .                          # scans repo → interactive select → index
brainbank index . --yes                    # skip prompts, auto-select all
brainbank hsearch "rate limiting"           # hybrid search
brainbank kv add decisions "Use Redis..."   # store a memory
brainbank kv search decisions "caching"     # recall it

Programmatic API

import { BrainBank } from 'brainbank';
import { code } from '@brainbank/code';
import { git } from '@brainbank/git';

const brain = new BrainBank({ repoPath: '.' })
  .use(code())
  .use(git());

await brain.index();

const results = await brain.hybridSearch('authentication middleware');

const log = brain.collection('decisions');
await log.add('Switched to argon2id for password hashing', { tags: ['security'] });

brain.close();

Packages

brainbank is the core framework — strictly plugin-agnostic. Plugins are separate @brainbank/* packages that own their database schema, search strategies, and context formatting. Install only what you need:

Indexer Plugins

Data sources that feed into BrainBank's hybrid search engine. Each plugin manages its own tables via the built-in migration system.

| Package | Description | Install | |---------|-------------|----------| | @brainbank/code | AST chunking, import graph, symbol index (20 languages) | npm i @brainbank/code | | @brainbank/git | Git history indexing + co-edit analysis | npm i @brainbank/git | | @brainbank/docs | Document collection search with smart chunking | npm i @brainbank/docs |

Integrations

Extensions that connect BrainBank to external tools and workflows.

| Package | Description | Install | |---------|-------------|----------| | @brainbank/mcp | MCP server for Antigravity, Claude, Cursor (read-only, 2 tools) | npm i @brainbank/mcp |

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Installation, quick start, first search | | CLI Reference | Complete command reference | | Plugins | Built-in plugins overview + configuration | | Collections | Dynamic KV store with semantic search | | Search | Hybrid search, scoped queries, context generation | | Custom Plugins | Build plugins + publish as npm packages | | Configuration | .brainbank/config.json, env vars | | Embeddings, Reranker & Pruner | Providers, benchmarks, per-plugin overrides, LLM noise filter | | Multi-Repo | Index multiple repositories into one DB | | MCP Server | AI tool integration (stdio), mcp:export setup | | Indexing | Code graph, incremental indexing, re-embedding | | Migrations | Plugin schema migrations, built-in schemas | | Architecture | System internals, data flows, design patterns |

Examples

| Example | Description | |---------|-------------| | notes-plugin | Programmatic plugin — reads .txt files | | custom-plugin | CLI auto-discovery plugin | | custom-package | Standalone npm package scaffold | | collection | Collections, search, tags, metadata | | rag | RAG chatbot — docs retrieval + generation ¹ |

¹ Requires OPENAI_API_KEY. RAG also requires PERPLEXITY_API_KEY.

Benchmarks

Early benchmarks on Apple Silicon — single SQLite file, no external vector DB.

| Benchmark | Corpus | Metric | Score | |-----------|--------|--------|:-----:| | BEIR SciFact | 5,183 scientific abstracts, 300 queries | NDCG@10 | 0.761 | | Custom RAG eval | 127 Pinecall.io docs, 20 queries — 1 miss | R@5 | 83% |

Pipeline progression — each stage's impact on the custom eval:

| Stage | R@5 | Δ | |-------|:---:|---| | Vector-only (HNSW) | 57% | — | | + BM25 → RRF | 78% | +21pp | | + Qwen3 reranker | 83% | +5pp |

More benchmarks (code+graph retrieval, large-scale stress tests, multi-provider comparisons) are in progress. Full methodology and reproduction commands → docs/benchmarks.md

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT