ProjectBrain (projectbrain-mcp v0.8.9)


Local SQLite Code Graph, Program Slicer, and Syntax-Verified Symbol Patcher for AI Coding Agents.

ProjectBrain indexes a repository locally into .projectbrain.db (SQLite WAL + FTS5) using tree-sitter and language AST parsers. It gives CLI and MCP coding agents four concrete primitives in a single dependency-light package—with no external database server, no Docker, no cloud embeddings, and no API keys:

1. Program & Symbol Slicing (projectbrain slice / brain_slice):
   • Slices exact functions, classes, methods, CommonJS/prototype assignments (res.send, app.use), or line ranges (file.py:ClassName.method or file.py:120-160) directly from SQLite in < 20ms without loading full files into the context window.
   • For large functions sliced around a target variable or call, computes an AST/Program Dependence Graph (PDG) slice across three orthogonal dimensions: backward data dependence (def -> use), forward data dependence (def -> use), and enclosing control-flow guards (if/try/for/with), collapsing unrelated lines while keeping governing logic intact.
2. One-Turn Code Dossiers (projectbrain dossier / brain_dossier):
   • Given a bug report, stack trace, or architectural question, ranks relevant symbols using sub-identifier BM25 + call/import/state-flow graph traversal and returns class-qualified (ClassName.method) target code slices plus 1-hop caller/callee signatures in a single read.
3. Syntax-Verified Symbol Patching (projectbrain patch / brain_patch):
   • Applies symbol-anchored edits (@replace_body <Symbol>, @add_method <ClassName>, @replace <Symbol>, @sub <Symbol>) validated against Tree-sitter + language syntax compilers and caller arity contracts before touching disk, with automatic rollback on syntax errors and zero-change dry runs.
4. Closed-World Structural Verification (projectbrain verify / projectbrain_verify_claim):
   • Verifies structural claims (calls, reaches, imports, handles) with explicit evidence provenance (exact, import_resolved, candidate) and refuses to guess (UNKNOWN) when any traversed file has a syntax error or when a call goes through a dynamic local receiver (adapter.send(...)) whose type cannot be resolved statically.

Language-Support Tiers

ProjectBrain indexes 29 file extensions across three explicit capability tiers:

When to Use ProjectBrain vs. Plain grep

• When plain rg / grep is faster: Looking up a single literal string or constant when you already know the exact identifier name and just want matching line numbers.
• When ProjectBrain wins:
  • Multi-hop call and dispatch questions (e.g., "how are exceptions routed to error handlers" or "how are redirects handled and when is auth stripped"), where following imports, mixins, and helper methods across files takes multiple turns of manual search/read loops.
  • Reading specific methods inside large files (projectbrain slice django/db/models/sql/query.py:Query.build_filter or projectbrain slice res.send) without dumping a 2,500-line file into the prompt.
  • Safe symbol-anchored patching (projectbrain patch --apply) where line numbers have drifted or where syntax errors must be rejected before writing to disk.

Quick Start

1. Install

pip install "projectbrain-mcp>=0.8.9"

2. Initialize a Repository (Minimal & Non-Destructive)

projectbrain --path /path/to/your/repo init

• Honors .gitignore: Automatically respects root and nested .gitignore and .git/info/exclude rules.
• Minimal Default Setup (--ide auto): Creates .projectbrain.db (SQLite WAL), updates .gitignore, and writes .mcp.json and AGENTS.md at the repo root using non-destructive <!-- projectbrain:start --> ... <!-- projectbrain:end --> markers. Only writes .cursor/, .vscode/, or .claude/ configs if those directories already exist in your repository (or when --ide all / --ide claude is explicitly passed).
• Safe Execution Defaults: Direct shell execution over MCP (brain_run) is disabled by default unless explicitly opted in via PROJECTBRAIN_ALLOW_EXEC=1.

3. MCP Server Configuration

{
  "mcpServers": {
    "projectbrain": {
      "command": "projectbrain-mcp",
      "args": ["--lean", "/path/to/your/repo"]
    }
  }
}

4. Core CLI Commands

# 1. Slice exact symbols or line ranges (fast <20ms SQLite lookup on indexed repos)
projectbrain --path /path/to/repo slice Query.build_filter res.send should_strip_auth

# 2. Compile a 1-turn code dossier (target slices + callers + callees)
projectbrain --path /path/to/repo dossier "how are exceptions routed to error handlers"

# 3. Apply a syntax-verified, symbol-anchored patch (--apply to write, omit for dry-run diff)
projectbrain --path /path/to/repo patch --apply --spec-file patch.spec

# 4. Verify closed-world structural claims (calls, reaches, imports, handles)
projectbrain --path /path/to/repo verify "Session.send" calls "HTTPAdapter.send"

Reproducible Evaluation & Scale Benchmarks (projectbrain/eval/)

All correctness, retrieval, claim-verification, and external repository benchmarks can be run locally from the repository root:

# 1. Fixture regression guards, self-dogfooding, and zero-ID adversarial evaluation
python projectbrain/eval/run_eval.py

# 2. 200-file polyglot scale, incremental Salsa early-cutoff, FTS5, and recursive CTE latency benchmark
python projectbrain/eval/bench_scale.py

# 3. External repository benchmarks: pallets/flask, django/django, psf/requests, pallets/click, expressjs/express
python projectbrain/eval/bench_external.py --suite all

# 4. Full unit, integration, security, and regression test suite (202 tests)
pytest projectbrain/tests -q

1. Held-Out External Repository Benchmark (python projectbrain/eval/bench_external.py --suite heldout)

Tested on three open-source repositories across Python and CommonJS JavaScript (psf/requests, pallets/click, expressjs/express):

2. Tuned External Repository Benchmarks (pallets/flask & django/django)

(Note: pallets/flask and django/django were used during v0.8.5–v0.8.8 development to tune dossier token budgets, PDG slicing, and incremental indexing latency.)

3. Built-In Verification & Dogfooding Suite (python projectbrain/eval/run_eval.py)

Changelog (v0.8.5 – v0.8.9)

1. CommonJS / Prototype Method Indexing, Dynamic Dispatch Verification, and Held-Out Benchmarks (v0.8.9):
   • JS CommonJS & Prototype Indexing: _parse_js now indexes obj.method = function, chained assignments (res.contentType = res.type = function), Class.prototype.method = function, exports.foo = function, module.exports = function, and defineGetter(obj, 'prop', function), plus CommonJS require('./mod') symbol bindings. On expressjs/express, lib/response.js indexes 32 functions (up from 10), lib/application.js indexes 18 functions (up from 2), and res.send, app.use, and app.handle slice cleanly.
   • Dynamic Receiver Dispatch -> UNKNOWN in verify_claim: When a function calls .method() on a local variable or dynamic receiver (adapter.send(request) in Session.send), verify_claim("Session.send", "calls", "HTTPAdapter.send") now returns UNKNOWN (explaining that the dynamic receiver cannot be resolved statically) instead of a false REFUTED.
   • Class-Qualified Headers & Retrieval: All dossier headers and call-graph pointers now format methods as ClassName.method (eliminating ambiguous bare __init__ or bare convert headers), @typing.overload stubs are filtered during Python indexing, and eval/bench_external.py now includes a held-out benchmark suite across psf/requests, pallets/click, and expressjs/express.
2. Tree-sitter CST Program Dependence Graph (PDG) Slicing for JS/TS/Go/Rust/Java (v0.8.8):
   • Added _analyze_treesitter_cst_pdg so compute_multidim_program_slice uses real Tree-sitter Concrete Syntax Trees for .ts, .tsx, .js, .jsx, .go, .rs, and .java in addition to Python's ast module.
3. Dossier Token Budget, Docstring Folding, Visible PDG Provenance, and $O(\Delta)$ Incremental Graph Updates (v0.8.7):
   • Folded multi-line Python docstrings (> 3 lines) in dossier slices, wired compute_multidim_program_slice into compile_dossier() with # [PDG Slice: ...] banners, and added incremental CodeGraph.update_files + SQLite graph_delta persistence.