# harshpratapsinghhh/myra architecture

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

- Interactive diagram: https://gitdiagram.com/harshpratapsinghhh/myra
- Repository: https://github.com/harshpratapsinghhh/myra

## Overview

MYRA is a voice-and-text personal assistant. Its main loop checks for proactive idle behavior, waits for wake-word activation, listens for a command, and passes it to the brain for intent-based actions or conversational handling; responses are spoken back. Music playback and controls are a prominent action branch, with short- and long-term state supporting context, recommendations, and behavior-aware suggestions. The README also documents mood-aware personality and hybrid rule/LLM conversation. Some brain internals and integrations were not sampled, so only documented or indexed relationships are shown.

Main entry points: [`core/brain.py`](https://github.com/harshpratapsinghhh/myra/blob/main/core/brain.py) (Command brain), [`core/proactive_engine.py`](https://github.com/harshpratapsinghhh/myra/blob/main/core/proactive_engine.py) (Proactive layer), [`main.py`](https://github.com/harshpratapsinghhh/myra/blob/main/main.py) (Voice loop), [`core/memory_engine.py`](https://github.com/harshpratapsinghhh/myra/blob/main/core/memory_engine.py) (Memory engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction"]
  node_main_loop["Voice loop<br/>[main.py]"]
  node_text_mode["Text mode<br/>[run.py]"]
  node_wake_detection["Wake detection<br/>[wake_word.py]"]
  node_voice_capture["Voice listener<br/>[voice_listener.py]"]
end

subgraph group_reasoning["Assistant reasoning"]
  node_brain["Command brain<br/>[brain.py]"]
  node_intent["Intent detection<br/>[intent_engine.py]"]
  node_conversation["Conversation"]
  node_ai_brain["AI brain<br/>[ai_brain.py]"]
  node_personality["Personality"]
  node_suggestions["Mood suggestions"]
  node_proactive["Proactive layer"]
  node_decisions["Confidence decisions<br/>[decision_engine.py]"]
  node_prediction["Prediction"]
  node_recommendations["Recommendations"]
  node_profile["User profile<br/>[profile_engine.py]"]
end

subgraph group_actions["Actions"]
  node_music_actions["Music controls<br/>[music_actions.py]"]
  node_music_player["Music player<br/>[music_player.py]"]
  node_system_actions["System actions<br/>[system_actions.py]"]
  node_web_actions["Web actions<br/>[web_actions.py]"]
end

subgraph group_state["Memory and state"]
  node_memory_engine["Memory engine<br/>[memory_engine.py]"]
  node_short_memory[("Session memory<br/>[memory.json]")]
  node_long_history[("Long-term history<br/>[history.json]")]
end

subgraph group_delivery["Response delivery"]
  node_speaker["Speech output<br/>[speaker.py]"]
  node_voice_engine["Voice generation<br/>[voice_engine.py]"]
end

node_user(("User"))
node_openai{{"OpenAI service"}}

node_user -->|"speaks commands"| node_main_loop
node_main_loop -->|"waits for wake"| node_wake_detection
node_wake_detection -.->|"activates listening"| node_voice_capture
node_main_loop -->|"captures input"| node_voice_capture
node_main_loop -->|"processes command"| node_brain
node_main_loop -->|"checks idle"| node_proactive
node_main_loop -->|"checks prediction"| node_prediction
node_main_loop -->|"falls back"| node_text_mode
node_text_mode -->|"processes command"| node_brain
node_text_mode -->|"checks idle"| node_proactive
node_brain -->|"detects intent"| node_intent
node_brain -->|"handles conversation"| node_conversation
node_brain -->|"requests AI reply"| node_ai_brain
node_ai_brain -.->|"requests dialogue"| node_openai
node_brain -->|"dispatches music"| node_music_actions
node_brain -->|"dispatches app action"| node_system_actions
node_brain -->|"dispatches search"| node_web_actions
node_music_actions -->|"delegates playback"| node_music_player
node_music_player -->|"updates playback state"| node_memory_engine
node_brain -->|"reads and updates context"| node_memory_engine
node_memory_engine -->|"reads and writes"| node_short_memory
node_memory_engine -->|"reads and writes"| node_long_history
node_brain -->|"detects mood"| node_suggestions
node_proactive -->|"gets recommendation"| node_recommendations
node_proactive -->|"scores confidence"| node_decisions
node_proactive -->|"sets pending action"| node_suggestions
node_proactive -->|"starts music"| node_music_actions
node_proactive -->|"reads activity and mood"| node_memory_engine
node_personality -.->|"adapts response tone"| node_user
node_brain -->|"formats action response"| node_personality
node_conversation -->|"uses conversation memory"| node_memory_engine
node_brain -->|"speaks response"| node_speaker
node_proactive -->|"speaks prompt"| node_speaker
node_speaker -->|"generates audio"| node_voice_engine
node_voice_engine -.->|"returns speech"| node_user

click node_main_loop "https://github.com/harshpratapsinghhh/myra/blob/main/main.py"
click node_text_mode "https://github.com/harshpratapsinghhh/myra/blob/main/run.py"
click node_wake_detection "https://github.com/harshpratapsinghhh/myra/blob/main/input/wake_word.py"
click node_voice_capture "https://github.com/harshpratapsinghhh/myra/blob/main/input/voice_listener.py"
click node_brain "https://github.com/harshpratapsinghhh/myra/blob/main/core/brain.py"
click node_intent "https://github.com/harshpratapsinghhh/myra/blob/main/core/intent_engine.py"
click node_conversation "https://github.com/harshpratapsinghhh/myra/blob/main/core/conversation_engine.py"
click node_ai_brain "https://github.com/harshpratapsinghhh/myra/blob/main/core/ai_brain.py"
click node_personality "https://github.com/harshpratapsinghhh/myra/blob/main/core/personality_engine.py"
click node_suggestions "https://github.com/harshpratapsinghhh/myra/blob/main/core/suggestion_engine.py"
click node_proactive "https://github.com/harshpratapsinghhh/myra/blob/main/core/proactive_engine.py"
click node_decisions "https://github.com/harshpratapsinghhh/myra/blob/main/core/decision_engine.py"
click node_prediction "https://github.com/harshpratapsinghhh/myra/blob/main/core/prediction_engine.py"
click node_recommendations "https://github.com/harshpratapsinghhh/myra/blob/main/core/recommendation_engine.py"
click node_profile "https://github.com/harshpratapsinghhh/myra/blob/main/core/profile_engine.py"
click node_music_actions "https://github.com/harshpratapsinghhh/myra/blob/main/actions/music_actions.py"
click node_music_player "https://github.com/harshpratapsinghhh/myra/blob/main/actions/music_player.py"
click node_system_actions "https://github.com/harshpratapsinghhh/myra/blob/main/actions/system_actions.py"
click node_web_actions "https://github.com/harshpratapsinghhh/myra/blob/main/actions/web_actions.py"
click node_memory_engine "https://github.com/harshpratapsinghhh/myra/blob/main/core/memory_engine.py"
click node_short_memory "https://github.com/harshpratapsinghhh/myra/blob/main/data/memory.json"
click node_long_history "https://github.com/harshpratapsinghhh/myra/blob/main/data/history.json"
click node_speaker "https://github.com/harshpratapsinghhh/myra/blob/main/output/speaker.py"
click node_voice_engine "https://github.com/harshpratapsinghhh/myra/blob/main/output/voice_engine.py"

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_loop,node_text_mode,node_wake_detection,node_voice_capture,node_user toneBlue
class node_brain,node_intent,node_conversation,node_ai_brain,node_personality,node_suggestions,node_proactive,node_decisions,node_prediction,node_recommendations,node_profile toneAmber
class node_music_actions,node_music_player,node_system_actions,node_web_actions toneMint
class node_memory_engine,node_short_memory,node_long_history toneRose
class node_speaker,node_voice_engine,node_openai toneIndigo
```

## Components

### Interaction

- [Voice loop](https://github.com/harshpratapsinghhh/myra/blob/main/main.py): `main.py`
- [Text mode](https://github.com/harshpratapsinghhh/myra/blob/main/run.py): `run.py`
- [Wake detection](https://github.com/harshpratapsinghhh/myra/blob/main/input/wake_word.py): `input/wake_word.py`
- [Voice listener](https://github.com/harshpratapsinghhh/myra/blob/main/input/voice_listener.py): `input/voice_listener.py`

### Assistant reasoning

- [Command brain](https://github.com/harshpratapsinghhh/myra/blob/main/core/brain.py): `core/brain.py`
- [Intent detection](https://github.com/harshpratapsinghhh/myra/blob/main/core/intent_engine.py): `core/intent_engine.py`
- [Conversation](https://github.com/harshpratapsinghhh/myra/blob/main/core/conversation_engine.py): `core/conversation_engine.py`
- [AI brain](https://github.com/harshpratapsinghhh/myra/blob/main/core/ai_brain.py): `core/ai_brain.py`
- [Personality](https://github.com/harshpratapsinghhh/myra/blob/main/core/personality_engine.py): `core/personality_engine.py`
- [Mood suggestions](https://github.com/harshpratapsinghhh/myra/blob/main/core/suggestion_engine.py): `core/suggestion_engine.py`
- [Proactive layer](https://github.com/harshpratapsinghhh/myra/blob/main/core/proactive_engine.py): `core/proactive_engine.py`
- [Confidence decisions](https://github.com/harshpratapsinghhh/myra/blob/main/core/decision_engine.py): `core/decision_engine.py`
- [Prediction](https://github.com/harshpratapsinghhh/myra/blob/main/core/prediction_engine.py): `core/prediction_engine.py`
- [Recommendations](https://github.com/harshpratapsinghhh/myra/blob/main/core/recommendation_engine.py): `core/recommendation_engine.py`
- [User profile](https://github.com/harshpratapsinghhh/myra/blob/main/core/profile_engine.py): `core/profile_engine.py`

### Actions

- [Music controls](https://github.com/harshpratapsinghhh/myra/blob/main/actions/music_actions.py): `actions/music_actions.py`
- [Music player](https://github.com/harshpratapsinghhh/myra/blob/main/actions/music_player.py): `actions/music_player.py`
- [System actions](https://github.com/harshpratapsinghhh/myra/blob/main/actions/system_actions.py): `actions/system_actions.py`
- [Web actions](https://github.com/harshpratapsinghhh/myra/blob/main/actions/web_actions.py): `actions/web_actions.py`

### Memory and state

- [Memory engine](https://github.com/harshpratapsinghhh/myra/blob/main/core/memory_engine.py): `core/memory_engine.py`
- [Session memory](https://github.com/harshpratapsinghhh/myra/blob/main/data/memory.json): `data/memory.json`
- [Long-term history](https://github.com/harshpratapsinghhh/myra/blob/main/data/history.json): `data/history.json`

### Response delivery

- [Speech output](https://github.com/harshpratapsinghhh/myra/blob/main/output/speaker.py): `output/speaker.py`
- [Voice generation](https://github.com/harshpratapsinghhh/myra/blob/main/output/voice_engine.py): `output/voice_engine.py`

### Other components

- **User**
- **OpenAI service**

## Connections

- User → Voice loop: speaks commands (evidence: `README.md`)
- Voice loop → Wake detection: waits for wake (evidence: `main.py`)
- Wake detection → Voice listener: activates listening (evidence: `input/wake_word.py`)
- Voice loop → Voice listener: captures input (evidence: `main.py`)
- Voice loop → Command brain: processes command (evidence: `main.py`)
- Voice loop → Proactive layer: checks idle (evidence: `main.py`)
- Voice loop → Prediction: checks prediction (evidence: `main.py`)
- Voice loop → Text mode: falls back (evidence: `main.py`)
- Text mode → Command brain: processes command (evidence: `run.py`)
- Text mode → Proactive layer: checks idle (evidence: `run.py`)
- Command brain → Intent detection: detects intent (evidence: `core/brain.py`)
- Command brain → Conversation: handles conversation (evidence: `core/brain.py`)
- Command brain → AI brain: requests AI reply (evidence: `core/brain.py`)
- AI brain → OpenAI service: requests dialogue (evidence: `README.md`)
- Command brain → Music controls: dispatches music (evidence: `core/brain.py`)
- Command brain → System actions: dispatches app action (evidence: `core/brain.py`)
- Command brain → Web actions: dispatches search (evidence: `core/brain.py`)
- Music controls → Music player: delegates playback (evidence: `actions/music_actions.py`)
- Music player → Memory engine: updates playback state (evidence: `actions/music_player.py`)
- Command brain → Memory engine: reads and updates context (evidence: `core/brain.py`)
- Memory engine → Session memory: reads and writes (evidence: `core/memory_engine.py`)
- Memory engine → Long-term history: reads and writes (evidence: `core/memory_engine.py`)
- Command brain → Mood suggestions: detects mood (evidence: `core/brain.py`)
- Proactive layer → Recommendations: gets recommendation (evidence: `core/proactive_engine.py`)
- Proactive layer → Confidence decisions: scores confidence (evidence: `core/proactive_engine.py`)
- Proactive layer → Mood suggestions: sets pending action (evidence: `core/proactive_engine.py`)
- Proactive layer → Music controls: starts music (evidence: `core/proactive_engine.py`)
- Proactive layer → Memory engine: reads activity and mood (evidence: `core/proactive_engine.py`)
- Personality → User: adapts response tone
- Command brain → Personality: formats action response (evidence: `core/brain.py`)
- Conversation → Memory engine: uses conversation memory (evidence: `core/conversation_engine.py`)
- Command brain → Speech output: speaks response (evidence: `core/brain.py`)
- Proactive layer → Speech output: speaks prompt (evidence: `core/proactive_engine.py`)
- Speech output → Voice generation: generates audio (evidence: `output/speaker.py`)
- Voice generation → User: returns speech