Project Brain

A persistent intelligence layer for AI coding agents.

Project Brain builds a semantic understanding of your codebase and provides context to AI coding agents. It indexes your project structure, symbols, dependencies, workflows, and architecture to enable intelligent code navigation and context-aware assistance.

Features

• Code Intelligence: Analyzes source code to extract symbols, relationships, and dependencies
• Knowledge Indexing: Builds a structured knowledge base from your codebase
• RAG-Based Context: Retrieves relevant context using vector search
• MCP Integration: Exposes a Model Context Protocol server for AI agent integration
• Incremental Sync: Tracks changes and syncs knowledge incrementally
• Impact Analysis: Determines what would be affected by code changes
• Workflow Tracing: Discovers and traces feature workflows across the codebase

Installation

npm install -g project-brain-cli

Quick Start

# Initialize Project Brain in your project
project-brain init

# Scan the repository and create a project inventory
project-brain study

# Check the current status
project-brain status

# Incrementally sync after code changes
project-brain sync

# Start the MCP server for AI agent integration
project-brain mcp

Commands

| Command | Description | |---------|-------------| | init [options] | Initialize Project Brain in the current repository | | study [options] | Scan the repository and create a project inventory | | status | Show Project Brain status | | analyze [options] | Analyze source code and build code intelligence | | explain <query> | Explain a module or symbol from project knowledge | | knowledge [options] | Build project knowledge from code intelligence | | explain-module <module> | Explain a module using project knowledge | | index [options] | Build the RAG index for vector search | | sync [options] | Incrementally sync project knowledge | | watch [options] | Watch for changes and sync automatically | | ask [options] <query> | Ask a question about the codebase | | impact [options] <symbol> | Analyze the impact of changing a symbol | | trace-workflow [options] <query> | Trace how a feature/workflow works | | context [options] <task> | Build minimal sufficient context for a task | | eval [options] | Benchmark Project Brain context quality | | mcp [options] | Start the MCP server |

MCP Tools

When running project-brain mcp, the following tools are exposed:

• project_overview - Get project technology, modules, and statistics
• search_project - Search for symbols and files
• get_symbol - Get detailed information about a symbol
• find_references - Find all references to a symbol
• find_dependencies - Find dependencies of a symbol
• explain_module - Get an explanation of a module
• get_architecture - Get project architecture information
• build_context - Build minimal context for a task
• impact_analysis - Analyze the impact of changing a symbol
• trace_workflow - Trace a workflow through the codebase

Configuration

Project Brain creates a .project-brain/ directory in your project root to store configuration and indexed data. This directory should be added to your .gitignore.

Supported Languages

• TypeScript (.ts, .tsx)
• JavaScript (.js, .jsx)

Privacy & Security

• No data is sent to external servers by default
• All processing happens locally
• No API keys or credentials are stored in the project
• Secrets in code are automatically redacted from the knowledge base

Development

# Install dependencies
npm install

# Run typecheck
npm run typecheck

# Run tests
npm test

# Build for production
npm run build

# Run in development mode
npm run dev

License

MIT