BrainHub — Unified Web Frontend + File Storage + MCP Gateway + Ops Agent

The self-use main entry of the Brain product family: a single FastAPI process aggregating all panels (knowledge base / search / file storage / kanban / memory / agent status / ops logs), exposing a single MCP gateway externally, with a built-in ops agent that automatically maintains the knowledge base and memory.

Introduction

BrainHub is the entry point for the Brain product family, consolidating all capabilities into one operable interface and one set of APIs:

• Web Panel: Jinja2 + HTMX zero-frontend build, knowledge base browsing / semantic search / file storage CRUD / kanban task state machine / memory / agent status / ops logs

• JSON API v1: /api/v1/* for the desktop React frontend

• MCP Gateway: aggregates 12 tools total from BrainHub's own tools + BrainMem retrieval tools; any agent only connects to this one entry

• Ops Agent: scheduled archiving, index rebuild, memory extraction, health checks

In the self-use phase, a single brainhub start brings up the entire main process: imports brainmem as the retrieval backend, spawns the brain-bridge subprocess, appearing as one software externally.

Related MCP server: MCPHub

Features

• 🖥️ Unified Panel — 7 types of pages aggregated in one service, HTMX partial refresh + Alpine lightweight interactions, no frontend build chain needed

• 🔌 Single MCP Entry — write_note / read_file / list_files / project state machine / health_check / send_matrix_msg + forwarding BrainMem retrieval tools

• 🤖 Ops Agent — APScheduler scheduled: archiving / index rebuild / memory extraction / health checks, no external orchestration needed

• 📁 File Storage — BRAIN_ROOT file browsing, upload/download, lazy thumbnail generation, out-of-bounds and sensitive path interception

• 📋 Kanban — project/task state machine (todo → doing → blocked → done, strict transitions)

• 🔗 Collaboration Integration — forwards send_matrix_msg to the BrainBridge daemon via named pipe, frontend receives Matrix messages and agent status in real-time via WS

• 💻 Desktop Same-Origin Mount — mounts brainhub-desktop build artifacts at /app, same-origin without CORS

Architecture

Quick Start

# 安装（Python 3.10+，uv 管理；依赖 BrainMem editable 安装）
uv sync
uv pip install -e ../brainmem

# 启动（拉起 Web + MCP 网关 + brain-bridge 子进程）
uv run brainhub start

# 运维子命令
uv run brainhub ops archive
uv run brainhub ops reindex
uv run brainhub ops health

Documentation Index

• PLAN.md — implementation plan and current progress (Phase 1-3 acceptance, panel, ops Cron, MCP tools, dependencies)

• docs/protocol-constitution.md — protocol constitution: MCP tool signatures / memory.db schema / Matrix envelope

• ../brainmem/PRODUCT_FAMILY_PLAN.md — product family global plan (cross-product boundaries, HX470 migration, risk trade-offs)

Related Projects

Brain product family: BrainMem (memory engine) · BrainHub (this repository) · BrainBridge (collaboration gateway)