megabrain

One call returns all the code related to a question
— explained like a senior engineer, with the real code spliced in.

megabrain is a local code-intelligence engine. It replaces minutes of file-by-file crawling — grep, read, explore-agent chains — with a single grounded answer. Index a repo once; every later question retrieves all the related code and stitches it into a walkthrough narrated by an LLM that can only point at code, never rewrite it — so nothing is hallucinated. Retrieval itself uses no LLM (~200 ms); the one LLM call just narrates.

Languages

Code is chunked over its real AST (the cAST split-then-merge recipe), so chunks are whole functions/classes with breadcrumbs — never arbitrary line windows.

Adding a language is a LangSpec entry + pip install tree_sitter_<lang> — a config entry in a registry, not a branch in the indexer. Import/call graph edges are built for Python and TS/JS today; other languages retrieve on dense+lexical signals (no graph needed for correctness).

Install

pip install megabrain                 # core: Python · TS/JS · Markdown
pip install 'megabrain[languages]'    # + Ruby · Go · Rust · PHP

From a clone, for development:

git clone https://github.com/bernatch22/megabrain.git && cd megabrain
pip install -e '.[languages]'
python3 -m pytest                      # offline test suite — no network, no key

Setup

One key, read from the environment (with a ~/.zshrc fallback):

export OPENROUTER_API_KEY=...          # embeddings + ask, all via OpenRouter

Everything runs through OpenRouter's OpenAI-compatible API, so any model works — pick per role by env (the defaults reproduce the validated stack):

export MEGABRAIN_EMBED_MODEL=perplexity/pplx-embed-v1-0.6b   # embeddings (default)
export MEGABRAIN_ASK_MODEL=qwen/qwen3-coder                  # ask narrator (default; ~5x cheaper than Haiku, on par)

Usage

megabrain index  ~/repo                                    # incremental (sha256), no daemon
megabrain ask    ~/repo "how does auth work end to end"    # walkthrough + real code (~6–20s)
megabrain ask    ~/repo/src/auth "how are tokens issued"   # scope to a sub-path (path-scope)
megabrain ask    ~/repo "how do I configure X" --docs      # explain the docs, not the code
megabrain query  ~/repo "request retry logic"              # raw code map, no LLM (~200ms)
megabrain get    ~/repo src/x.py --symbol Class.method     # one file or symbol
megabrain serve-api ~/repo --port 2134                     # long-running JSON API (warm state)

Path-scope: pass a sub-folder (~/repo/src/auth) to any of ask / query / get and retrieval is confined to files under it — the repo root (where the index lives) is auto-detected. Multi-repo works too: megabrain query ~/a/src,~/b "...".

Excluding files: build artifacts (node_modules, .venv, dist, …) are skipped by default. Add your own with megabrain index ~/repo --exclude generated --exclude '*.pb.go' or a persistent .megabrainignore at the repo root (one pattern per line; a bare name matches any path segment, a glob or path/ matches the repo-relative path):

generated/
vendor
*.min.js
docs/legacy

Provider flexibility — cloud, native, local, hybrid

Embeddings and chat can each point at any OpenAI-compatible endpoint. localhost servers (Ollama / LM Studio / vLLM) need no API key:

# native provider (e.g. A/B a model directly):
export MEGABRAIN_EMBED_BASE_URL=https://api.perplexity.ai/v1   # uses PERPLEXITY_API_KEY

# hybrid — local private embeddings + cheap OpenRouter narration:
export MEGABRAIN_EMBED_BASE_URL=http://localhost:11434/v1
export MEGABRAIN_EMBED_MODEL=embeddinggemma
export MEGABRAIN_EMBED_BATCH=8            # smaller requests for local servers

# fully local (decent GPU) — nothing leaves the machine:
export MEGABRAIN_CHAT_BASE_URL=http://localhost:11434/v1
export MEGABRAIN_ASK_MODEL=qwen3-coder:30b

Changing the embed model auto-triggers a full re-embed on the next index (or force it with --force), so vectors never silently mismatch. Local-stack benchmarks live in evals/LOCAL_MODELS.md.

How it works

A three-stage pipeline. Only ask calls an LLM — and only to narrate.

Because the model only emits citations and the engine splices code from disk, code cannot be hallucinated or rewritten.

MCP

Use it from Claude Code or any MCP client:

claude mcp add megabrain -- python3 -m megabrain.mcp_server

Tools: megabrain_ask (primary), megabrain_query, megabrain_get, megabrain_index — ask/query take an optional scope_path for sub-path retrieval. The server auto-refreshes a stale index before answering, so results always match disk.

HTTP API

serve-api keeps the index warm in memory and serves retrieval over HTTP (stdlib only — no framework). Embed it in an app, or front a docs site with real semantic search.

megabrain serve-api ~/repo --port 2134 [--host 0.0.0.0] [--cors https://site] [--no-llm]

Binds localhost by default (front it with a reverse proxy); --cors opts into a browser origin.

Design

Every choice below is backed by an internal golden set (30 verified queries):

Engine retrieval (internal golden set): R@1 0.86 · bundle_full 1.00 · p50 ~10 ms warm. SWE-bench Lite localization (no training): retrieval Acc@1 ≈ 0.52 / @5 ≈ 0.83 — on par with the trained CodeRankEmbed retriever.

Project layout

megabrain/   engine — chunkers, providers, embeddings, SQLite store, graph, indexer, query, ask, serve, cli, mcp_server
tests/       offline suite (no network/key/corpus) — run with `python3 -m pytest`
evals/       golden set + model bakeoffs (maintainer-side, private corpus)

_{MIT · github.com/bernatch22/megabrain}