Brainforge Knowledge

08_architecture

2 min read

Entry Points

  • backend/src/second_brain/mcp_server.py — FastMCP server, exposes all tools via @server.tool()
  • backend/src/second_brain/cli.py — Click CLI (brain command)
  • backend/src/second_brain/service_mcp.py — shared routing/orchestration logic

Layer Structure

CLI / MCP Client
    ↓
mcp_server.py / cli.py        ← input validation, timeout, string formatting
    ↓
service_mcp.py                ← request routing
    ↓
agents/{agent}.py             ← Pydantic AI agents (one file per cognitive task)
    ↓
services/{service}.py         ← infrastructure (memory, storage, embeddings, etc.)
    ↓
Supabase (PostgreSQL/pgvector) + Mem0 + Voyage AI

Key Directories

backend/src/second_brain/
  agents/          # 13 AI agents: recall, ask, learn, create, review, coach,
                   #   pmo, email_agent, clarity, synthesizer, template_builder,
                   #   chief_of_staff, specialist, summarizer
  services/        # Infrastructure: memory, storage, embeddings, ingest,
                   #   parsers, voyage, graphiti, graphiti_memory, retry, health
  config.py        # BrainConfig — single source of truth for all settings
  deps.py          # BrainDeps — dependency injection container
  schemas.py       # Pydantic output schemas for all agents
  models.py        # LLM model selection logic (API vs subscription vs Ollama)
  mcp_server.py    # FastMCP server + all tool definitions
  cli.py           # Click CLI commands
backend/supabase/
  migrations/      # 16 sequential SQL migrations (numbered 001–016)
backend/tests/     # pytest test suite (one file per module)

Dependency Injection

BrainDeps (in deps.py) holds all service instances. Passed to every agent via RunContext[BrainDeps]. Created once at startup via create_deps().

Configuration

BrainConfig extends pydantic_settings.BaseSettings. All settings read from .env automatically. Sensitive fields use repr=False. Cross-field validation via @model_validator.

Graph View