ResearchBrain

English | 简体中文

ResearchBrain is a local-first scientific research knowledge workbench for Windows, providing an integrated workflow from raw materials to traceable research conclusions around literature discovery, collection, management, reading, parsing, retrieval, investigation, and citation.

It can either incrementally mirror Zotero items, collections, tags, and PDFs, or batch-import via DOI and discover literature through Crossref, OpenAlex, arXiv, PubMed, and other sources, obtaining full text from compliant open sources. Imported literature is deduplicated by identifiers such as DOI, PDFs can be read directly, and are converted to Markdown with page numbers and section anchors by MinerU or PyMuPDF; after vectorization of bibliographic records, abstracts, and full text separately, they can be used for local retrieval, local-first online supplementation, and comprehensive web research. Each response retains original text evidence, page numbers, or online sources; literature found online can continue to be imported into the library, historical sessions can be restored, and references can be exported as CSL-JSON, BibTeX, RIS, DOI lists, or Markdown, or handed over to clients like Codex via MCP.

Bibliographic records, PDFs, parsed outputs, vector indexes, and conversation history are saved locally by default; requests are only sent to external services when the user enables online discovery or invokes MiniMax or DeepSeek. The application runs independently on Windows 11 without requiring WSL, gbrain, Docker, or PostgreSQL.

Currently at 0.1.8 alpha. The core research loop is functional but is not yet a complete Zotero replacement.

Core Capabilities

• Local Literature Library: Independent library or Zotero read-only mirror; incrementally syncs bibliographic records, authors, collections, tags, and PDF attachments based on Zotero library version, and displays the vectorization status of abstracts and PDF full text separately.

• Identity and Incremental Determination: Identifies literature by normalized DOI/PMCID/PMID/arXiv, and PDFs by SHA-256; clearly distinguishes five states: bibliographic record only, abstract indexed, PDF saved, PDF parsed, and full text indexed.

• Literature Collection: Batch DOI, Crossref metadata, online discovery via Crossref/OpenAlex/arXiv/PubMed, multi-identifier deduplication, and import of records without DOI.

• Legal Full Text: Locates PDFs via Unpaywall, OpenAlex, PMC, and Crossref links with open licenses; also extracts PDFs from confirmed open landing pages; automatically falls back when candidates fail, and supports manual PDF attachment.

• PDF Parsing: MinerU preferred, PyMuPDF fallback; outputs Markdown, structured JSON, page numbers, sections, and figure/table locations.

• Local Retrieval: MiniMax embo-01 vectorizes bibliographic records, abstracts, and PDF full text simultaneously; LanceDB provides full-text, vector, and RRF fusion ranking; an empty library returns a clear ready-state message.

• Evidence-Based Q&A: Supports "local only", "local-first + online", and "comprehensive web research"; DeepSeek can only cite provided local or online evidence IDs.

• Continuous Conversation: All sessions, messages, and citations are permanently saved per library and can be restored; the current question has a retrieval weight of 1.0, recent questions have a context retrieval weight of 0.25, historical model answers are only used for context understanding, and evidence weight is always 0.

• Scholar Supplement: Can send search queries directly to Google Scholar in the browser, avoiding reliance on unstable page scraping.

• Literature Export: CSL-JSON, BibTeX, RIS, DOI lists, and Markdown.

• Agent Access: FastAPI, CLI, desktop application, and stdio MCP share the same SQLite and LanceDB data.

Related MCP server: surveyHelper

Design Boundaries

• The Zotero mirror is one-way read-only; it does not write back to zotero.sqlite, attachments, or collections.

• The Zotero Desktop Local API does not provide a delete record endpoint; additions, modifications, and new/replacement PDFs are incrementally synced, but items deleted in Zotero are not automatically removed from the mirror.

• Automatic full-text retrieval does not integrate Sci-Hub, LibGen, or any paywall circumvention services.

• PDFs, bibliographic records, vector libraries, and chat history remain on the local machine by default; when invoking MiniMax/DeepSeek, relevant text is sent to the selected service provider.

• The base installation package does not include MinerU models. PyMuPDF is used automatically when MinerU is not configured.

• 0.1.x does not include advanced bibliographic record editing, complex duplicate interactive merging, PDF annotation, or team collaboration.

See Privacy and Security Boundaries and Licensing Information.

Architecture

flowchart LR
  UI["Tauri + React"] --> API["FastAPI sidecar"]
  MCP["Codex / MCP client"] --> CORE["Shared services"]
  API --> CORE
  CORE --> DB["SQLite"]
  CORE --> IDX["LanceDB"]
  CORE --> OBJ["Content-addressed PDFs"]
  CORE --> ZOT["Zotero Local API"]
  CORE --> NET["Crossref / OpenAlex / arXiv / PubMed / Unpaywall"]
  CORE --> MODELS["MiniMax / DeepSeek"]

See the Architecture Document for architectural decisions, process models, and data ownership.

Running from Source

Prerequisites

• Windows 11 x64

• Python 3.11

• Node.js 20

• Rust stable MSVC

• Visual Studio C++ Build Tools, WebView2, and PowerShell 7 or Windows PowerShell

• It is recommended to install uv

git clone git@github.com:cacity/ResearchBrain.git
cd ResearchBrain

uv venv --python 3.11
uv sync --all-extras --group dev
$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -m researchbrain.cli init

cd desktop
npm ci
npm run tauri dev

To start only the local API and browser frontend:

$env:PYTHONPATH = "src"
.\.venv\Scripts\python.exe -m researchbrain.cli serve
cd desktop
npm run dev

The production desktop version randomly selects a loopback port and generates a 256-bit session token; the development API defaults to 127.0.0.1:8765, and Vite defaults to 127.0.0.1:1420.

Initial Configuration

1. In "Settings", fill in the contact email for Crossref, Unpaywall, OpenAlex, and PubMed.

2. Optionally fill in NCBI and OpenAlex API Keys for more stable online retrieval quotas.

3. Confirm the Zotero data directory, e.g., %USERPROFILE%\Zotero, and enable the local API in Zotero.

4. Save MiniMax and DeepSeek keys to Windows Credential Manager.

5. Optional: Install MinerU, and fill in the full path to mineru.exe in "Settings > Document Parsing".

6. Create a "Zotero Read-Only Mirror" library, click "Detect Zotero", then perform the initial sync; subsequent clicks on "Incremental Sync" only process bibliographic records and PDFs added or modified after the library version watermark.

7. View the number of new bibliographic records, PDFs, missing attachments, parses, and vectors in the sync statistics; the "Tasks" page allows batch retrying of failed tasks.

The default data directory is %LOCALAPPDATA%\ResearchBrain:

ResearchBrain/
  config/settings.json       # 不含密钥的设置
  data/library.sqlite        # 题录、任务、对话和出处
  data/lancedb/              # 可重建检索索引
  library/objects/           # SHA-256 内容寻址 PDF
  artifacts/                 # Markdown、JSON 和图表产物
  runtime/                   # 可回滚外部组件

Codex and MCP

After installing the desktop version, click "Register MCP" in "Settings > Codex", then create a new Codex task to call:

• list_libraries

• get_item

• search_library

• ask_library

• export_references

The source environment can also be run:

.\scripts\register_codex_mcp.ps1
codex.cmd mcp list

Testing and Building

.\.venv\Scripts\python.exe -m ruff format --check --no-cache src tests scripts
.\.venv\Scripts\python.exe -m ruff check --no-cache src tests scripts
.\.venv\Scripts\python.exe -m pytest -p no:cacheprovider
cd desktop
npm run typecheck
npm run format:check

Windows installer:

.\scripts\build_release.ps1

See the Development Guide, Release Guide, and GitHub Publishing Checklist for the complete development, testing, and release process.

Repository Structure

src/researchbrain/       Python 业务核心、API、CLI 和 MCP
desktop/src/             React/TypeScript 桌面界面
desktop/src-tauri/       Rust/Tauri 宿主和 sidecar 生命周期
src/researchbrain/migrations/  Alembic 数据库迁移
tests/                   Python 自动化测试
scripts/                 构建、注册、冒烟和视觉检查脚本
docs/                    架构、隐私、许可、路线图和开发文档
.github/                 CI、依赖更新和协作模板

Contributing

Please read the Contribution Guide, Support Information, and Security Policy before submitting issues. Do not upload private PDFs, Zotero databases, API keys, browser cookies, or logs containing personal paths.

License

The project is released under the GNU Affero General Public License v3.0 only. PyMuPDF, MinerU, and other third-party components retain their respective licenses; the Third-Party Licensing Information must be read before distributing the installer.