# thekaifansari01/jarvis-os-agent architecture

> Architecture diagram of the GitHub repository thekaifansari01/jarvis-os-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thekaifansari01/jarvis-os-agent
- Repository: https://github.com/thekaifansari01/jarvis-os-agent

## Overview

JARVIS OS Agent is a Windows-focused desktop and cross-device action agent. Its main workflow takes a voice, keyboard, or remote command through command handling and brain selection, executes tools or MCP actions, then returns a response while updating memory. Separate branches provide voice output and input, proactive outreach, retrieval/indexing, and desktop/mobile interfaces. The README documents several architectural links; sampled source confirms selected runtime wiring, but unsampled modules mean some internal calls are not shown.

Main entry points: [`core/main/CommandHandler.py`](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/main/CommandHandler.py) (Command Handler), [`main.py`](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/main.py) (Application Startup), [`core/brain/Memory/Memory.py`](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Memory/Memory.py) (Context Memory), [`core/brain/Processor/AgenticBrain.py`](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Processor/AgenticBrain.py) (Agentic Brain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Command Runtime"]
  node_main["Application Startup<br/>[main.py]"]
  node_handler["Command Handler<br/>[CommandHandler.py]"]
  node_processor["Command Processor<br/>[Processor.py]"]
  node_agentbrain["Agentic Brain<br/>[AgenticBrain.py]"]
  node_fastbrain["Fast Brain<br/>[FastBrain.py]"]
  node_executor["Action Executor<br/>[executor.py]"]
end

subgraph group_memory["Memory and Retrieval"]
  node_memory[("Context Memory<br/>[Memory.py]")]
  node_ltm[("Lifetime Memory<br/>[LifetimeMemory.py]")]
  node_behavior[("Behavior Patterns")]
  node_rag[("Hybrid RAG<br/>[RagEngine.py]")]
  node_indexer["Knowledge Indexer"]
end

subgraph group_voice["Voice and Interfaces"]
  node_voicein["Voice Input<br/>[stt.py]"]
  node_hotkey["Keyboard Input<br/>[HotKeyManager.py]"]
  node_remote["Telegram Remote"]
  node_tts["Speech Output<br/>[tts.py]"]
  node_ui["Desktop Interfaces"]
end

subgraph group_actions["Tools and Integrations"]
  node_tools["Native Tools"]
  node_mcp["MCP Manager<br/>[MCPManager.py]"]
  node_mobile["Mobile Bridge<br/>[server.py]"]
end

subgraph group_proactive["Proactive Services"]
  node_proactive["Proactive Agent<br/>[proactive_agent.py]"]
  node_events["Event Queue<br/>[event_queue.py]"]
  node_channels["Proactive Channels"]
end

node_user(("User"))

node_user -->|"speaks to"| node_voicein
node_user -->|"types via"| node_hotkey
node_user -->|"commands via"| node_remote
node_main -->|"starts"| node_handler
node_main -->|"starts"| node_voicein
node_voicein -->|"submits command"| node_handler
node_hotkey -->|"dispatches command"| node_handler
node_remote -->|"routes command"| node_handler
node_handler -->|"processes command"| node_processor
node_processor -->|"selects complex tasks"| node_agentbrain
node_processor -->|"selects simple tasks"| node_fastbrain
node_handler -->|"executes actions"| node_executor
node_handler -->|"records exchange"| node_memory
node_agentbrain -->|"uses memory"| node_memory
node_fastbrain -->|"uses memory"| node_memory
node_memory -->|"uses lifetime store"| node_ltm
node_memory -->|"uses patterns"| node_behavior
node_agentbrain -->|"invokes tools"| node_tools
node_fastbrain -->|"invokes tools"| node_tools
node_agentbrain -.->|"uses MCP tools"| node_mcp
node_main -->|"starts service"| node_rag
node_rag -->|"loads index settings"| node_indexer
node_main -->|"starts"| node_proactive
node_proactive -->|"queues events"| node_events
node_proactive -->|"dispatches outreach"| node_channels
node_main -->|"starts service"| node_mcp
node_tools -.->|"includes bridge"| node_mobile
node_handler -.->|"speaks response"| node_tts
node_main -.->|"starts interfaces"| node_ui

click node_main "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/main.py"
click node_voicein "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/voice/stt.py"
click node_hotkey "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/main/HotKeyManager.py"
click node_remote "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/main/TelegramRemoteBot.py"
click node_handler "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/main/CommandHandler.py"
click node_processor "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Processor/Processor.py"
click node_agentbrain "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Processor/AgenticBrain.py"
click node_fastbrain "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Processor/FastBrain.py"
click node_executor "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/executor.py"
click node_memory "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Memory/Memory.py"
click node_ltm "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Memory/LifetimeMemory.py"
click node_behavior "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Memory/BehavioralEngine.py"
click node_rag "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/RagEngine.py"
click node_indexer "https://github.com/thekaifansari01/jarvis-os-agent/tree/main/core/brain/Indexer"
click node_tools "https://github.com/thekaifansari01/jarvis-os-agent/tree/main/tools"
click node_mcp "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/mcp/MCPManager.py"
click node_mobile "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/tools/MobileBridge/server.py"
click node_proactive "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/Proactive/proactive_agent.py"
click node_events "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/Proactive/event_queue.py"
click node_channels "https://github.com/thekaifansari01/jarvis-os-agent/tree/main/Proactive"
click node_tts "https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/voice/tts.py"
click node_ui "https://github.com/thekaifansari01/jarvis-os-agent/tree/main/core/ui"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_handler,node_processor,node_agentbrain,node_fastbrain,node_executor,node_user toneBlue
class node_memory,node_ltm,node_behavior,node_rag,node_indexer toneAmber
class node_voicein,node_hotkey,node_remote,node_tts,node_ui toneMint
class node_tools,node_mcp,node_mobile toneRose
class node_proactive,node_events,node_channels toneIndigo
```

## Components

### Command Runtime

- [Application Startup](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/main.py): `main.py`
- [Command Handler](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/main/CommandHandler.py): `core/main/CommandHandler.py`
- [Command Processor](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Processor/Processor.py): `core/brain/Processor/Processor.py`
- [Agentic Brain](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Processor/AgenticBrain.py): `core/brain/Processor/AgenticBrain.py`
- [Fast Brain](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Processor/FastBrain.py): `core/brain/Processor/FastBrain.py`
- [Action Executor](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/executor.py): `core/brain/executor.py`

### Memory and Retrieval

- [Context Memory](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Memory/Memory.py): `core/brain/Memory/Memory.py`
- [Lifetime Memory](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Memory/LifetimeMemory.py): `core/brain/Memory/LifetimeMemory.py`
- [Behavior Patterns](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/Memory/BehavioralEngine.py): `core/brain/Memory/BehavioralEngine.py`
- [Hybrid RAG](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/brain/RagEngine.py): `core/brain/RagEngine.py`
- [Knowledge Indexer](https://github.com/thekaifansari01/jarvis-os-agent/tree/main/core/brain/Indexer): `core/brain/Indexer`

### Voice and Interfaces

- [Voice Input](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/voice/stt.py): `core/voice/stt.py`
- [Keyboard Input](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/main/HotKeyManager.py): `core/main/HotKeyManager.py`
- [Telegram Remote](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/main/TelegramRemoteBot.py): `core/main/TelegramRemoteBot.py`
- [Speech Output](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/voice/tts.py): `core/voice/tts.py`
- [Desktop Interfaces](https://github.com/thekaifansari01/jarvis-os-agent/tree/main/core/ui): `core/ui`

### Tools and Integrations

- [Native Tools](https://github.com/thekaifansari01/jarvis-os-agent/tree/main/tools): `tools`
- [MCP Manager](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/core/mcp/MCPManager.py): `core/mcp/MCPManager.py`
- [Mobile Bridge](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/tools/MobileBridge/server.py): `tools/MobileBridge/server.py`

### Proactive Services

- [Proactive Agent](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/Proactive/proactive_agent.py): `Proactive/proactive_agent.py`
- [Event Queue](https://github.com/thekaifansari01/jarvis-os-agent/blob/main/Proactive/event_queue.py): `Proactive/event_queue.py`
- [Proactive Channels](https://github.com/thekaifansari01/jarvis-os-agent/tree/main/Proactive): `Proactive`

### Other components

- **User**

## Connections

- User → Voice Input: speaks to
- User → Keyboard Input: types via
- User → Telegram Remote: commands via
- Application Startup → Command Handler: starts (evidence: `main.py`)
- Application Startup → Voice Input: starts (evidence: `main.py`)
- Voice Input → Command Handler: submits command
- Keyboard Input → Command Handler: dispatches command (evidence: `core/main/HotKeyManager.py`)
- Telegram Remote → Command Handler: routes command (evidence: `core/main/TelegramRemoteBot.py`)
- Command Handler → Command Processor: processes command (evidence: `core/main/CommandHandler.py`)
- Command Processor → Agentic Brain: selects complex tasks
- Command Processor → Fast Brain: selects simple tasks
- Command Handler → Action Executor: executes actions (evidence: `core/main/CommandHandler.py`)
- Command Handler → Context Memory: records exchange (evidence: `core/main/CommandHandler.py`)
- Agentic Brain → Context Memory: uses memory
- Fast Brain → Context Memory: uses memory
- Context Memory → Lifetime Memory: uses lifetime store (evidence: `core/brain/Memory/Memory.py`)
- Context Memory → Behavior Patterns: uses patterns (evidence: `core/brain/Memory/Memory.py`)
- Agentic Brain → Native Tools: invokes tools
- Fast Brain → Native Tools: invokes tools
- Agentic Brain → MCP Manager: uses MCP tools
- Application Startup → Hybrid RAG: starts service
- Hybrid RAG → Knowledge Indexer: loads index settings (evidence: `core/brain/RagEngine.py`)
- Application Startup → Proactive Agent: starts (evidence: `main.py`)
- Proactive Agent → Event Queue: queues events (evidence: `Proactive/proactive_agent.py`)
- Proactive Agent → Proactive Channels: dispatches outreach (evidence: `Proactive/proactive_agent.py`)
- Application Startup → MCP Manager: starts service
- Native Tools → Mobile Bridge: includes bridge
- Command Handler → Speech Output: speaks response
- Application Startup → Desktop Interfaces: starts interfaces (evidence: `main.py`)