Brain Researcher

Exact historical reproducibility archive (not the v0.2.0 software release):

Brain Researcher is a workspace-centric infrastructure for auditable AI-assisted neuroimaging. It turns research questions into bounded episodes that connect evidence, admissible analysis choices, tool/recipe selection, provenance, and review verdicts. This public repository ships the open code, MCP contracts, service stack, Web UI, docs, and public-safe helpers; private benchmark corpora, Neo4j graph contents, internal run artifacts, and site-specific launchers are not included.

Choose your path

Public surface status

The v0.2.0 release contract uses the canonical status tokens stable, supported-local, experimental, deployment-specific, and historical. They describe what the public repository supports, not what a private or hosted deployment may add.

Reproducibility claims use a separate five-level vocabulary: inspectable means the committed evidence can be reviewed; integrity verified means its recorded checksums match; public runnable means the workflow can run from shipped or unrestricted public inputs; governed rerun means the rerun also needs access-controlled data or infrastructure; and fully reproduced means a completed rerun met its declared scientific tolerances. See the reproduction status vocabulary before interpreting a pack badge or verifier result.

Understand Brain Researcher

The storyboard below is a quick visual overview of the intended workflow: start with a research question, route planning and tools through MCP, connect KG evidence and neuroimaging recipes, then review the result before treating it as analysis output. For concrete services, paths, and setup commands, continue to the sections below.

For a more detailed walkthrough of the codebase, service boundaries, dependency graph, and file-linked architecture notes, read the Brain Researcher public DeepWiki generated by Devin.

What it does

• Plan → Recipe → Verify loop. Natural-language research questions become typed plans, MCP recipes, local/agent handoff prompts, and evidence-grounded reports. Hosted execution is deployment-specific and should be treated as unavailable unless runtime readiness, auth, data, and credits pass.
• Brain-researcher knowledge graph (BR-KG). Neo4j-backed graph linking concepts, brain regions, datasets, tasks, methods, papers, and tools. Supports multi-hop QA, hypothesis-candidate retrieval, behavior↔fMRI cross-modal queries.
• MCP tool surface. Planning, KG search, workflow recipes, run inspection, scientific review, deep research, and hypothesis workflows exposed via the Model Context Protocol for Claude Code, Codex, Cursor, or any MCP client. v0.2.0 maps to MCP contract epoch 2026-05-27 and ships 10 stable-tier tool contracts under contracts/tools/. Public compatibility claims are limited to these versioned contracts.
• Neuroimaging toolchain. Workflow recipes target Neurodesk containers (FSL, MRtrix3, SPM, ANTs, FreeSurfer, fMRIPrep, MRIQC, …) and Python packages such as Nilearn, MNE, NiMARE, and custom pipelines.
• SLURM-ready. Pluggable cluster profiles (configs/slurm/profiles/*.yaml) — easy to add your own.

Architecture (high level)

┌────────────────────────────────────────────────────────────────────────────┐
│                              Web UI  (Next.js)                              │
│  chat · studio · KG · dataset explorer · hypothesis · 3D brain viewer       │
└────────────┬──────────────────────────┬─────────────────────────────────────┘
             │                          │
             ▼                          ▼
   ┌────────────────────┐    ┌────────────────────┐     ┌───────────────────┐
   │   Orchestrator     │◀──▶│       Agent        │◀───▶│   MCP Server      │
   │  (FastAPI / SSE)   │    │ (LLM router +      │     │ stable public     │
   │ plans, runs, jobs  │    │   tool executor)   │     │  MCP contracts    │
   └────────┬───────────┘    └────────┬───────────┘     └─────────┬─────────┘
            │                         │                           │
            ▼                         ▼                           │
   ┌────────────────────┐    ┌────────────────────┐               │
   │     BR-KG API      │    │   Tool catalog     │◀──────────────┘
   │  (Neo4j-backed,    │    │ Nilearn / MNE /    │
   │ concepts · regions │    │ NiMARE / fMRIPrep /│
   │ · papers · tools)  │    │ Neurodesk modules  │
   └────────────────────┘    └────────────────────┘

For a deeper dive see docs/contract-tiers.md for the MCP surface contract and tests/architecture/test_import_boundaries.py for the import-boundary ratchet.

Where the important pieces live

Quick start (local Docker)

Brings up the default runtime stack: Neo4j + Redis + BR-KG + agent + web UI. Compose also runs a one-shot init-local-dirs job to prepare writable local data/ and logs/ subdirectories for non-root service containers. The orchestrator worker is optional and can be added with the worker profile.

git clone https://github.com/brain-researcher/brain-researcher-public.git
cd brain-researcher-public

# 1. Set required secrets, one LLM API key, and a matching DEFAULT_LLM_MODEL.
cp .env.example .env
# Edit .env and replace the required placeholders before continuing.

# 2. Validate the Compose model.
PUBLIC_HOSTNAME=localhost docker compose --env-file .env config --quiet

# 3. Build and start the default stack, then wait for health checks.
docker compose up -d --build --wait --wait-timeout 300

# 4. Verify: the init job exits 0 and runtime services are healthy.
docker compose ps --all
# → init-local-dirs (Exited 0)
# → neo4j, redis, br-kg, agent, web-ui   (Status: healthy)

# 5. Check the Agent, BR-KG, and Web UI HTTP surfaces.
bash scripts/smoke/health_smoke.sh

# 6. Open http://localhost:3000 in your browser.

Stop the local stack without deleting its volumes:

docker compose down

To build and start every compose service, including the optional orchestrator:

docker compose --profile worker up -d --build --wait --wait-timeout 300
docker compose --profile worker ps --all
# → init-local-dirs (Exited 0)
# → neo4j, redis, br-kg, agent, orchestrator, web-ui

Port collision? Override defaults via env vars:

BR_NEO4J_HTTP_PORT=7484 BR_NEO4J_BOLT_PORT=7697 BR_KG_PORT=5010 \
  AGENT_PORT=8010 ORCHESTRATOR_PORT=3011 WEB_UI_PORT=3010 \
  docker compose -p brpub up -d --build --wait --wait-timeout 300
docker compose -p brpub ps --all
BASE_AGENT=http://localhost:8010 BASE_NKG=http://localhost:5010 \
  BASE_UI=http://localhost:3010 bash scripts/smoke/health_smoke.sh

Open http://localhost:3010 for this alternate-port stack. When finished, stop the same Compose project without deleting its volumes:

docker compose -p brpub down

Minimal env vars (see docs/ENVIRONMENT_SETUP.md for full reference):

Generate local service secrets:

python3 - <<'PY'
import secrets

print("NEO4J_PASSWORD=" + secrets.token_urlsafe(24))
print("JWT_SECRET_KEY=" + secrets.token_urlsafe(48))
print("NEXTAUTH_SECRET=" + secrets.token_urlsafe(48))
PY

Then paste those values into .env, add one LLM provider key, and set DEFAULT_LLM_MODEL to a model served by that provider. Matching examples are in docs/ENVIRONMENT_SETUP.md. Official key pages:

• Gemini: https://aistudio.google.com/app/apikey
• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/settings/keys
• DeepSeek: https://platform.deepseek.com/api_keys
• Z.AI / GLM: https://docs.z.ai/guides
• OpenRouter: https://openrouter.ai/docs/api-keys
• OpenCode providers: https://dev.opencode.ai/docs/providers/

The default Brain Researcher runtime reads Gemini, OpenAI, Anthropic, or DeepSeek keys directly. Z.AI/GLM, OpenRouter, and OpenCode are included for external coding-agent or OpenAI-compatible gateway setups; configure those clients explicitly before relying on them for runtime calls.

Example .env fragment:

NEO4J_PASSWORD=replace_with_generated_value
JWT_SECRET_KEY=replace_with_generated_value
NEXTAUTH_SECRET=replace_with_generated_value

GEMINI_API_KEY=replace_with_key_from_google_ai_studio
DEFAULT_LLM_MODEL=gemini-3-flash-preview

Neo4j data boundary

The first boot brings up an empty Neo4j. The compiled BR-KG graph, Neo4j dumps, and internal graph-derived datasets are private and are not attached to GitHub Releases. Populate Neo4j only from private or local sources you are authorized to use.

Install as a Python package

The MCP server + CLI live under src/brain_researcher/. From the repository root, create an isolated Python 3.11 environment and install the base package:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
brain-researcher --help
brain-researcher-mcp --help

Install only the runtime profile you need: .[mcp], .[agent], or .[br-kg]. The .[all] contributor profile is intentionally heavy: it includes MCP, BR-KG, agent, neuroimaging, UI, notebook, and development dependencies. If you only want to run the public reproducibility examples, use their isolated setup commands instead of installing this full stack.

For exact tested versions, profile mappings, regeneration commands, and the fresh-venv smoke, see requirements/locks/README.md.

Core CLI surfaces (br is a short alias). If another installation shadows both console-script names, use python -m brain_researcher.cli.main from the activated, installed environment:

brain-researcher chat             # interactive chat; requires an LLM provider key
brain-researcher serve agent      # one foreground service per terminal
brain-researcher serve kg
brain-researcher serve mcp
brain-researcher serve web
brain-researcher db --help        # inspect database commands and prerequisites
brain-researcher data --help      # inspect the currently implemented data commands

For HPC / SLURM usage, see docs/hpc.md. For the contract layer that governs which tool names are stable across releases, see docs/contract-tiers.md and inspect contracts/tools/*.json.

Kubernetes / Helm (experimental)

The Helm chart and raw manifests under infrastructure/k8s/ are incomplete operator assets, not apply-ready deployment paths:

Run these inspection commands from the repository root with Helm installed:

# Helm chart (experimental/incomplete): render for syntax inspection only.
cp infrastructure/k8s/helm/brain-researcher/values.yaml /tmp/brain-researcher-values.yaml
helm template brain-researcher infrastructure/k8s/helm/brain-researcher/ \
  -f /tmp/brain-researcher-values.yaml > /tmp/brain-researcher-rendered.yaml
grep -E '^[[:space:]]*image:' /tmp/brain-researcher-rendered.yaml | sort -u

# Inventory the empty Secret key contracts in the raw manifest templates.
grep -RInE '^[[:space:]]*kind:[[:space:]]*Secret|^[[:space:]]*(data|stringData):' \
  infrastructure/k8s/manifests/

Do not apply the current Helm output to a cluster. Although helm template produces deterministic image references with fixed preview tags, the project does not publish or support the corresponding application images. The chart also emits no Secret resources and expects operator-supplied secret names and keys. Rendering validates the static contract only; it does not prove that the workloads can be pulled, started, secured, or kept healthy.

Do not run kubectl apply -f infrastructure/k8s/manifests/ on the public directory as shipped. Its Secret resources contain key contracts with empty values, including TLS and basic-auth inputs, and some resources require cluster CRDs such as cert-manager. If you maintain a raw-manifest deployment, copy the templates into a private deployment workspace, replace secrets through your secret-management workflow, verify the required CRDs, review a server-side dry run or diff against the intended cluster, and only then apply the reviewed files. The retained raw Istio manifests under infrastructure/k8s/istio/ are also experimental templates; the unsupported secondary Istio chart and install helpers were removed from the active tree.

The table above is the maintained repository map. For the current import-boundary ratchet, see tests/architecture/test_import_boundaries.py and tests/architecture/services_layer_baseline.txt. For public audit artifacts, start with docs/reproducibility_packs.md and reproducibility/README.md. Agent skills, templates, demos, adapters, and eval rubrics remain in the companion brain-researcher-agent-kit repository.

Citation

If you use Brain Researcher in published work, please cite:

@software{chen_2026_brain_researcher,
  author       = {Chen, Zijiao and {Brain Researcher contributors}},
  title        = {Brain Researcher: AI-assisted research infrastructure workspace for neuroimaging analyses},
  year         = {2026},
  version      = {0.2.0},
  url          = {https://github.com/brain-researcher/brain-researcher-public/releases/tag/v0.2.0}
}

No DOI is assigned here to the v0.2.0 software release. The version DOI 10.5281/zenodo.21282320 identifies the historical br-reproducibility-20260709.1 artifact archive, and the artifact-family concept DOI 10.5281/zenodo.21282319 resolves to the latest record in that independent, non-semver artifact family; it is not a fixed identifier for the archive above. Neither DOI is the DOI for software release v0.2.0. A machine-readable software citation lives in CITATION.cff, and the mapping is explicit in release/manifest.json. No paper or preprint identifier is claimed by this software citation.

Contributing

We welcome bug reports, feature ideas, case studies, and code contributions.

• Read first: CONTRIBUTING.md — dev workflow, codegraph-accelerated review, test conventions.
• Code of conduct: CODE_OF_CONDUCT.md.
• Security: report vulnerabilities privately per SECURITY.md; see also THREAT_MODEL.md for the MCP server attack surface. Runtime payload scrubbing is provided by br.redaction.
• Adding a new tool: see docs/how-to-add-tool.md for the workflow from @mcp.tool decoration through contract-layer inclusion.

For agent-policy templates (research / code-review / brain-researcher), see brain-researcher-agent-kit/agents/.

Acknowledgments

Brain Researcher builds on the work of many open-source neuroscience projects:

• Datasets and ontologies: OpenNeuro, BIDS, Cognitive Atlas, NeuroSynth, NeuroBagel, Allen Brain Atlas
• Toolchains: Nilearn, MNE-Python, NiMARE, fMRIPrep, MRIQC, FSL, Neurodesk
• Infrastructure: Model Context Protocol, Neo4j, Next.js, FastAPI

License

MIT — © 2026 Brain Researcher Team