# getmetal/motorhead architecture

> Architecture diagram of the GitHub repository getmetal/motorhead, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getmetal/motorhead
- Repository: https://github.com/getmetal/motorhead

## Overview

##### Main Components

a) Core Components:
- Memory Management Service (src/memory.rs)
- Long-term Memory Service (src/long_term_memory.rs)
- Retrieval Service (src/retrieval.rs)
- Redis Database Integration (src/redis_utils.rs)
- Message Reducer (src/reducer.rs)

b) External Services:
- OpenAI API (or Azure OpenAI)
- Redis with RediSearch VSS

**┌─ Client Layer ─────────────────────────────────┐**
- External Applications/Examples                  │
- (JS, Python, Vanilla JS clients)               │
- ┬───────────────────────────┘

**┌─ API Layer ───────┼───────────────────────────┐**
- REST Endpoints:    │                           │
- GET /sessions/:id/memory                     │
- POST /sessions/:id/memory                    │
- DELETE /sessions/:id/memory                  │
- POST /sessions/:id/retrieval                 │
- ┬───────────────────────────┘

**┌─ Core Services ───┼───────────────────────────┐**
- ┌─────────────┐  │  ┌──────────────┐         │
- Memory    │──┼──│   Retrieval  │         │
- Manager    │  │  │   Service    │         │
- ┘  │  └──────────────┘         │

- ┌─────────────┐  │  ┌──────────────┐         │
- Message   │──┼──│  Long-term   │         │
- Reducer   │  │  │    Memory    │         │
- ┘  │  └──────────────┘         │
- ┬───────────────────────────┘

**┌─ External Services┼───────────────────────────┐**
- ┌─────────────┐  │  ┌──────────────┐         │
- OpenAI/    │──┼──│    Redis     │         │
- Azure OpenAI │  │  │ (RediSearch) │         │
- ┘  │  └──────────────┘         │
- ┘

##### Important Elements to Highlight

a) Data Flow:
- Message flow from clients through API endpoints
- Memory management process
- Retrieval query path
- Interaction with Redis for storage and search
- Summarization flow with OpenAI

b) Configuration Elements:
- Window size management
- Long-term memory toggle
- Model selection (GPT-3.5/4)
- Redis connection
- Azure/OpenAI API configuration

##### Implementation Details

- Session-based architecture
- Message window management
- Integration with vector search
- Summarization pipeline
- Multiple client support
- Configuration flexibility

Remember to:
- Keep the main flow clear and centered
- Related components together
- Use consistent styling
- Notes for important configuration options
- Scaling points

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef client fill:#f0f0f0,stroke:#333
    classDef api fill:#ffa07a,stroke:#333
    classDef core fill:#87ceeb,stroke:#333
    classDef external fill:#90ee90,stroke:#333
    classDef database fill:#deb887,stroke:#333

    %% Client Layer
    subgraph Clients
        JS["JavaScript Client"]:::client
        PY["Python Client"]:::client
        VJS["Vanilla JS Client"]:::client
        HVJS["Hosted Vanilla JS"]:::client
    end

    %% API Layer
    subgraph API
        GET["/sessions/:id/memory GET"]:::api
        POST["/sessions/:id/memory POST"]:::api
        DEL["/sessions/:id/memory DELETE"]:::api
        RET["/sessions/:id/retrieval POST"]:::api
        HEALTH["Health Check"]:::api
    end

    %% Core Services
    subgraph Core
        MM["Memory Manager"]:::core
        RS["Retrieval Service"]:::core
        LTM["Long-term Memory"]:::core
        MR["Message Reducer"]:::core
        DM["Data Models"]:::core
        MAIN["Main Service"]:::core
    end

    %% External Services
    subgraph External
        OPENAI["OpenAI/Azure OpenAI"]:::external
        REDIS["Redis + RediSearch"]:::database
    end

    %% Relationships
    JS & PY & VJS & HVJS --> GET & POST & DEL & RET
    GET & POST & DEL & RET --> MM
    HEALTH --> MAIN
    MM --> RS
    MM --> LTM
    MM --> MR
    RS --> REDIS
    LTM --> OPENAI
    LTM --> REDIS
    MR --> OPENAI
    
    %% Click Events
    click JS "https://github.com/getmetal/motorhead/tree/main/examples/chat-js"
    click PY "https://github.com/getmetal/motorhead/tree/main/examples/chat-py"
    click VJS "https://github.com/getmetal/motorhead/tree/main/examples/chat-vanilla-js"
    click HVJS "https://github.com/getmetal/motorhead/tree/main/examples/chat-vanilla-js-hosted"
    click MM "https://github.com/getmetal/motorhead/blob/main/src/memory.rs"
    click RS "https://github.com/getmetal/motorhead/blob/main/src/retrieval.rs"
    click LTM "https://github.com/getmetal/motorhead/blob/main/src/long_term_memory.rs"
    click MR "https://github.com/getmetal/motorhead/blob/main/src/reducer.rs"
    click REDIS "https://github.com/getmetal/motorhead/blob/main/src/redis_utils.rs"
    click DM "https://github.com/getmetal/motorhead/blob/main/src/models.rs"
    click MAIN "https://github.com/getmetal/motorhead/blob/main/src/main.rs"
    click HEALTH "https://github.com/getmetal/motorhead/blob/main/src/healthcheck.rs"

    %% Legend
    subgraph Legend
        C1["Client Component"]:::client
        A1["API Endpoint"]:::api
        S1["Core Service"]:::core
        E1["External Service"]:::external
        D1["Database"]:::database
    end
```
