Project Brain

An inspectable memory and code intelligence layer for AI coding agents.

Project Brain connects repository code, architectural decisions, rules and lessons so an agent can request relevant project context across sessions and tools. You run the storage and inspect what it remembers.

Get started · Connect your agent · Try the demo · Documentation · Evidence and limitations

Real interface with synthetic example data. Screenshot values are illustrative, not benchmark results or measurements from your repositories.

Latest published release: v0.9.2. Downloadable Python artifacts include checksums and an SBOM. For the complete API, worker, dashboard and datastore setup, use the source workflow below.

The problem

An agent can read code without knowing which decisions are still valid, why a constraint exists, or what previous work learned. Those facts can be scattered across conversations, documents and tools.

Project Brain gives connected agents a shared source of repository context. It retrieves indexed code and recorded knowledge for a task, with evidence you can inspect. The agent still reads current source and runs the relevant checks.

Related MCP server: rpg-encoder

What it does

• Indexes code and maps dependencies. Search files, symbols and chunks; inspect graph relationships and likely change impact.

• Keeps repository-scoped knowledge. Record architectural decisions and rules without mixing unrelated projects.

• Links memory to evidence. Capture observations and lessons, inspect their supporting evidence, and review higher-risk promotions.

• Builds task context through MCP. Request relevant source and constraints from Codex, Claude Code, Cursor or another MCP-compatible client.

• Makes state visible. Inspect projects, indexing, code relationships, context packs and memory from the dashboard.

This is early software run by a trusted operator, built for one developer; an experimental team mode on main lets a small team of trusted people share one Brain. It complements your coding agent, Git and CI. It is not a multi-tenant service.

Quickstart

The recommended path is a source checkout on Linux, with Python 3.12, Docker Compose 2.24+ and Node.js 22 for the dashboard. macOS, WSL2 and native Windows have not been verified to the same standard; see platform support.

Run from a terminal on the machine that will host Brain:

git clone --branch v0.9.2 https://github.com/Perlitten/project-brain-public.git project-brain
cd project-brain
./scripts/bootstrap.sh
.venv/bin/brain index --repo "$PWD"
./scripts/start.sh

Bootstrap creates .venv and .env, generates local API secrets, installs the Python package, starts Postgres, Redis and Neo4j, and runs brain doctor. The index command reads Brain's own clean checkout as a first example. Start launches the API, worker and dashboard; keep that terminal open.

Open http://127.0.0.1:3100/setup. Check service health and the active repository, then connect an agent below. Press Ctrl+C to stop the API, worker and web app. Storage remains running until docker compose stop.

The default providers are mocks. This is a keyless installation smoke test; mock embeddings do not establish meaningful semantic retrieval. Configure real models before evaluating usefulness.

To use your own repository, pass its absolute path to bootstrap and indexing. Git repositories must have a clean committed tree. Ignored generated files are excluded; commit legitimate source changes before reindexing.

See Getting started for repository selection, model configuration, restart, troubleshooting and the first MCP task. Prebuilt GHCR containers remain experimental and are outside this recommended installation path.

Connect your agent

Local Lite profile (unreleased main)

In a checkout of main, install the Python package and open a terminal in your own repository. Lite uses SQLite, local graph adjacency and a durable local queue/cache; it starts no Docker containers or database daemons.

brain init --lite
brain index
brain mcp
# Optional local API and background maintenance worker:
brain serve --lite

brain mcp uses the saved .brain profile over stdio; point your MCP client at the absolute brain executable with argument mcp and your repository as cwd. Offline token-feature embeddings support identifier search; they do not provide learned semantic retrieval. Chat answers require an explicitly configured model. Lite supports bounded search/context/impact up to 50k chunks; advanced Cypher administration uses the full stack. See Lite setup. Initial indexing on main uses deterministic summaries without chat completions.

The local stdio server reads Brain's .env and connects directly to its storage services. Use the absolute path to the Python interpreter in the checkout you just installed:

claude mcp add project-brain -- /absolute/path/project-brain/.venv/bin/python -m apps.mcp_server.server

Other MCP clients use the same command and arguments; see the client configuration and tool reference. For a separately hosted instance, authenticated Streamable HTTP and the HTTP-backed stdio bridge are documented there and in Deployment.

A concrete first task

Ask your connected agent:

Use Project Brain's search_code for FileIndexer in this repository. Read the returned source, then use prepare_task_context for the task: "Explain how ignored generated files are excluded during reindexing." Include the relevant implementation, tests and any applicable decisions.

Pass the same absolute repo_path used by indexing. The result should point to source such as brain/indexers/file_indexer.py and its regression tests. This exercises a real MCP connection and inspectable code retrieval; it does not measure an improvement in coding outcomes.

After a change, an agent can request review_diff, record a scoped decision, or capture a lesson with its validation evidence. Tool access does not mean agents automatically call Brain in every session: configure your client workflow.

From one developer to a team

Experimental preview, main only, not in v0.9.2. Not piloted with real people. Optional OIDC SSO and an invitation UI are implemented; bounded execution of operator-allowlisted steps is available but off by default. Agent-chosen execution and automatic git merges are not supported.

A Brain starts as a team of one: with no team members registered, every authenticated caller (the shared PROJECT_BRAIN_API_KEY included) can use every indexed repository, and /health reports "mode": "solo". Boundaries switch on when the first verified member joins, by redeeming a single-use invitation or being added with brain team member add: the shared key is then refused, each repository is reachable through the project it is attached to, and member roles (reader, contributor, reviewer, administrator) decide who may search, propose knowledge or request runs. Invitations are created with the CLI or the team:admin API; there is no SSO and no invitation UI. In team state the dashboard signs each member in with their own key and sends it on every call, so Brain applies that member's roles.

The team mode walkthrough covers the whole path, from brain team init to revoking a member, with its known limitations. Stage and gaps: team-mode status; design: ADR: team collaboration.

See the product

Open the public, read-only demo. It contains synthetic projects and numbers, with no connected Brain API in the verified deployment. You can also inspect the screens locally after starting the app; Dashboard guide explains the views.

Code-map screenshot: synthetic example data, not a measured impact analysis.

See Demo safety and verification for the tested routes, deployment provenance, isolation checks and limits of the verification.

Architecture at a glance

flowchart LR
    Agent[AI coding agent] -->|MCP| Core[Python tools / API]
    UI[Next.js dashboard] -->|server-side authenticated API| Core
    Core --> PG[(Postgres + pgvector)]
    Core --> Graph[(Neo4j)]
    Core --> Queue[(Redis)]
    Worker[Background worker] --> PG
    Worker --> Graph
    Worker --> Queue
    Core -.-> Models[Configured model providers]
    Worker -.-> Models

Postgres stores the index, memory and durable jobs; Neo4j stores code relationships; Redis supports queueing, cache and worker liveness. The CLI and local MCP tools access the same core services. See Architecture and trust boundaries.

Self-hosted storage is not a local-only inference guarantee. External embedding providers receive code chunks; external LLMs receive selected code, knowledge and prompts. Connected agents have their own data policies. For local inference, configure both provider roles and review integrations and endpoints.

Evidence and limitations

Installation, indexing and MCP workflows have end-to-end smoke coverage. Python and web tests, migration checks, production-build checks, privacy gates and CodeQL run in CI. Evaluation guide separates functional verification from task-level experiments and retained historical evidence.

Improvements in coding correctness, task completion, time and total token cost are not established. Mock-provider checks are functional smoke tests. Benchmark evidence has limited scope and does not establish general superiority.

MCP sampling — legacy fallback, not a current feature: compatibility code may ask a sampling-capable client to answer from retrieved context when the server-side model fails. MCP sampling is deprecated by SEP-2577, not removed from supported versions. Brain's newer-protocol path uses input requests instead. Configure a server-side model for normal operation. Client support, approval and billing vary; this fallback is not independently verified across external clients.

Memory records reported validation; Brain does not prove every lesson's tests were executed. Eligible learned guidance can promote automatically, while higher-risk cases and distilled procedures have approval gates. Explicit rules and decisions are separate writes. Read the memory policy.

Documentation and contribution

Start with the documentation index. It separates current installation and operating guides from historical research and release records.

• Getting started and MCP

• FAQ, Memory and Roadmap

• Deployment and backup / restore

• Team mode walkthrough (experimental preview, main only)

• Contributing, issues and Code of conduct

• Security reporting and Changelog

License

MIT. Third-party libraries, fonts, container images and models keep their own licenses; see Third-party notices. This is an independent project, unaffiliated with the coding tools mentioned.