A local-first hybrid RAG MCP server that indexes your Obsidian vault and your Git repos together. Hybrid BM25 + e5 retrieval with a Japanese tokenizer in the default install, MCP-native for Claude, Cursor, Claude Desktop, and any other MCP-compatible client.
Status: early prototype. Markdown-only today; PDF and code-AST chunking are on the roadmap. APIs and storage layout may change.
Landing page: https://0916shokichi-blip.github.io/bobrain/ — also browsable locally via
python3 -m http.serverfrom the repo root →http://localhost:8000/docs/.
What it is
Bobrain indexes multiple local directories into a single hybrid search layer (BM25 + dense embeddings, combined via Reciprocal Rank Fusion) and exposes a search_docs MCP tool so your AI client can retrieve relevant chunks across all of your personal knowledge sources at once.
Unlike existing RAG servers that focus on a single directory tree or require cloud embeddings, Bobrain:
- runs fully local with in-process ONNX embeddings (
multilingual-e5-large) - supports multiple independent root directories with namespace isolation
- ships Japanese-aware BM25 out of the box (MeCab via
fugashi + unidic-lite) - is designed for people whose knowledge lives in more than one place — an Obsidian vault and the README/docs folder of every active repo
Killer use case
Ask your AI:
"Where did I write about MCP chunking strategies — either in my notes or the code?"
and get a single ranked list spanning your Obsidian vault and your ~/code/ directory, cited by file path.
Install
Requires Python 3.12+.
# Recommended: install once, run from anywhere
pipx install bobrain
# Or run a one-shot without installing (uv 0.5+)
uvx bobrain --help
Or clone and develop locally:
git clone https://github.com/0916shokichi-blip/bobrain.git
cd bobrain
uv sync
First-run cost (set expectations)
| Step | Cost | Notes |
|---|---|---|
| Model download | ~2.2 GB | multilingual-e5-large ONNX weights, fetched once into ~/.bobrain/fastembed_cache/ |
| Memory peak | ~12 GB | e5-large runs on CPU (1024-dim, 24-layer). Expect a transient spike during embed |
| Indexing time | ~3–6 sec/chunk | CPU inference, Apple Silicon (sustained loads slow due to thermal throttling). ~1,000 chunks ≈ 60–90 minutes on the first run; subsequent runs only re-embed changed chunks (typically seconds for daily updates) |
| Disk after indexing | ~50 MB / 1,000 chunks | LanceDB columnar storage under ~/.bobrain/lancedb/ |
Subsequent bobrain index runs reuse the cached weights, but currently re-embed every chunk in the namespace (full rebuild — incremental hash-based diff is on the roadmap). bobrain watch is the only incremental path today.
Quickstart
# index a directory under a namespace
bobrain index ~/Documents/notes -n notes
# index a second namespace (they live side by side)
bobrain index ~/code/my-project -n code
# index multiple roots into one namespace in a single pass
bobrain index ~/vault ~/code/my-project -n combined
# quick CLI search (BM25 + vector hybrid)
bobrain search "how did I chunk markdown" -k 5
# cross-namespace filter
bobrain search "mcp server" --ns notes --ns code
# keep the index live while you edit (Ctrl+C to stop)
bobrain watch ~/Documents/notes -n notes
Excluding files with .bobrainignore
Drop a .bobrainignore at any indexed root (gitignore syntax) to exclude
private notes, scratch files, or whole subtrees:
# private/
private/
drafts/
# everything ending in .scratch.md
*.scratch.md
# negation re-includes a single file
!drafts/ship-this-one.md
Patterns from a .bobrainignore apply only inside its own directory subtree
(same semantics as .gitignore), so you can place a narrower one in a
subfolder. The built-in skip list (.venv, node_modules, .git, ...) is
always active and cannot be re-enabled via .bobrainignore.
(If you cloned the repo instead of installing, prefix every command with uv run.)
MCP client setup
Point your MCP client at the stdio server. If you installed via pipx:
{
"mcpServers": {
"bobrain": {
"command": "bobrain",
"args": ["serve"]
}
}
}
The bobrain command on PATH works the same way whether you installed from PyPI or from the git URL above.
Or, from a local clone:
{
"mcpServers": {
"bobrain": {
"command": "uv",
"args": ["run", "bobrain", "serve"],
"cwd": "/absolute/path/to/bobrain"
}
}
}
Then from Claude / Cursor / Claude Desktop you can call the MCP tools directly.
MCP tools
| Tool | What it does |
|---|---|
search_docs(query, top_k=5, namespaces=None) |
Hybrid (BM25 + vector) search across the local index. namespaces is an optional allow-list. |
list_namespaces() |
Lists each indexed namespace with its chunk and document counts. Use it to discover what's available before filtering search_docs. |
Roadmap
- Japanese-aware BM25 via MeCab (fugashi + unidic-lite)
- Upgrade embeddings to
multilingual-e5-large(query/passage prefix aware) - Incremental indexing with
watchdog(bobrain watch) - Indexing progress + per-phase wall times (
scan / embed / db-write / bm25) - Multi-root
bobrain index(combine vault + repo in one namespace) -
.bobrainignore(gitignore-style per-project exclusions) - PDF chunker via
pymupdf(dependency already in) - Markdown heading-aware chunker (today: fixed character window)
- Code AST-aware chunker (tree-sitter)
- LLM Wiki auto-detection (directories containing
CLAUDE.md + log.md + index.md) - Reranker integration (Voyage / Cohere)
- Pro tier with cloud sync and team sharing
License
MIT. See LICENSE.
Made by Bob — Avatar by Nano Banana Pro.
This is 1 of 8 tools by Bob. → other tools
Metadata
Release files for bobrain 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bobrain-0.3.0.tar.gz | 21.7 kB | Without provenance | Details for bobrain-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bobrain-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for bobrain-0.3.0-py3-none-any.whl |
Total release size: 48.1 kB
Release files / bobrain-0.3.0.tar.gz
| Download URL | bobrain-0.3.0.tar.gz |
|---|---|
| Size | 21.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ade6ee51a04b8794f427a76d7a717865d4952ea37425271fb3db703e8a7cb939
|
|
BLAKE2b-256 checksum How to use checksums |
f9de9cb0012f34138d61877994a05b7c39b759e9a1cac38a681e21a35d83d014
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / bobrain-0.3.0-py3-none-any.whl
| Download URL | bobrain-0.3.0-py3-none-any.whl |
|---|---|
| Size | 26.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e59e2f06f3b20c18c71aa7b343e857ebdf517ae57fac58c72956521f2226204e
|
|
BLAKE2b-256 checksum How to use checksums |
f2dd16728bef50bf6a441a0dab30893f362681e1d38824a395867ef5e28c49dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for bobrain 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.