Project Brain

Project Brain is an AI-native engineering system designed to serve as a central layer of memory, navigation, impact analysis, and context preparation for other AI agents (such as Claude Code, Codex, and Antigravity) working on large codebases.

Current release: 0.9.0 (tournament-sandbox).

Instead of replacing execution tools, Project Brain operates as a reasoning and indexing layer above the codebase, ensuring agents have a stable map of the project, understand cross-component dependencies, and maintain historical context.

1. What Project Brain Resolves

• Navigation Degradation: Prevents agents from getting lost in large codebases.

• Impact Blindness: Reduces cases where changes in one surface (e.g., backend API) silently break others (e.g., Android app, web portal).

• Context Bloat: Prepares task-specific, highly relevant context packages rather than dumping large amounts of unneeded files into the prompt.

• Architectural Drift: Enforces rules and keeps track of past architecture and product decisions.

• Passive Memory: Generates evidence-bound proactive insights instead of acting like a static knowledge base.

Related MCP server: Axon

2. What Project Brain is NOT

• It is not a replacement for Claude Code, Codex, or Antigravity (they remain the "hands" that write code).

• It is not a replacement for Git, CI, or IDEs.

• It is not a general-purpose chat interface or a personal note-taking wiki.

• It is not a monolithic developer platform.

3. Quickstart (local, single user)

Runs on one machine with your own repositories. No API keys are needed to try it: the shipped .env.example uses mock LLM and embedding providers. The step-by-step guide with measured timings and troubleshooting is docs/release/0.9.0-rc1/INSTALL.md.

What runs where

Prerequisites

• Python 3.10+

• Docker with Docker Compose v2

• ~2 GB free RAM for the services

• Optional: Node.js 20+ for the web UI; postgresql-client (pg15) for backups

Steps

# 1. Get the code and install the package (registers the `brain` command)
git clone https://github.com/Perlitten/project-brain-public.git project-brain
cd project-brain
python3 -m venv .venv
source .venv/bin/activate            # Windows PowerShell: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

# 2. Configure
cp .env.example .env                 # Windows: copy .env.example .env
# Set TARGET_REPO_PATH to the repository you want indexed.

# 3. Start the storage services
docker compose up -d postgres redis neo4j

# 4. Preflight: python, .env, directories, provider keys, service health
brain doctor

# 5. Index a repository
brain index --repo /path/to/your/repo

# 6. Run the API (and, in a second terminal, the worker for background jobs)
uvicorn apps.api.main:app --port 8000
python -m brain.workers.worker

Check it:

curl http://127.0.0.1:8000/health
curl -H "X-API-Key: change-me-in-production" -H "Content-Type: application/json" \
     -d '{"repo_path": "/path/to/your/repo", "task_description": "add oauth login"}' \
     http://127.0.0.1:8000/context

API auth is on by default: every call needs X-API-Key equal to PROJECT_BRAIN_API_KEY in .env. Change that value before you expose the port anywhere.

Everything in Docker instead. docker compose up -d --build also builds and starts the api, worker and n8n containers. The containers see only the Project Brain checkout (/app); to index another repository from inside them, mount it into the api and worker services first.

Real models

Pick providers in .env, set the matching key, then re-index:

Embeddings from different providers are not comparable. After switching the embedding provider run brain embeddings verify and, if it reports incompatible vectors, brain embeddings backfill.

Tests

pytest tests/ -q      # hermetic: ignores provider keys in your .env
ruff check .

4. Web UI

The API serves JSON only. The human interface is a separate Next.js app in apps/web/ that reads the API server-side, so the API key never reaches the browser. Without an API configured it renders demo data.

cd apps/web
npm ci
cp .env.example .env.local     # BRAIN_API_URL=http://127.0.0.1:8000, BRAIN_API_KEY=<your key>
npm run dev                    # http://localhost:3100

Deploy to Vercel: import the repository, set Root Directory to apps/web (framework preset Next.js), add the variables above, deploy. Then set BRAIN_WEB_URL in the API's .env to the UI address: GET / advertises it and old /dashboard links redirect there. Any Node host works the same way with npm run build && npm run start.

5. CLI Usage

Once the package is installed in editable mode, the brain command-line executable is registered and available.

Version check without CLI dependencies:

python -m brain.version

Health Checks

To verify connection health across all local or remote database dependencies (PostgreSQL, Redis, Neo4j):

brain health

Auditing a Repository

To scan a target repository structure and compile the initial read-only codebase audit:

brain audit --repo <path_to_repository>

• Default behavior: If --repo is omitted, it uses REPO_ROOT from .env (defaults to the current project directory).

• Output: The scan generates a structured report at reports/initial-audit.md relative to the Project Brain root.

6. Memory Semantics

Explicitly historical Markdown remains searchable but is tagged as historical evidence and heavily demoted in ordinary current-state retrieval. A query that explicitly asks for history or archived context restores its normal retrieval weight. Decision memory is canonical by normalized title within an optional repo_path: recording the same title in the same scope updates that decision instead of creating another active instruction. Context packs include global decisions plus decisions owned by the requested repository, so one project's normative memory cannot leak into another project's task. Rules and decisions are read fresh for each context pack; only repository files and symbols use the process cache, so a write or revocation takes effect on the next delegated task without an API restart. Time-bound audit snapshots, archived design sources, and repository Task Contracts receive the same non-current authority treatment automatically; the live harness injects its exact active contract separately.

Brain Insights is a proactive inbox backed by the worker queue and the insights database table, shown in the web UI. Manual scans enqueue proactive_insights; scheduled scans can be imported through n8n.

7. Eval & Adversarial Verification

# Golden tasks against your target repository.
brain eval --repo <path-to-target-repo> --golden rules/golden_tasks.yaml

# Validate a golden task YAML file.
brain eval --repo <path-to-target-repo> --golden rules/golden_tasks.yaml --validate

Embedding integrity

brain embeddings status
brain embeddings verify --json
brain embeddings backfill              # sync pgvector + regenerate incompatible
brain embeddings backfill --pgvector-only  # JSON -> pgvector only

Proactive insights

# Queue a deterministic insight scan through the API.
curl -X POST http://localhost:8000/jobs/proactive-insights \
  -H "X-API-Key: $PROJECT_BRAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# List stored insights.
curl http://localhost:8000/insights -H "X-API-Key: $PROJECT_BRAIN_API_KEY"

By default, insight scans use deterministic checks only. To let the low-latency NVIDIA NIM route synthesize additional evidence-bound insights:

DEFAULT_LLM_PROVIDER=nvidia
NVIDIA_API_KEY=<secret>
LLM_TASK_INSIGHT_MODEL=meta/llama-3.1-8b-instruct
PROACTIVE_INSIGHTS_LLM_ENABLED=true

The LLM stage is bounded by PROACTIVE_INSIGHTS_MAX_SNAPSHOT_CHARS and PROACTIVE_INSIGHTS_TIMEOUT_S. If the model fails or times out, deterministic insights still run and the failure is reported in the job result.

External imports

# Grafify graph JSON -> Neo4j (uses GRAFIFY_OUTPUT_PATH or ../graphify-out/graph.json)
brain import grafify
brain import grafify --path ../graphify-out/graph.json

# Obsidian vault -> rules/decisions (requires OBSIDIAN_VAULT_PATH or --vault)
brain import obsidian --vault /path/to/vault

Browser automation (optional)

Project Brain does not control Cursor's embedded Simple Browser or the OS desktop. For optional local browser checks, a Playwright eval scaffold lives under eval/browser_automation/.

pip install -e ".[dev]"
playwright install chromium
python eval/browser_automation/smoke_test.py

Set BROWSER_HEADLESS=false in .env to watch the browser window. Platform limits (Computer Use, Cursor UI, Puppeteer vs Playwright) are documented in docs/tooling-gaps.md.

8. Production Deployment

Use DEPLOYMENT.md for the full git-safe self-host guide. It covers a fresh Ubuntu VPS, Docker Compose, nginx/TLS, n8n, repository mounts, indexing, smoke tests, MCP client setup, backups, and safety rules. Day-2 operations (release layout, upgrades, rollback) are in deploy/RUNBOOK.md and docs/release/0.9.0-rc1/UPGRADING_AND_ROLLBACK.md. The web UI deploys separately (section 4).

If an AI coding agent will do the deployment, start with AGENT_DEPLOYMENT.md. It is stricter than the human guide and includes command gates, failure playbooks, and a final report template.

The production compose file is docker-compose.prod.yml. It keeps Postgres, Redis, and Neo4j private to Docker, exposes the API and n8n on loopback only, and expects nginx to terminate public HTTPS.

Minimal server flow:

sudo mkdir -p /opt/project-brain
sudo chown -R "$USER:$USER" /opt/project-brain
git clone https://github.com/Perlitten/project-brain-public.git /opt/project-brain
cd /opt/project-brain

cp deploy/.env.prod.example .env
chmod 600 .env
# Fill BRAIN_PUBLIC_HOST, N8N_HOST, N8N_PUBLIC_URL, NVIDIA_API_KEY,
# BRAIN_TARGET_REPO_DIR, and BRAIN_INDEXED_PROJECTS_DIR.

bash deploy/server_up.sh

Do not commit .env, .secrets/, reports/, or context_packs/. .mcp.json is tracked but must stay secret-free: it carries ${VAR} references, never a literal BRAIN_API_KEY. BRAIN_API_KEY accepts either the shared PROJECT_BRAIN_API_KEY or a scoped pbk_ credential — prefer the scoped one: the remote MCP tools need core:write,jobs:read, and a per-agent key is revocable without rotating the shared secret (scripts/mint_api_credential.py --name <agent> --scopes core:write,jobs:read).

9. MCP Server

Project Brain ships with a Model Context Protocol (MCP) server exposing 10 tools:

search_code and ask_project accept an optional repo_path argument. Use it when multiple repositories are indexed, for example /indexed/forex-bot, so retrieval does not mix files from unrelated projects. The HTTP /search and /ask endpoints accept the same repo_path field. For the remote MCP server, BRAIN_REPO is used as the default repo scope when repo_path is omitted.

record_decision also accepts optional repo_path. Omit it only for a genuinely global control-plane decision. Repository task state and architecture should use the same canonical path passed to prepare_task_context.

record_rule follows the same scope rule. Context packs, Q&A, and diff review load only global rules plus rules matching the selected canonical repository.

Connecting an AI client

Local (stdio). The client starts the server itself; it reads the install's .env and talks to Postgres, Redis and Neo4j directly, so the storage services from the quickstart must be running.

# Claude Code (Windows: .venv\Scripts\python.exe)
claude mcp add project-brain -- /path/to/project-brain/.venv/bin/python -m apps.mcp_server.server

Other clients (Claude Desktop, Cursor) take the same command in their JSON config:

{
  "mcpServers": {
    "project-brain": {
      "command": "/path/to/project-brain/.venv/bin/python",
      "args": ["-m", "apps.mcp_server.server"],
      "cwd": "/path/to/project-brain"
    }
  }
}

Remote (HTTP). To use a deployed Brain from another machine, run apps.mcp_server.remote_server with BRAIN_API_URL, BRAIN_API_KEY and BRAIN_REPO set; no local datastores are needed. The tracked .mcp.json does exactly this from environment variables, and .mcp.json.example is the template for clients that keep their config elsewhere. Details: DEPLOYMENT.md, section 10.

MCP stdio E2E verification

python eval/mcp_stdio_e2e.py
# writes reports/mcp-stdio-e2e.json

Protocol rules for AI Agents (Antigravity / Claude Code / Codex)

Agents must respect these rules prior to modifying the main repository:

1. Before writing code: Invoke prepare_task_context to request the relevant files, tests, and architectural constraints.

2. Read the Context Pack: Analyze the generated context pack before initiating changes.

3. Minimize footprint: Do not modify files outside the context pack scope.

4. After editing: Invoke review_diff to run checks on generated diffs, checking for rule violations or untested files.

License

MIT © 2026 Andrei Damashkevich.

Project Brain builds on third-party libraries, fonts, container images and models that keep their own licenses — see THIRD_PARTY_NOTICES.md. Product names mentioned in this repository are trademarks of their owners; this is an independent project, not affiliated with any of them.