Architecture Overview

This document explains how the cerebro system works end-to-end.

System Diagram

flowchart TB
    subgraph cerebro_repo["~/Projects/cerebro (source code)"]
        CLI_CRATE["crates/cerebro<br/>CLI binary"]
        CORE_CRATE["crates/cerebro-core<br/>shared types"]
        MCP_CRATE["crates/cerebro-mcp<br/>MCP library"]
        TUI_CRATE["crates/cerebro-tui<br/>TUI binary (feature branch)"]
        DOCS["docs/<br/>tool documentation"]
    end

    subgraph cortex_dir["~/Projects/<name> (your cortex)"]
        CFG["config.toml"]
        AUTO["content/ (auto-generated)<br/>index.md, projects/, journal/"]
        MANUAL["content/ (manual)<br/>intent/, notes/, SUMMARY.md"]
        BOOK["book/<br/>rendered HTML"]
        AGENTS["AGENTS.md<br/>edit boundaries"]
    end

    subgraph external["External data sources"]
        GIT["project git repos"]
        OODB["opencode sessions.db"]
    end

    subgraph consumers["Consumers"]
        MDBOOK["mdbook"]
        OPENCODE["OpenCode"]
        TERMINAL["Terminal user"]
    end

    CLI_CRATE -->|scrapes| GIT
    CLI_CRATE -->|queries| OODB
    CLI_CRATE -->|reads| CFG
    CLI_CRATE -->|writes| AUTO

    TUI_CRATE -->|reads same data| AUTO
    TUI_CRATE -->|reads| MANUAL
    TUI_CRATE -->|uses types| CORE_CRATE

    MCP_CRATE -->|reads| AUTO
    MCP_CRATE -->|reads| MANUAL

    MANUAL -. "human edits" .-> MANUAL
    AGENTS -. "defines boundaries" .-> MANUAL

    AUTO -->|mdbook src| MDBOOK
    MANUAL -->|mdbook src| MDBOOK
    MDBOOK -->|renders| BOOK

    OPENCODE <-->|JSON-RPC| MCP_CRATE
    TERMINAL <-->|interactive| TUI_CRATE

    style CLI_CRATE fill:#4a9eff,color:#fff
    style TUI_CRATE fill:#9b59b6,color:#fff
    style MCP_CRATE fill:#ff6b6b,color:#fff
    style AUTO fill:#ff8
    style MANUAL fill:#f8f
    style BOOK fill:#8f8

The Two Repos

cerebro (~/Projects/cerebro)

The source code repository. Contains:

• CLI binary (crates/cerebro/) — Scrapes data sources and generates markdown
• Shared types (crates/cerebro-core/) — Config, ProjectContext, Storage trait
• MCP server (crates/cerebro-mcp/) — JSON-RPC server for OpenCode
• TUI (crates/cerebro-tui/) — Terminal UI (feature branch)
• Documentation (docs/) — mdBook docs about the cerebro tool itself

Your cortex

The cortex (named whatever you choose — cortex in this project’s case). Contains:

• config.toml — Project list and settings (read by cerebro)
• content/ — mdBook source (mix of auto-generated and manual)
• book/ — Rendered HTML output
• AGENTS.md — Defines edit boundaries for AI agents
• book.toml — mdBook configuration

The Three Binaries

cerebro (CLI)

cerebro build            # Scrape repos, generate markdown
cerebro build --fresh    # Ignore cache
cerebro build --project X  # Single project
cerebro status           # Show cache status
cerebro serve            # Spawn mdbook in output_dir
cerebro serve --port N   # Custom port
cerebro mcp              # Start MCP server

Data flow:

1. Reads config.toml from your cortex
2. For each project: scrapes git, queries OpenCode DB, scans TODOs, reads manual notes
3. Writes markdown to output_dir (typically ./content)
4. Cache stored alongside config to avoid redundant scraping

cerebro-mcp (MCP Server)

# Started by OpenCode via opencode.json:
#   "command": ["cerebro", "mcp"]
# Or standalone:
cerebro-mcp    # Reads CORTEX_PATH env var

Tools provided:

• read_project — Combined generated + manual content for a project
• list_projects — All tracked projects with metadata
• read_journal — Journal entry by date
• read_today — Today’s journal entry
• read_intent — Goals by period (daily/weekly/monthly/yearly)
• search_todos — Search TODOs across projects
• get_stats — Overall statistics

Path resolution:

• CORTEX_PATH env var (required — points to your cortex)
• Reads generated content from {CORTEX_PATH}/content/
• Reads manual notes from {CORTEX_PATH}/content/notes/ and {CORTEX_PATH}/content/intent/

cerebro-tui (Feature Branch)

Interactive terminal UI for browsing projects without opening a browser. Shares cerebro-core types with the CLI and reads the same cortex content that mdbook renders.

Views implemented:

• Home/Dashboard — Project overview
• Project detail — Full context for a single project
• Journal — Date-grouped activity logs
• TODOs — Searchable/filterable TODO list
• Config — View/edit configuration

Content Boundaries

The cortex’s content/ has a strict split between auto-generated and manual content:

Auto-generated (cerebro writes, humans don’t edit)

Manual (humans write, cerebro doesn’t touch)

The boundary is enforced by an AGENTS.md file in your cortex which instructs AI agents which files are safe to overwrite and which are human-only.

Cron Workflow

0 5,9 * * *    cerebro build && mdbook build
59 23 * * *    cerebro build && mdbook build

Runs from your cortex. Scrape → generate → render, three times daily.

Shared Type System

All binaries share types from cerebro-core:

ProjectConfig     — Name, repo_path, active flag
ProjectContext    — Full context: commits, sessions, todos, notes
ManualNotes       — Status, next actions, journal excerpt
Config            — Settings + project list
Cache             — Timestamps for incremental scraping

The TUI uses these same types to render views, ensuring consistency between what you see in the browser (mdbook), the terminal (TUI), and what OpenCode reads (MCP).