Skip to main content
Bob

Bobrain

The answer you're searching for — you already wrote it, years ago.

CI

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.server from 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)

Source distribution for bobrain 0.3.0
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)

Table of built distributions (wheels) for bobrain 0.3.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page