ProjectBrain (projectbrain-mcp v0.8.7)


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, 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 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.

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 "trace POST /checkout to database validation"), where following imports, base classes, and helper methods across files takes 10–30 turns of manual search/read loops.
  • Reading specific methods inside large files (projectbrain slice django/db/models/sql/query.py:Query.build_filter) 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.7"

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 src/flask/app.py:Flask.wsgi_app

# 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 "checkout" reaches "validate_coupon"

Reproducible Evaluation & Scale Benchmarks (eval/)

All correctness, retrieval, claim-verification, and scale benchmarks in this repository can be run locally:

# 1. Retrieval precision/recall, multi-hop graph vs. grep baseline, claim verification, and zero-ID slicing
python eval/run_eval.py

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

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

Built-In Verification Suite Results (python eval/run_eval.py)

External Repository Benchmarks (pallets/flask & django/django, v0.8.7)

What Changed in v0.8.5 – v0.8.7 (From pallets/flask & django/django Sandbox Reviews)

1. Dossier Token Budget, Docstring Folding, and Visible PDG Provenance (v0.8.7):
   • Folded multi-line Python docstrings (> 3 lines) in dossier slices before budgeting max_lines, replaced verbose Markdown 6D tables and file skeletons with compact 1-line summaries on secondary files, and wired compute_multidim_program_slice directly into compile_dossier() with explicit # [PDG Slice: seeds=L.. | bwd_defs=L.. | fwd_uses=L.. | guards=L.. | vars=...] headers.
   • Across the 6-question pallets/flask benchmark, target function slice recall improved from 12 / 19 (v0.8.6) to 19 / 19 (21 / 21) while total dossier size dropped 49.3% (113 KB -> 57.28 KB, 2.73 KB per hit).
2. Compound Domain Term Splitting & State-Flow Dispatch Bridging (v0.8.7):
   • _extract_keywords() now splits glued compound identifiers ("errorhandlers" -> ["errorhandlers", "error_handler", "error", "handlers", "handler"]) and stems agentive nouns ("handler" -> "handle"), discounts docstring-only matches (teardown_appcontext), and bridges state_flow writers (register_error_handler) to readers (_find_error_handler) and their callers (handle_user_exception, handle_http_exception).
3. $O(\Delta)$ Incremental Graph & SQLite Updates (v0.8.7):
   • incremental_index() now updates _blobs, CodeGraph (update_files), and SQLite (apply_incremental with graph_delta) incrementally for only the modified files, and sorts Tree-sitter 0.23+ capture nodes deterministically so salsa_early_cutoff triggers reliably on body-only edits (cutting single-file edit latency on django/django from ~7.0 s to < 1.0 s).
4. Fixed Perpetual Graph Rebuild on Skipped/Vendored Files (I-02):
   • is_stale() and incremental_index() track _skipped alongside _index, preventing vendored/minified files from triggering repeated re-indexing.
5. Fast Cold-Start SQLite Slicing & Zero-Copy Graph Persistence (I-03):
   • projectbrain slice <Symbol> queries indexed symbols and files tables in .projectbrain.db directly before loading the full repository graph into memory.
6. Flask Tuple Route Methods, Scoped Contract Checks, and Pinned mcp (I-01, I-04, I-06, I-07):
   • _flask_methods parses tuple and set literals (methods=("GET", "POST")), .py pytest client.post(...) calls are excluded from frontend HTTP contract checks, mcp>=1.2.0,<2.0.0 is pinned, and the PyPI classifier is set to Development Status :: 4 - Beta.