BrainHub — 통합 Web 프론트엔드 + 클라우드 드라이브 + MCP 게이트웨이 + 운영 agent

Brain 제품군의 자가 사용 메인 진입점: FastAPI 단일 프로세스로 모든 패널(지식 베이스 / 검색 / 클라우드 드라이브 / 칸반 / 메모리 / agent 상태 / 운영 로그)을 통합하고, 외부에 단일 MCP 게이트웨이를 제공하며, 내장 운영 agent가 지식 베이스와 메모리를 자동 유지합니다.

소개

BrainHub는 Brain 제품군의 사용 진입점으로, 제품군의 모든 역량을 하나의 조작 가능한 인터페이스와 API 세트로 모으는 역할을 합니다:

• Web 패널: Jinja2 + HTMX 제로 프론트엔드 구축, 지식 베이스 탐색 / 의미 검색 / 클라우드 드라이브 CRUD / 칸반 작업 상태 머신 / 메모리 / agent 상태 / 운영 로그

• JSON API v1: /api/v1/* 데스크톱 React 프론트엔드용

• MCP 게이트웨이: BrainHub 자체 도구 + BrainMem 검색 도구 총 12개를 통합, 모든 agent는 이 하나의 진입점에만 연결

• 운영 agent: 정기 아카이브, 인덱스 재구축, 메모리 추출, 헬스 체크

자가 사용 시에는 brainhub start 하나로 메인 프로세스를 모두 기동합니다: import brainmem을 검색 백엔드로 사용하고, brain-bridge 자식 프로세스를 띄워 외부적으로 하나의 소프트웨어처럼 보입니다.

Related MCP server: MCPHub

특징

• 🖥️ 통합 패널 — 7가지 유형의 페이지를 하나의 서비스에 통합, HTMX 부분 새로고침 + Alpine 가벼운 상호작용, 프론트엔드 빌드 체인 불필요

• 🔌 단일 MCP 진입점 — write_note / read_file / list_files / 프로젝트 상태 머신 / health_check / send_matrix_msg + BrainMem 검색 도구 전달

• 🤖 운영 agent — APScheduler 정기 작업: 아카이브 / 인덱스 재구축 / 메모리 추출 / 헬스 체크, 외부 오케스트레이션 불필요

• 📁 클라우드 드라이브 — BRAIN_ROOT 파일 탐색, 업로드/다운로드, 썸네일 lazy 생성, 경로 이탈 및 민감 경로 차단

• 📋 칸반 — 프로젝트/작업 상태 머신 (todo → doing → blocked → done, 엄격한 전이)

• 🔗 협업 연동 — 네임드 파이프를 통해 send_matrix_msg를 BrainBridge daemon으로 전달, 프론트엔드 WS에서 Matrix 메시지와 agent 상태를 실시간 수신

• 💻 데스크톱 동일 출처 마운트 — /app에 brainhub-desktop 빌드 산출물 마운트, 동일 출처로 CORS 불필요

아키텍처 구성

빠른 시작

# 安装（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

문서 인덱스

• PLAN.md — 구현 계획과 현재 진행 상황 (Phase 1-3 검수, 패널, 운영 Cron, MCP 도구, 의존성)

• docs/protocol-constitution.md — 프로토콜 헌법: MCP 도구 시그니처 / memory.db schema / Matrix envelope

• ../brainmem/PRODUCT_FAMILY_PLAN.md — 제품군 전체 플랜 (제품 경계를 넘는, HX470 마이그레이션, 리스크 트레이드오프)

관련 프로젝트

Brain 제품군: BrainMem (메모리 엔진) · BrainHub (본 저장소) · BrainBridge (협업 게이트웨이)