ProjectBrain (projectbrain-mcp v0.8.0)

Local-First 6D AST Coordinate Matrix, Pure SQLite Graph-as-Storage (.projectbrain.db), Polyglot Context Compiler, and Symbol-Anchored Patch Engine for AI Coding Agents.

Instead of forcing LLMs to search repositories as flat 1D text files (running rg/grep and reading dozens of overlapping read_file windows), ProjectBrain indexes your codebase across Python, TypeScript/JavaScript/React, Go, Rust, Java, and SQL into a 6D AST Coordinate Matrix and a Pure SQLite WAL Property Graph (.projectbrain.db) using pre-compiled tree-sitter C wheels—no external database daemon, no Docker, no cloud vector embeddings, and no API keys required:

• 6D AST Coordinate Matrix (X × Y × Z × W × E/T × C): Decomposes files and monolith components into atomic AST cells indexed across six orthogonal dimensions:
  • D1: X_scope (Lexical / Structural Scope): Outer function, class/struct/trait, switch/case branch, if/elif guard, useEffect[deps], or JSX conditional block.
  • D2: Y_role & Layer (D3): Behavioral role (STATE, EFFECT, ACTION, IO, VIEW, SCHEMA) and architectural layer (PRODUCTION vs. co-located TEST_SUITE).
  • D3: Z_write / Z_read (State & Storage Channels): Directional dataflow tracking which state variables, object attributes, and storage/DB keys each block mutates vs. reads.
  • D4: W_calls (Dyck-Constrained Call Graph): Outgoing function/method calls, HTTP route-to-handler bindings, and 1–3 hop interprocedural effect bubbling.
  • D5: E_exit & T_mode (Exception & Temporal Control-Flow): Tracks raise/throw/catch/HTTP status exits (4xx/5xx) and execution mode (SYNC | ASYNC | REACTIVE | TIMER).
  • D6: C_contract (Cross-Boundary Contract Verifier): Pre-commit verification of caller-callee arity & keyword obligations ([6D Caller Arity Contract Violation]), route/client payload keys, SQL NOT NULL schema constraints, and dialect mismatches.
• Pure SQLite WAL Graph-as-Storage (.projectbrain.db):
  • Stores vertices (graph_nodes WITHOUT ROWID), forward/reverse B-Tree adjacency lists (edges WITHOUT ROWID), sub-token BM25 inverted indices (fts_symbols FTS5), and content-addressed source code (source_blobs WITHOUT ROWID) in a single ACID database file.
  • Includes WITH RECURSIVE CTE multi-hop reachability in <6ms, Salsa-style interface_hash early-cutoff on body-only edits, and an in-memory Stacked Delta Overlay (temp.unified_symbols) for zero-disk dry-run verification.
• Single-Read Surgical Dossier & Context Compiler (projectbrain dossier / brain_context):
  • Uses Dyck-Constrained Sublinear ACL Push (PPR) + Submodular Concept-Coverage Selection to return exact target slices (with reversible -> expand: brain_slice <file>:<s-e> fold handles), 1-hop callee signature skeletons, Stack-Trace Crash Frame Pinning, and Greenfield Structural Sibling Exemplars.
• AST Symbol-Anchored Patch Engine (projectbrain patch / brain_patch):
  • Supports both line-anchored (@sub, @replace L<s-e>, @insert_after, @delete) and AST symbol-anchored (@replace_body <Symbol>, @add_method <ClassName>, @replace <Symbol>) directives with ±5 line drift auto-healing, lazy-elision rejection, dual Tree-sitter + Python compile() validation, and pre-commit caller arity checks.

Step-by-Step Setup Guide (60 Seconds)

Step 1: Install from PyPI

pip install projectbrain-mcp

(Alternatively, use pipx install projectbrain-mcp or uv tool install projectbrain-mcp.)

Verify both the CLI and MCP server binaries are available:

projectbrain --help
projectbrain-mcp --help

Step 2: Initialize Your Repository (One Command)

Run projectbrain init --hooks inside any repository (or pass --path and optional --ide {all,antigravity,claude,cursor,vscode}):

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

What projectbrain init --hooks does automatically:

1. Builds the Pure SQLite Graph-as-Storage Index: Writes .projectbrain.db (WAL mode).
2. Updates .gitignore: Ensures ephemeral index, dossier, and diff files stay out of Git.
3. Configures MCP Across IDEs: Writes/merges .mcp.json (Claude Code / Antigravity), .cursor/mcp.json (Cursor), and .vscode/mcp.json (VS Code Agent Mode).
4. Installs Agent Rules & PreToolUse Hooks: Writes AGENTS.md, CLAUDE.md, .cursor/rules/projectbrain.mdc, and .claude/settings.local.json PreToolUse guards.

Step 3: MCP Server Configuration (Standard or Lean 5-Tool Mode)

Add projectbrain-mcp to your MCP configuration (pass --lean or set PROJECTBRAIN_LEAN_MCP=1 to expose only the 6 core high-leverage tools and save ~2,900 tokens of tool-schema overhead):

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

Or run directly with uvx:

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

(Every MCP tool also accepts an optional repo_path argument per call for multi-repo workspaces.)

Daily CLI Workflow & Commands

1. Compile a Single-Read Engineering Dossier (dossier / dossier --zoom)

projectbrain --path /path/to/repo dossier "recover from a panic in an HTTP handler and abort with 500"
projectbrain --path /path/to/repo dossier --zoom "how does JWT signature and exp claim verification work"

2. Surgically Slice Symbols or Line Ranges (slice)

projectbrain --path /path/to/repo slice --summary src/App.tsx:ProtectedRoute recovery.go:CustomRecoveryWithWriter

3. Apply AST Symbol-Anchored or Line-Anchored Patches (patch)

# AST Symbol-Anchored replacement (immune to line-number drift!)
projectbrain --path /path/to/repo patch --apply --spec "@file recovery.go
@replace_body Recovery
	return RecoveryWithWriter(DefaultErrorWriter)
@end"

# Intra-line substitution
projectbrain --path /path/to/repo patch --apply --spec "@file src/App.tsx
@sub L84 \`!profileCompleted\` -> \`isHydrated && !profileCompleted\`"

4. View Live ROI & Token Savings Dashboard (stats)

projectbrain --path /path/to/repo stats --summary

Blind Open-Source Repository Evaluation (v0.8.0)

Evaluated zero-shot across 4 unseen open-source production repositories spanning Python, TypeScript/JSX, and Go (encode/httpx, pallets/flask, honojs/hono, gin-gonic/gin — 670 files, 6,713 functions, 656 classes/structs, 5,074 6D cells, 12,046 graph nodes, and 35,627 edges) using natural-language prompts with zero function/method identifiers:

• Zero-Identifier Symbol Slice Recall (compile_context @ 2,500 token budget): 12 / 12 (100.0%)
• Top-5 File Localization Accuracy (file_acc_at_5): 12 / 12 (100.0%) (11 / 12 Top-1)
• AST Symbol-Anchored Patch Verification (@replace_body / @sub): 4 / 4 (100.0%)
• Token Compression vs. Matched File Reads: 80% – 91% reduction (4.2x – 6.0x fewer tokens vs. grep + 80-line window baseline)

Project Layout

projectbrain/
├── src/projectbrain/
│   ├── brain.py        # 6D Context Compiler, Dossier Engine, Slicer, Explorer & Contract Verifier
│   ├── store.py        # Pure SQLite WAL Graph-as-Storage (graph_nodes, edges WITHOUT ROWID, FTS5, source_blobs, Delta Overlay)
│   ├── slicer.py       # 6D Coordinate Matrix extractor, smart focus-window folding & signature skeletons
│   ├── patcher.py      # Two-Phase AST Symbol-Anchored & Line-Anchored Patch Engine + syntax/contract gates
│   ├── parsers.py      # Polyglot Tree-sitter CST codecs (Python, JS/TS/JSX/TSX, Go, Rust, Java, SQL)
│   ├── graph.py        # Multiplex CodeGraph, Dyck-Constrained Sublinear ACL Push (PPR) & Hub Damping
│   ├── ledger.py       # Page-accurate ROI & Token Savings Ledger (.projectbrain_ledger.json)
│   ├── memory.py       # Persistent AST-anchored repo memory (.projectbrain_memory.json)
│   ├── resolve.py      # Cross-file import & TypeScript path alias resolution
│   ├── frameworks.py   # Next.js, FastAPI, Flask, Express, Hono, Gin, Actix, Axum & Spring route inference
│   ├── cli.py          # CLI entry point (init --hooks, dossier, patch, slice, stats, compile, explore)
│   └── server.py       # FastMCP server entry point (standard 22-tool and --lean 6-tool modes)
├── tests/              # 192 unit, integration, security, and benchmark threshold tests
└── eval/               # Polyglot scale benchmark, self-dogfooding & zero-identifier adversarial harness