# turing-machines/mentals-ai architecture

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

- Interactive diagram: https://gitdiagram.com/turing-machines/mentals-ai
- Repository: https://github.com/turing-machines/mentals-ai

## Overview

##### Main Components

a) Core System Components:
- Agent Executor (Central Executive - System 2)
- LLM Interface (System 1)
- Memory Management System
- Tool Registry
- Code Interpreter

b) External Integrations:
- OpenAI API / LLM Providers
- PostgreSQL with pgvector
- File System
- Python Runtime

##### Architectural Layers

**┌─────────────────────────────────────────────┐**
- Agent Layer                  │
- (.gen files, Markdown-based agent scripts)  │
- ┤
- Execution Layer                  │
- (Agent Executor, Memory Controller, Tools)  │
- ┤
- Integration Layer                │
- (LLM Interface, Database, File System)      │
- ┘

##### Key Relationships to Highlight

a) Control Flow:
- Recursive loop between Agent Executor and LLM
- Instruction flow between components
- Demonstrate memory access patterns

b) Data Flow:
- Agent script processing
- Context management
- Memory operations
- Tool execution paths

##### Specific Implementation Details

- Blue rectangles: Core components
- Green hexagons: External services
- Yellow diamonds: Decision points
- Purple rounded rectangles: Tools

##### Component Interactions

**Agent Script (.gen) → Agent Executor**
- ↓
- ┌─────────────────────────────┐
- Instruction Pipeline    │
- ┘
- ↙             ↘
- Working Memory    Short-term Memory
- ↘             ↙
- ┌─────────────────────────────┐
- LLM Interface       │
- ┘

##### Technical Details

- C++ core implementation
- LibOAI integration
- PostgreSQL vector storage
- Python interpreter integration
- File system interactions

- Natural language control flow
- Markdown-based agent definition
- Recursive decision-making process
- Memory management system
- Tool integration framework

This system design should effectively communicate both the high-level architecture and the detailed interactions between components, while highlighting the unique aspects of Mentals AI's approach to agent-based AI systems.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef external fill:#4CAF50,stroke:#2E7D32,color:white
    classDef memory fill:#FF9800,stroke:#EF6C00,color:white
    classDef tools fill:#9C27B0,stroke:#6A1B9A,color:white
    classDef storage fill:#FF5722,stroke:#D84315,color:white
    classDef agent fill:#03A9F4,stroke:#0277BD,color:white

    %% Agent Layer
    subgraph AgentLayer
        AgentScripts[".gen Files"]
        MarkdownAgents["Markdown-based Agents"]
    end
    click AgentScripts "https://github.com/turing-machines/mentals-ai/tree/main/agents/"

    %% Execution Layer
    subgraph ExecutionLayer
        AgentExecutor["Agent Executor\n(System 2)"]:::core
        MemoryController["Memory Management\nSystem"]:::memory
        ToolRegistry["Tool Registry"]:::tools
        CodeInterpreter["Code Interpreter"]:::tools
        NativeTools["Native Tools System"]:::tools
    end
    click AgentExecutor "https://github.com/turing-machines/mentals-ai/blob/main/src/agent_executor.h"
    click MemoryController "https://github.com/turing-machines/mentals-ai/blob/main/src/memory_controller.h"
    click ToolRegistry "https://github.com/turing-machines/mentals-ai/blob/main/src/tool_registry.h"
    click CodeInterpreter "https://github.com/turing-machines/mentals-ai/blob/main/src/code_interpreter.h"
    click NativeTools "https://github.com/turing-machines/mentals-ai/blob/main/src/native_tools.h"

    %% Integration Layer
    subgraph IntegrationLayer
        LLMInterface["LLM Interface\n(System 1)"]:::core
        OpenAI["OpenAI API"]:::external
        PostgreSQL["PostgreSQL\nVector Storage"]:::storage
        FileSystem["File System"]:::storage
        PythonRuntime["Python Runtime"]:::external
        ContextManager["Context Manager"]:::core
    end
    click LLMInterface "https://github.com/turing-machines/mentals-ai/blob/main/src/llm.h"
    click OpenAI "https://github.com/turing-machines/mentals-ai/tree/main/src/liboai/"
    click PostgreSQL "https://github.com/turing-machines/mentals-ai/blob/main/src/pgvector.h"
    click ContextManager "https://github.com/turing-machines/mentals-ai/blob/main/src/context.h"

    %% Memory Components
    subgraph MemorySystem
        WorkingMemory["Working Memory"]:::memory
        ShortTermMemory["Short-term Memory"]:::memory
    end

    %% Relationships
    AgentScripts --> AgentExecutor
    MarkdownAgents --> AgentExecutor
    AgentExecutor --> MemoryController
    AgentExecutor --> ToolRegistry
    ToolRegistry --> CodeInterpreter
    ToolRegistry --> NativeTools
    MemoryController --> WorkingMemory
    MemoryController --> ShortTermMemory
    WorkingMemory --> LLMInterface
    ShortTermMemory --> LLMInterface
    LLMInterface --> OpenAI
    MemoryController --> PostgreSQL
    CodeInterpreter --> PythonRuntime
    AgentExecutor --> ContextManager
    ContextManager --> FileSystem

    %% Legend
    subgraph Legend
        CoreComponent["Core Component"]:::core
        ExternalService["External Service"]:::external
        MemoryComponent["Memory Component"]:::memory
        ToolComponent["Tool Component"]:::tools
        StorageComponent["Storage Component"]:::storage
    end
```
