Two indexes, both on your machine. A vector store that finds code by meaning, and a symbol graph that answers exactly who calls what.
brew install jcsoftdev/tap/project-brain The two brains
An assistant left alone with your repository greps for a string and misses everything phrased differently, or reads whole files until the context window gives out. Neither answers “what breaks if I change this”. project-brain builds both indexes, locally, and tells the assistant which one to reach for.
Files are chunked and embedded with a local Ollama model. Retrieval is by meaning, so “how does auth work” finds the middleware, the token parser and the session store — none of which contain the word you typed.
A WASM parser extracts every symbol and call edge into a local SQLite graph. Retrieval is exact: definitions, callers, callees, blast radius, shortest call path. No model involved, no approximation, sub-millisecond reads.
And it stays fresh on its own
Quick start
Nothing to host, nothing to sign up for, no key to paste. Everything below runs on your machine and stays there.
One self-contained binary. No Node, no Bun, nothing else at runtime — the runtime, the WASM grammars and the templates are all compiled in.
brew install jcsoftdev/tap/project-brain Detects every AI tool you have and registers the MCP server in each one. Also installs the brain-audit and brain-okf host skills.
project-brain setup Detects the stack, writes a CLAUDE.md with MCP routing instructions, installs a git commit hook, scaffolds module docs, and runs the first index.
project-brain init health is the command that tells you why, when semantic results come back
empty: it reports the embedding service, the index counts and how stale they are.
project-brain health MCP tools
The server ships routing instructions alongside the tools, so the model reaches for the exact one instead of defaulting to a semantic search for a structural question.
| Tool | What it does |
|---|---|
search_context | Conceptual lookup. Ranked snippets, each with a chunk_id. The one to use when you cannot name the symbol. |
expand_context | Full body of a chunk_id — cheaper than the assistant re-reading the whole file. |
| Tool | What it does |
|---|---|
search_code | Exact keyword search (BM25) over indexed code: identifiers, error strings, exact phrases. Works with no Ollama. |
| Tool | CLI | What it does |
|---|---|---|
find_symbol | project-brain find | Exact definition by name — path, line range, kind, signature. |
find_callers | project-brain callers | Every symbol that calls this one. Who depends on X. |
find_callees | project-brain callees | Every symbol this one calls. What X depends on. |
impact | project-brain impact | Blast radius — everything transitively affected if X changes. |
trace_path | project-brain trace | Shortest call path from A to B, as an ordered chain. |
repo_map | project-brain map | Token-budgeted overview ranked by PageRank over the call graph. |
| Tool | What it does |
|---|---|
get_architecture | Stack, modules, chunk and symbol counts in one call. Orientation before drilling in. |
list_modules / get_module | Browse the indexed structure by module and pull a module whole. |
add_knowledge | Persist a note or decision into the brain so it survives the session. |
manage_adr | Create or list Architecture Decision Records. Append-only — supersede, never edit. |
sync_project | Re-index changed files now, incrementally, hash-gated. |
check_health | Embedding service and index status — run it when results look empty or stale. |
What to ask it
You never name a tool — the routing instructions do that. These are the questions that steer it well.
What breaks if I change parseConfig?
impactthe full blast radius, before you touch it
How does authentication work here?
search_contextthe middleware, the token parser, the session store
Where is GraphStore defined?
find_symbolpath, line range, kind, signature
Who calls chargeCard?
find_callersevery dependent, exactly, no guessing
Summarize the store module
get_moduleevery chunk the module owns
Remember we use RRF for hybrid search
add_knowledgepersisted, and still there next session
Ollama powers semantic search only. The structural graph and the keyword index read
local files with no model at all, and search_context falls back to a
code-aware BM25 floor marked degraded rather than failing quietly.
project-brain init --no-embed brain-audit runs a whole-project audit — dead code, orphan UI, broken
flows, ranked by severity — answering “is this export dead?” with
find_callers instead of a guess from a grep. brain-okf writes a
knowledge concept and verifies its anchor first. Both are offered, never scheduled.
Knowledge bundles
No parser can recover the reasoning behind a decision, because it was never in the
AST. An Open Knowledge Format v0.2 bundle — committed Markdown with YAML
frontmatter — holds that half, anchored to real symbols. And okf audit
keeps the two honest: it fails CI on a broken anchor, or on a concept whose code
moved on without it.
project-brain okf init Install
Every channel ships the same artifact: a compiled binary with the runtime, WASM grammars
and templates embedded. project-brain update reads the binary’s own path to
work out which channel installed it, and prints the matching command rather than guessing.
| Channel | Command | Platforms | Upgrade |
|---|---|---|---|
| Homebrew | brew install jcsoftdev/tap/project-brain | macOS (Apple Silicon), Linux | brew upgrade project-brain |
| curl | curl -fsSL .../scripts/install.sh | sh | macOS (Apple Silicon), Linux x64/arm64 | re-run the installer |
| Registry | bun install -g project-brain | all, including Intel macOS and Windows | project-brain update |
| Scoop | scoop install project-brain | Windows — bucket not published yet | scoop update project-brain |
Intel macOS has no prebuilt binary. Homebrew and curl both refuse rather than hand you an arm64 binary — use a registry install there.
Free, MIT, and it never sends your code anywhere.
brew install jcsoftdev/tap/project-brain