ProjectBrain (projectbrain-mcp v0.8.5)


For a real bug or refactor, ProjectBrain gives your coding agent the exact symbols, callers, and dependencies it needs in 1 turn—with fewer wrong files and 77–89% fewer tokens.

Instead of forcing AI coding agents to explore repositories by running dozens of rg/grep searches and reading entire files line-by-line, ProjectBrain indexes your codebase locally into a SQLite WAL Code Graph (.projectbrain.db) using tree-sitter and structural parsers. No external database daemon, no Docker, no cloud vector embeddings, and no API keys required.

What It Actually Does

1. One-Turn Code Dossiers (projectbrain dossier / brain_dossier):
   • Given a bug report, stack trace, or feature prompt, ProjectBrain ranks relevant symbols using sub-identifier BM25 + call/import/state-flow graph traversal, automatically bridges passive schema/DTO and class/module config declarations (ConfigAttribute, ImmutableDict, SCREAMING_SNAKE_CASE constants) to their executable consumers, and returns exact code slices plus 1-hop caller/callee signatures in a single read.
2. Multi-Dimensional Program Slicing (projectbrain slice / brain_slice):
   • Slices exact functions, classes, methods, or line ranges (file.py:ClassName.method or file.py:120-160) across multiple files in a single call. When slicing large functions around a target variable or call, computes an AST/PDG slice across three orthogonal dimensions: backward data-dependence (def -> use), forward data-dependence (def -> use), and upward control-dependence guards (if/try/for/with), collapsing unrelated filler lines while preserving governing logic.
3. AST Symbol-Anchored Patching (projectbrain patch / brain_patch):
   • Applies surgical edits (@replace_body <Symbol>, @add_method <ClassName>, @replace <Symbol>, @sub L<n>) validated against Tree-sitter + language syntax compilers and caller arity contracts before touching disk, with automatic rollback on syntax errors.
4. .gitignore-Compliant Polyglot Indexing (29 File Extensions):
   • Honors root and nested .gitignore / .git/info/exclude rules automatically.
   • Supports Python, TypeScript, JavaScript, JSX/TSX, Vue, Svelte, Go, Rust, Java, Kotlin, Scala, C, C++, C#, Ruby, PHP, Swift, SQL, GraphQL, Prisma, and Protobuf.
5. Safe Output & Traceback Compression (projectbrain run / brain_run):
   • Folds passing test noise (pytest, jest/vitest, go test, cargo test), deduplicates repetitive log lines, and maps stack-trace file:line frames directly to enclosing functions and 1-hop callers. Direct shell execution over MCP is disabled by default unless explicitly opted in via PROJECTBRAIN_ALLOW_EXEC=1.

Quick Start (60 Seconds)

Step 1: Install

pip install projectbrain-mcp

(Or pipx install projectbrain-mcp / uv tool install projectbrain-mcp.)

Step 2: Initialize Your Repository (Non-Destructive)

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

What projectbrain init does safely (--ide auto by default):

1. Builds the SQLite Code Graph Index: Writes .projectbrain.db (WAL mode), honoring .gitignore.
2. Updates .gitignore: Appends ephemeral .projectbrain* cache patterns if not already present.
3. Writes Minimal Root Config by Default (--ide auto): Creates .mcp.json and AGENTS.md at the repo root, and only touches .cursor/, .vscode/, or .claude/ if those IDE directories already exist in your repo (pass --ide all to generate configs for all IDEs).
4. Appends Agent Rules Non-Destructively: Uses <!-- projectbrain:start --> ... <!-- projectbrain:end --> section markers in AGENTS.md, CLAUDE.md, .cursor/rules/projectbrain.mdc, and deep-merges .claude/settings.local.json PreToolUse hooks so existing team instructions and settings are never overwritten.

Step 3: MCP Server Configuration

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

Core CLI Workflow

# 1. Compile a 1-turn engineering dossier (target slices + callers + callees)
projectbrain --path /path/to/repo dossier "recover from a panic in an HTTP handler and abort with 500"

# 2. Slice multiple symbols or line ranges in one batch
projectbrain --path /path/to/repo slice src/App.tsx:ProtectedRoute recovery.go:CustomRecoveryWithWriter

# 3. Apply a syntax-verified, symbol-anchored patch
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 Suite (eval/)

Every retrieval, multi-hop graph traversal, closed-world claim verification, and scale benchmark in this repository can be reproduced locally with two commands:

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

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

1. Built-In Reproducible Harness Results (python eval/run_eval.py)

2. Blind Cold-Start Agent Benchmarks (Production Open-Source Repositories)

Measured head-to-head by spawning two isolated subagents simultaneously on unmodified open-source repositories (Naive Search Agent using rg/Select-String + read_file vs. ProjectBrain Agent starting completely cold with no pre-built .projectbrain.db index and zero file/symbol hints in the prompt):

A. paperless-ngx/paperless-ngx (4-Question Deep Architectural Audit — Cold Start)

B. Netflix/dispatch (879-File Repository — 3-Question Cold-Start Trace)

Project Layout

projectbrain/
├── src/projectbrain/
│   ├── brain.py        # Context Compiler, Dossier Engine, Slicer, Explorer & Contract Verifier
│   ├── store.py        # SQLite WAL Property Graph (.projectbrain.db), FTS5, and Delta Overlay
│   ├── slicer.py       # Statement/Symbol Slicer, Focus-Window Folding & Signature Skeletons
│   ├── patcher.py      # AST Symbol-Anchored & Line-Anchored Patch Engine + Syntax Verification
│   ├── parsers.py      # Tree-sitter & Structural Parsers (29 file extensions)
│   ├── graph.py        # Cross-File Call/Import Graph & Personalized PageRank Push
│   ├── ledger.py       # Session Token & ROI Telemetry Ledger
│   ├── memory.py       # AST-Anchored Repository Notes (.projectbrain_memory.json)
│   ├── resolve.py      # Cross-File Import & TypeScript Path Alias Resolution
│   ├── frameworks.py   # Route Inference (Next.js, FastAPI, Flask, Express, Hono, Gin, Actix, Spring, ASP.NET)
│   ├── cli.py          # CLI Entry Point (init, dossier, slice, patch, verify, run, stats)
│   └── server.py       # FastMCP Server Entry Point (standard and --lean modes)
├── tests/              # 194 Unit, Integration, Security, and Benchmark Threshold Tests
└── eval/               # Reproducible Evaluation & Scale Benchmark Harnesses