# mirix-ai/mirix architecture

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

- Interactive diagram: https://gitdiagram.com/mirix-ai/mirix
- Repository: https://github.com/mirix-ai/mirix

## Overview

##### Project Type and Purpose
- This is a full-stack, open-source multi-agent personal assistant application.
- Frontend: Electron + React for desktop UI, capturing user input and screen activity.
- Backend: Python library + FastAPI server managing six specialized memory agents, orchestrating data flows, and interfacing with LLM APIs and a local database.

- Frontend → FastAPI API endpoints: user messages, file uploads, settings.
- FastAPI → AgentWrapper: wraps incoming requests into internal messages.
- AgentWrapper ↔ Message Queue → Specialized Agents: dispatch tasks (e.g., “summarize screen capture” → EpisodicMemoryAgent).
- Agents → Service Layer → ORM → Database: persist new memory records or query existing ones.
- Agents → LLM API Clients → External LLM Providers (OpenAI, etc.) → Agents: generate responses or process data.
- Agents → File Manager → Local filesystem / Cloud mapping: store screen captures, audio files.
- BackgroundAgent monitors screen activity → sends captures back through the same orchestration flow.
- FastAPI → Frontend: streams or returns responses to display chat bubbles and memory visualizations.

##### Architectural Patterns and Design Principles
- Layered Architecture: separation of concerns across UI, API, agent/orchestration, services, data.
- Multi-Agent Pattern: each memory type is encapsulated in its own agent class, promoting modularity and extensibility.
- Dependency Injection via Configuration: agents, database, and LLM clients are wired from YAML configs.
- Event-Driven messaging: in-process message queue decouples agents and orchestrator.
- Privacy-first local storage: database and screen captures remain on user’s machine, controlled by Electron settings.

##### Technologies and Frameworks
- Frontend: Electron, React, JavaScript/TypeScript ecosystem (Node.js, package.json)
- Backend: Python 3.x, FastAPI, SQLAlchemy, pglite, uvicorn
- LLM Clients: openai, anthropic, cohere, google-ai, aws-bedrock wrappers
- Data: SQLite or PostgreSQL, BM25 full-text search, vector similarity (pgvector)
- Build & Packaging: PyInstaller spec files (main.spec, mirix_backend.spec), Electron packaging scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        style FrontendLayer stroke:#1f77b4,stroke-width:2px
        ElectronMain["electron.js"]:::frontend
        Preload["preload.js"]:::frontend
        AppJS["App.js"]:::frontend
        ChatWindow["ChatWindow.js"]:::frontend
        MemoryTree["MemoryTreeVisualization.js"]:::frontend
        SettingsPanel["SettingsPanel.js"]:::frontend
        ScreenshotMonitor["ScreenshotMonitor.js"]:::frontend
    end

    %% API / Transport Layer
    subgraph "API / Transport Layer"
        style APILayer stroke:#17becf,stroke-width:2px
        FastAPIEndpoints["fastapi_server.py"]:::api
        IPCUtils["utils.py"]:::api
        MessageQueue["message_queue.py"]:::api
    end

    %% Backend Layer
    subgraph "Backend Layer"
        style BackendLayer stroke:#17becf,stroke-width:2px
        FastAPIServer["server.py"]:::api
        CLIEntrypoint["main.py"]:::api
    end

    %% Agent Orchestration Layer
    subgraph "Agent Orchestration Layer"
        style Orchestration stroke:#ff7f0e,stroke-width:2px
        AgentWrapper["agent_wrapper.py"]:::orchestration
        BackgroundAgent["background_agent.py"]:::orchestration
        CoreAgent["core_memory_agent.py"]:::orchestration
        EpisodicAgent["episodic_memory_agent.py"]:::orchestration
        SemanticAgent["semantic_memory_agent.py"]:::orchestration
        ProceduralAgent["procedural_memory_agent.py"]:::orchestration
        ResourceAgent["resource_memory_agent.py"]:::orchestration
        KnowledgeVaultAgent["knowledge_vault_agent.py"]:::orchestration
    end

    %% Service Layer
    subgraph "Service Layer"
        style ServiceLayer stroke:#2ca02c,stroke-width:2px
        AgentManager["agent_manager.py"]:::service
        EpisodicManager["episodic_memory_manager.py"]:::service
        SemanticManager["semantic_memory_manager.py"]:::service
        ProceduralManager["procedural_memory_manager.py"]:::service
        ResourceManager["resource_memory_manager.py"]:::service
        KnowledgeVaultManager["knowledge_vault_manager.py"]:::service
        FileManager["file_manager.py"]:::service
        UserManager["user_manager.py"]:::service
        OrgManager["organization_manager.py"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        style DataLayer stroke:#2ca02c,stroke-width:2px
        ORMModels["orm/*.py"]:::data
        DBConnector["pglite_connector.py"]:::data
        SchemaExtractor["schema_extractor.py"]:::data
    end

    %% LLM Integration Layer
    subgraph "LLM Integration Layer"
        style LLMLayer stroke:#9467bd,stroke-width:2px
        LLMBase["llm_client_base.py"]:::llm
        OpenAIClient["openai_client.py"]:::llm
        AnthropicClient["anthropic_client.py"]:::llm
        CohereClient["cohere_client.py"]:::llm
        GoogleAIClient["google_ai_client.py"]:::llm
        AWSBedrockClient["aws_bedrock.py"]:::llm
        PromptTemplates["prompts/*.txt"]:::llm
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        style ConfigLayer stroke:#8c564b,stroke-width:2px
        YAMLConfigs["configs/*.yaml"]:::config
        AppConfig["config.py"]:::config
        Constants["constants.py"]:::config
        Helpers["utils.py"]:::config
        Logging["log.py"]:::config
        Tracing["tracing.py"]:::config
        Settings["settings.py"]:::config
    end

    %% External Systems
    subgraph "External Systems"
        style ExternalLayer stroke:#7f7f7f,stroke-width:2px
        ExternalLLM["OpenAI/Anthropic/Cohere/etc."]:::external
        LocalFS["Local File System / Cloud"]:::external
        LocalDB["SQLite/PostgreSQL"]:::external
    end

    %% Connections
    ElectronMain -->|starts| AppJS
    Preload -->|injects| AppJS
    AppJS -->|renders| ChatWindow
    AppJS -->|renders| MemoryTree
    AppJS -->|renders| SettingsPanel
    ScreenshotMonitor -->|captures| AgentWrapper
    ChatWindow -->|HTTP request| FastAPIEndpoints
    FastAPIEndpoints -->|"uses utils"| IPCUtils
    FastAPIEndpoints -->|wrap request| AgentWrapper
    AgentWrapper -->|enqueue message| MessageQueue
    MessageQueue -->|dispatch to| CoreAgent
    MessageQueue -->|dispatch to| EpisodicAgent
    MessageQueue -->|dispatch to| SemanticAgent
    MessageQueue -->|dispatch to| ProceduralAgent
    MessageQueue -->|dispatch to| ResourceAgent
    MessageQueue -->|dispatch to| KnowledgeVaultAgent
    BackgroundAgent -->|monitor & send| AgentWrapper
    CoreAgent -->|call| LLMBase
    EpisodicAgent -->|DB write/read| ORMModels
    SemanticAgent -->|DB write/read| ORMModels
    ProceduralAgent -->|DB write/read| ORMModels
    ResourceAgent -->|file store| FileManager
    KnowledgeVaultAgent -->|DB write| ORMModels
    LLMBase -->|implement| OpenAIClient
    LLMBase -->|implement| AnthropicClient
    LLMBase -->|implement| CohereClient
    LLMBase -->|implement| GoogleAIClient
    LLMBase -->|implement| AWSBedrockClient
    LLMBase -->|use templates| PromptTemplates
    OpenAIClient -->|LLM call| ExternalLLM
    AnthropicClient -->|LLM call| ExternalLLM
    CohereClient -->|LLM call| ExternalLLM
    GoogleAIClient -->|LLM call| ExternalLLM
    AWSBedrockClient -->|LLM call| ExternalLLM
    ORMModels -->|connect| DBConnector
    DBConnector -->|extract schema| SchemaExtractor
    FileManager -->|store| LocalFS
    ORMModels -->|persist| LocalDB
    FastAPIEndpoints -->|response| AppJS

    %% Click Events
    click ElectronMain "https://github.com/mirix-ai/mirix/blob/main/frontend/public/electron.js"
    click Preload "https://github.com/mirix-ai/mirix/blob/main/frontend/public/preload.js"
    click AppJS "https://github.com/mirix-ai/mirix/blob/main/frontend/src/App.js"
    click ChatWindow "https://github.com/mirix-ai/mirix/blob/main/frontend/src/components/ChatWindow.js"
    click MemoryTree "https://github.com/mirix-ai/mirix/blob/main/frontend/src/components/MemoryTreeVisualization.js"
    click SettingsPanel "https://github.com/mirix-ai/mirix/blob/main/frontend/src/components/SettingsPanel.js"
    click ScreenshotMonitor "https://github.com/mirix-ai/mirix/blob/main/frontend/src/components/ScreenshotMonitor.js"
    click FastAPIEndpoints "https://github.com/mirix-ai/mirix/blob/main/mirix/server/fastapi_server.py"
    click IPCUtils "https://github.com/mirix-ai/mirix/blob/main/mirix/server/utils.py"
    click MessageQueue "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/message_queue.py"
    click FastAPIServer "https://github.com/mirix-ai/mirix/blob/main/mirix/server/server.py"
    click CLIEntrypoint "https://github.com/mirix-ai/mirix/blob/main/main.py"
    click AgentWrapper "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/agent_wrapper.py"
    click BackgroundAgent "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/background_agent.py"
    click CoreAgent "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/core_memory_agent.py"
    click EpisodicAgent "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/episodic_memory_agent.py"
    click SemanticAgent "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/semantic_memory_agent.py"
    click ProceduralAgent "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/procedural_memory_agent.py"
    click ResourceAgent "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/resource_memory_agent.py"
    click KnowledgeVaultAgent "https://github.com/mirix-ai/mirix/blob/main/mirix/agent/knowledge_vault_agent.py"
    click AgentManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/agent_manager.py"
    click EpisodicManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/episodic_memory_manager.py"
    click SemanticManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/semantic_memory_manager.py"
    click ProceduralManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/procedural_memory_manager.py"
    click ResourceManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/resource_memory_manager.py"
    click KnowledgeVaultManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/knowledge_vault_manager.py"
    click FileManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/file_manager.py"
    click UserManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/user_manager.py"
    click OrgManager "https://github.com/mirix-ai/mirix/blob/main/mirix/services/organization_manager.py"
    click ORMModels "https://github.com/mirix-ai/mirix/blob/main/mirix/orm/episodic_memory.py"
    click DBConnector "https://github.com/mirix-ai/mirix/blob/main/mirix/database/pglite_connector.py"
    click SchemaExtractor "https://github.com/mirix-ai/mirix/blob/main/mirix/database/schema_extractor.py"
    click LLMBase "https://github.com/mirix-ai/mirix/blob/main/mirix/llm_api/llm_client_base.py"
    click OpenAIClient "https://github.com/mirix-ai/mirix/blob/main/mirix/llm_api/openai_client.py"
    click AnthropicClient "https://github.com/mirix-ai/mirix/blob/main/mirix/llm_api/anthropic_client.py"
    click CohereClient "https://github.com/mirix-ai/mirix/blob/main/mirix/llm_api/cohere_client.py"
    click GoogleAIClient "https://github.com/mirix-ai/mirix/blob/main/mirix/llm_api/google_ai_client.py"
    click AWSBedrockClient "https://github.com/mirix-ai/mirix/blob/main/mirix/llm_api/aws_bedrock.py"
    click PromptTemplates "https://github.com/mirix-ai/mirix/tree/main/mirix/prompts/system"
    click YAMLConfigs "https://github.com/mirix-ai/mirix/blob/main/configs/mirix.yaml"

    %% Styles
    classDef frontend fill:#c6dbef,stroke:#1f77b4
    classDef api fill:#d0eff0,stroke:#17becf
    classDef orchestration fill:#ffe5cc,stroke:#ff7f0e
    classDef service fill:#d6eadf,stroke:#2ca02c
    classDef data fill:#d6eadf,stroke:#2ca02c
    classDef llm fill:#e0dbfc,stroke:#9467bd
    classDef config fill:#f3e5f5,stroke:#8c564b
    classDef external fill:#e0e0e0,stroke:#7f7f7f
```
