cuhk-aim-group/neurodiscovery

📖 Overview

NeuroDiscovery is a closed-loop framework for evidence-grounded neuroimaging autoresearch. It comprises a neuroscience knowledge graph, a hypothesis generator and NeuroRuntime, an agent-based execution platform.

The graph combines curated resources with source-linked literature evidence, preserving provenance, publication dates and evidence polarity. The generator constructs testable cross-domain hypotheses compatible with available data and analysis methods. NeuroRuntime tests selected hypotheses reproducibly on raw neuroimaging data; supported, contradicted and inconclusive outcomes guide subsequent research, separately from execution failures.

NeuroRuntime retains the project’s strengths in neuroimaging dataset and model adaptation, data processing and model configuration/execution. It ships with independent GUI and CLI interfaces for day-to-day use, and can also be installed as a reusable skill library inside agent projects such as OpenClaw, Hermes, and Claude Code.

NeuroDiscovery and research materials

This repository hosts NeuroDiscovery (formerly NeuroClaw) and related public resources. Existing directory and interface names, including neurooracle/, neurobench/, neuroclaw_environment.json, the neuroclaw host-agent skill and neuroclaw_academic_* MCP tools, are retained for compatibility.

Public materials have separate versions:

The linked NeuroClaw technical report describes an earlier project version. Its experiments and the public demo should be interpreted using their own version information, separately from the NeuroDiscovery manuscript.

---

🚀 Updates

• [2026.09.15]: NeuroDiscovery v1.0.0 brings a refreshed desktop interface, expanded model-provider support including Ollama Cloud, improved AutoResearch continuity, and three configurable hypothesis novelty modes (strict, novelty_first, weighted).
• [2026.06.20]: NeuroClaw now provides Windows and macOS desktop clients, while Linux remains supported through the repository and command-line/web workflows.
• [2026.05.23]: NeuroBench now covers both data processing and model training/evaluation.
• [2026.05.20]: 7 atoms × 15 canonical tasks + 4 mediation chains in neurooracle.atoms.
• [2026.05.15]: NeuroOracle launched: knowledge-graph explorer plus hypothesis engine with live demo at https://huggingface.co/spaces/zxcvb20001/NeuroOracle.
• [2026.05.06]: Added 19 dataset and modality skills with companion scripts; all 86 skills enforce unified metadata (layer, skill_type, dependencies); skill_loader DAG validation ensures dependency graph correctness.
• [2026.04.28]: Our technical report is now available on arXiv: https://arxiv.org/abs/2604.24696
• [2026.04.22]: v1.0 released. Stable release with improvements and full documentation.
• [2026.04.17]: Our project homepage is now live. Welcome to visit: https://cuhk-aim-group.github.io/NeuroDiscovery/
• [2026.04.08]: NeuroBench released for multi-agent neuroimaging workflow evaluation.
• [2026.04.02]: v0.1 released with complete NeuroClaw framework and core functionality.

✨ Key Features

🔄 Data-Aware Orchestration

• Dataset-Context Planning: Organize capabilities around dataset structure, metadata, and workflow stage instead of simply “which tool to call”
• Automatic Skill Recommendation: Users specify the target dataset, and NeuroRuntime recommends relevant skills and executable workflows
• Preprocessing Constraint Awareness: Dataset-specific modality availability and preprocessing requirements are considered during orchestration

Supported Dataset Overview

Access is not equivalent to anonymous download. See the verified access matrix for registration, DUA, review, fee, and current availability details.

🎯 Executability and Reproducibility

• Automatic Dependency Management: No manual installation needed; the system detects and resolves dependencies
• True Model Execution: Beyond sharing docs, it guides and executes model reproduction
• Environment Isolation: Virtual environments and containerization avoid system pollution
• Verifiable Processes: Complete logging and result tracking
• Shadow Checkpoints: Git-based filesystem snapshots for rollback and diff comparison without polluting the project repository
• Subagent Orchestration: Spawns specialized subagents (biostatistician, clinical neuroscientist, methodology expert) for multi-perspective task execution
• Reflective Learning: Automatic reflection on tool failures and task completion, with persistent memory for cross-session learning

🧠 End-to-End Research Coverage

• Literature Review: arXiv search, PubMed retrieval, academic resource integration
• Experiment Design: Evidence-grounded hypothesis generation, scientific literature analysis and methodology evaluation
• Data Processing: Multi-format conversion (DICOM ↔ NIfTI), automated preprocessing pipelines
• Model Execution: Run published research models, deep learning framework integration
• Result Visualization: Scientific data visualization, statistical chart generation
• Paper Writing: Auto-generated drafts, format standardization

🤝 Flexible Integration

• NeuroDiscovery provides standalone GUI and CLI workflows through NeuroRuntime, so researchers can use it directly without depending on another host project.
• skills/, materials/, USER.md, and SOUL.md can also be installed as a reusable skill library in existing agent systems such as OpenClaw, Hermes, and Claude Code.
• The bundled core/ engine provides an integrated agent loop, skill loader, and tool runtime for standalone deployments.
• Non-neuroscience connectors (WhatsApp, Telegram, Slack, calendar, e-commerce, SaaS auth) are disabled by default via core/config/features.json and can be re-enabled if needed.

---

🚀 Quick Start

Option 1. Desktop Client (recommended)

Download the latest Windows or macOS client from the GitHub Releases page. Existing release assets retain their original NeuroClaw filenames.

• Windows: use NeuroClaw Setup 0.2.1.exe for normal installation. The portable .exe is also available, but may take longer to start because it extracts the app first.
• macOS: use the .dmg or .zip build from the release assets.
• Open Settings to configure the model endpoint, runtime mode, Python path, FSL path, proxy, language, and text size.
• Open NeuroOracle from the sidebar. If the graph file is missing, the client can download it from Hugging Face.

Linux remains supported through the source repository, command-line workflow, and web interface.

Option 2. Run from Source

Requirements: Python >= 3.10 and Git. Conda/Mamba, CUDA/GPU tools, FSL, FreeSurfer, and dcm2niix are optional depending on the workflows you want to run.

git clone https://github.com/CUHK-AIM-Group/NeuroDiscovery.git
cd NeuroDiscovery
python installer/setup.py
python core/agent/main.py --web

Then open http://localhost:7080 in your browser.

Useful checks:

python installer/setup.py --check
python core/agent/main.py --web --port 8080 --host 0.0.0.0

Settings are saved to neuroclaw_environment.json. API keys can be passed at runtime with --api-key or provided through the configured provider environment variable.

Option 3. Install as a Host-Agent Skill

Use this path if you want Codex, Claude Code, Cursor, or another coding agent to use NeuroDiscovery’s neuroimaging skill library.

git clone https://github.com/CUHK-AIM-Group/NeuroDiscovery.git
cd NeuroDiscovery
python installer/install_agent_integration.py --target codex

Common targets:

The installed host-agent skill retains its compatibility name, neuroclaw. After installation, ask the host agent to use NeuroClaw or enter NeuroClaw mode for neuroimaging, NeuroOracle, NeuroBench, and autoresearch tasks.

Benchmark output files under materials/benchmark_results/ are historical run artifacts. See their coverage and scoring notes before comparing them with a newer task registry.

Benchmark Evaluation

The 500 neuroimaging execution tasks live under neurobench/. Each task directory contains a task.md instruction file, and task_atlas.json assigns every task to one of seven categories. NeuroBench remains the name used by the existing benchmark interface.

NeuroBench currently accepts these benchmark configurations:

• with-skills: the agent can use the skills loaded from skills/
• no-skills: the baseline run without skills
• with-skills + no-skills paired comparison: enable --benchmark-compare-skills to run both variants for the same task set

Benchmark scoring is handled separately with --score-benchmark: it reads reports in output/, applies a GPT-5.4 weighted rubric, and generates numeric scores for planning completeness, tool/skill reasonableness, and command/code correctness. For fairness, each task case is scored in one batch across all comparable models to reduce scoring-standard drift. Skill-call counts are recorded separately and used for efficiency analysis.

To score existing benchmark reports:

python core/agent/main.py --score-benchmark

To speed up scoring on larger runs:

python core/agent/main.py --score-benchmark --score-workers 8

Web benchmark mode

python core/agent/main.py --web --benchmark

CLI benchmark batch runner

python core/agent/main.py --benchmark

To run the paired skill comparison in CLI mode:

python core/agent/main.py --benchmark --benchmark-compare-skills

In CLI benchmark mode, NeuroRuntime will ask for:

• the benchmark directory path
• the benchmark model name

Then it will:

• read all task.md files recursively from that directory
• sort tasks alphabetically by task folder name
• run tasks one by one without asking for intermediate confirmation
• print progress in the terminal only
• save reports under output//, with one markdown report per case and run

The benchmark reports include the solution thinking, skills used, skill-call counts, and the commands or code that were used or suggested.

---

📁 Project Structure

NeuroDiscovery/
├── README.md / README_zh.md        # Project documentation
├── USER.md / SOUL.md               # User preferences and agent behavior guidelines
│
├── core/                           # NeuroRuntime execution platform
│   ├── agent/                      # CLI/Web agent entry points
│   ├── web/                        # FastAPI Web UI
│   ├── skill_loader/               # Reads skills/*/SKILL.md
│   └── config/                     # Feature toggles and runtime settings
│
├── installer/                      # Setup wizard and host-agent integration installer
│   ├── setup.py
│   ├── config_wizard.py
│   └── install_agent_integration.py
│
├── skills/                         # Skill library
│   ├── base skills                 # Environment, search, BIDS, Git, conversion
│   ├── interface skills            # Research idea, method design, experiments, writing
│   └── subagent skills             # Tool, model, dataset, and modality workflows
│
├── models/                         # Brain model adapters and training/evaluation scripts
├── neurooracle/                    # Knowledge graph and autoresearch pipeline
│
├── neurobench/                     # 500 neuroimaging execution tasks (T01-T500)
│
├── docs/                           # Project website pages
├── materials/                      # Research materials and benchmark outputs
│
└── LICENSE                         # License

---

🛠️ Skill Quick Reference

Tip: Click the ℹ️ icon on any skill card in the Web UI to view expanded documentation, usage examples, and recent execution logs.

Base Layer

Interface Layer (Task Orchestration)

Subagent Layer

Subagent skills in NeuroRuntime include four categories: tool, model, dataset, and modality.

Tool

Model

Workflow

Dataset

Modality

Legend: ✅ Implemented | 🏗️ In Development | ⏳ Planned

---

🙏 Acknowledgments

Thanks to:

• OpenClaw
• Hermes
• Claude Code
• Karcen/rs-fMRI-Pipeline-Tutorial
• nature-skills
• Open-source neuroscience tools community (MNE-Python, FreeSurfer, FSL, etc.)