# agiresearch/cerebrum architecture

> Architecture diagram of the GitHub repository agiresearch/cerebrum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agiresearch/cerebrum
- Repository: https://github.com/agiresearch/cerebrum

## Overview

##### Project Type & Purpose
- Cerebrum is an open-source Python SDK + CLI for AIOS (the “AI Agent Operating System”).
- It provides libraries and command‐line tools to build, run, publish, and benchmark LLM-based AI Agents and Tools against the AIOS kernel and external LLM/providers.

##### File-Structure & Architectural Patterns
- Top-Level Modules:
– cerebrum/commands → CLI entrypoints (run-agent, list-*, download-agent/tool, upload-agent/tool, run-computer-use-agent)
– cerebrum/manager → orchestrator for Agents & Tools
– cerebrum/llm, cerebrum/memory, cerebrum/storage, cerebrum/tool → layered API modules
– cerebrum/tool/core + registry → built-in tool implementations & plugin registry
– cerebrum/community/adapter → adapter pattern for 3rd-party frameworks (Autogen, Interpreter, MetaGPT)
– cerebrum/interface → abstraction definitions for API layers
– cerebrum/example → sample agents/tools demonstrating folder structure & config
– run_cua.py + script.sh → specialized scripts for computer-use agent
– benchmarks/ → evaluation harness against multiple agents and scenarios
- Patterns: layered architecture (CLI → commands → manager → API layers → services), plugin/registry for tools, adapter for external agent frameworks.

a. Main Components
- CLI Layer
– Commands: run-agent, list-available-llms, download-agent, upload-tool, run-computer-use-agent
- Command Dispatcher
– cerebrum.commands.* modules
- Manager Layer
– cerebrum.manager.agent / .tool / .package
- API Layers
– LLM API: cerebrum.llm/apis.py, layer.py
– Memory API: cerebrum.memory/apis.py, layer.py
– Storage API: cerebrum.storage/apis.py, layer.py
– Tool API: cerebrum.tool/apis.py, base.py, layer.py
- Plugin Registry
– cerebrum.tool.core/registry.py → registers built-in tools
- Community Adapters
– cerebrum.community.adapter/* → wrap Autogen, Interpreter, MetaGPT
- Agent Execution Pipeline
– Agent entry.py + config.json + meta_requirements.txt
- Example & Benchmark Workflows
– cerebrum/example/* for demos
– benchmarks/experiment_core.py for evaluations
- External Services
– AIOS Kernel (RPC/HTTP)
– LLM Providers (OpenAI, Anthropic, HF, etc.)
– Remote AgentHub / ToolHub (HTTP)
– Third-party tool services (Google, Wikipedia, Wolfram, etc.)

b. Relationships & Data Flow
1. User invokes CLI → CLI parses args → calls corresponding cerebrum.commands module
2. Command module → Manager → loads Agent/Tool via config & registry
3. Manager coordinates:
– LLM API calls (to external LLM endpoints)
– Memory reads/writes (local/in-memory or remote)
– Storage operations (context persistence)
– Tool invocations (to core tool code or external service)
4. Community Adapters wrap this pipeline to integrate with other frameworks
5. Example agents/tools and Benchmarks plug into the same pipeline

c. Key Architectural Principles
– Layered Separation (CLI → Command → Manager → API → Services)
– Plugin/Registry Pattern for extensible Tools & Agents
– Adapter Pattern for external agent frameworks
– Config-Driven (JSON/YAML metadata drives discovery & wiring)
– Modular & Extensible: add new tools under cerebrum/tool/core, register them, write new commands if needed

d. Important Technologies & Frameworks
– Python 3.10/3.11
– Standard library + HTTP/gRPC for kernel communications
– JSON/YAML for configs
– External LLM clients (openai-python, anthropic-python, etc.)
– In-memory or file-based stores for memory/storage
– Shell scripts (script.sh, run_cua.py) for specialized workflows

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        runAgent["run-agent"]:::cli
        listAvailableLLMs["list-available-llms"]:::cli
        downloadAgent["download-agent"]:::cli
        uploadTool["upload-tool"]:::cli
        runCUA["run-computer-use-agent"]:::cli
    end

    %% Command Dispatcher
    subgraph "Command Dispatcher"
        direction TB
        dispatcher["cerebrum/commands/*.py"]:::dispatcher
    end

    %% Manager Layer
    subgraph "Manager Layer"
        direction TB
        agentManager["Agent Manager"]:::manager
        toolManager["Tool Manager"]:::manager
        packageManager["Package Manager"]:::manager
    end

    %% API Layers
    subgraph "API Layers"
        direction TB
        llmApis["LLM API (apis.py)"]:::api
        llmLayer["LLM Layer (layer.py)"]:::api
        memoryApis["Memory API (apis.py)"]:::api
        memoryLayer["Memory Layer (layer.py)"]:::api
        storageApis["Storage API (apis.py)"]:::api
        storageLayer["Storage Layer (layer.py)"]:::api
        toolApis["Tool API (apis.py)"]:::api
        toolBase["Tool Base (base.py)"]:::api
        toolLayer["Tool Layer (layer.py)"]:::api
        coreRegistry["Plugin Registry"]:::registry
    end

    %% Community Adapters
    subgraph "Community Adapters"
        direction TB
        adapterCore["adapter.py"]:::adapter
        autogenAdapter["autogen_adapter.py"]:::adapter
        interpreterAdapter["interpreter_adapter.py"]:::adapter
        metagptAdapter["metagpt_adapter.py"]:::adapter
    end

    %% Example & Benchmark
    subgraph "Examples & Benchmarks"
        direction TB
        examples["Example Agents/Tools"]:::example
        benchmark["Benchmarks (experiment_core.py)"]:::example
    end

    %% External Services
    subgraph "External Services"
        direction TB
        AIOS["AIOS Kernel"]:::external
        LLMProviders["LLM Providers"]:::external
        AgentHub["AgentHub/ToolHub"]:::external
        ThirdPartyTools["3rd-Party Tool Services"]:::external
        memoryStore[(Memory Store)]:::external
        storageStore[(Storage Store)]:::external
    end

    %% Flows
    runAgent -->|invokes| dispatcher
    listAvailableLLMs -->|invokes| dispatcher
    downloadAgent -->|invokes| dispatcher
    uploadTool -->|invokes| dispatcher
    runCUA -->|invokes| dispatcher

    dispatcher -->|dispatches| agentManager
    dispatcher -->|dispatches| toolManager
    dispatcher -->|dispatches| packageManager

    agentManager -->|calls| llmApis
    agentManager -->|calls| memoryApis
    agentManager -->|calls| storageApis
    agentManager -->|calls| toolApis

    toolManager -->|uses| coreRegistry
    toolManager -->|calls| toolApis

    llmApis -->|internal| llmLayer
    memoryApis -->|internal| memoryLayer
    storageApis -->|internal| storageLayer
    toolApis -->|internal| toolLayer

    llmLayer -->|requests| LLMProviders
    memoryLayer -->|reads/writes| memoryStore
    storageLayer -->|reads/writes| storageStore
    toolLayer -->|invokes| ThirdPartyTools

    agentManager -->|rpc/http| AIOS
    agentManager -->|http| AgentHub

    agentManager -->|wraps via| adapterCore
    adapterCore --> autogenAdapter
    adapterCore --> interpreterAdapter
    adapterCore --> metagptAdapter

    examples -->|demo pipeline| dispatcher
    benchmark -->|parallel run| dispatcher

    %% Click Events
    click runAgent "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/commands/run_agent.py"
    click listAvailableLLMs "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/commands/list_available_llms.py"
    click downloadAgent "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/commands/download_agent.py"
    click uploadTool "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/commands/upload_tool.py"
    click runCUA "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/run_cua.py"
    click dispatcher "https://github.com/agiresearch/cerebrum/tree/main/cerebrum/commands"
    click agentManager "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/manager/agent.py"
    click toolManager "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/manager/tool.py"
    click packageManager "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/manager/package.py"
    click llmApis "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/llm/apis.py"
    click llmLayer "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/llm/layer.py"
    click memoryApis "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/memory/apis.py"
    click memoryLayer "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/memory/layer.py"
    click storageApis "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/storage/apis.py"
    click storageLayer "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/storage/layer.py"
    click toolApis "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/tool/apis.py"
    click toolBase "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/tool/base.py"
    click toolLayer "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/tool/layer.py"
    click coreRegistry "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/tool/core/registry.py"
    click adapterCore "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/community/adapter/adapter.py"
    click autogenAdapter "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/community/adapter/autogen_adapter.py"
    click interpreterAdapter "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/community/adapter/interpreter_adapter.py"
    click metagptAdapter "https://github.com/agiresearch/cerebrum/blob/main/cerebrum/community/adapter/metagpt_adapter.py"
    click examples "https://github.com/agiresearch/cerebrum/tree/main/cerebrum/example"
    click benchmark "https://github.com/agiresearch/cerebrum/blob/main/benchmarks/experiment_core.py"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef dispatcher fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef manager fill:#d4edda,stroke:#333,stroke-width:1px
    classDef api fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef registry fill:#d1ecf1,stroke:#333,stroke-width:1px
    classDef adapter fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef example fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#d6d8db,stroke:#333,stroke-width:1px
```
