# treevu-ai/jarvis architecture

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

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

## Overview

Jarvis is a local, voice-first conversational assistant with persistent memory, tool use, and a separate offline dictation mode. The main interaction runs from listening and wake-word handling through reply generation, which can enrich context, select and execute tools, and return speech. Memory, MCP integrations, and the desktop controls are distinct product capabilities. The excerpts are partial, so links for unsampled subsystem internals are limited to the documented workflow and repository structure.

Main entry points: [`src/jarvis/reply/engine.py`](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/reply/engine.py) (Reply engine), [`src/jarvis/listening/listener.py`](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/listener.py) (Audio listener), [`src/desktop_app/app.py`](https://github.com/treevu-ai/jarvis/blob/main/src/desktop_app/app.py) (Desktop app), [`src/jarvis/reply/planner.py`](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/reply/planner.py) (Tool planner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice assistant"]
  node_daemon["Assistant daemon<br/>[daemon.py]"]
  node_listener["Audio listener<br/>[listener.py]"]
  node_wake["Wake detection<br/>[wake_detection.py]"]
  node_intent["Intent judge<br/>[intent_judge.py]"]
  node_state["Listening state<br/>[state_manager.py]"]
  node_tts["Speech output<br/>[tts.py]"]
end

subgraph group_reply["Conversation and tools"]
  node_replyengine["Reply engine<br/>[engine.py]"]
  node_planner["Tool planner<br/>[planner.py]"]
  node_selection["Tool selection<br/>[selection.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_builtin["Built-in tools"]
  node_mcp["MCP client<br/>[mcp_client.py]"]
end

subgraph group_memory["Persistent memory"]
  node_memory["Memory services"]
  node_conversations["Conversation memory<br/>[conversation.py]"]
  node_graphmemory["Knowledge graph<br/>[graph.py]"]
  node_database[("Memory database<br/>[db.py]")]
end

subgraph group_dictation["Offline dictation"]
  node_dictation["Dictation engine"]
  node_history[("Dictation history<br/>[history.py]")]
end

subgraph group_desktop["Desktop controls"]
  node_desktop["Desktop app<br/>[app.py]"]
  node_setup["Setup wizard<br/>[setup_wizard.py]"]
  node_viewer["Memory viewer<br/>[memory_viewer.py]"]
end

node_user(("Speaker"))
node_mcpservers{{"MCP servers"}}
node_llm{{"Local Ollama"}}
node_hotkeyuser(("Hotkey user"))
node_computer{{"Clipboard and apps"}}

node_user -->|"speaks to"| node_listener
node_daemon -->|"runs"| node_listener
node_listener -->|"detects wake"| node_wake
node_listener -->|"updates state"| node_state
node_listener -->|"judges transcript"| node_intent
node_intent -->|"directs query"| node_replyengine
node_replyengine -->|"requests response"| node_llm
node_replyengine -->|"plans tools"| node_planner
node_replyengine -->|"enriches context"| node_memory
node_replyengine -->|"speaks reply"| node_tts
node_tts -->|"returns speech"| node_user
node_planner -->|"narrows tools"| node_selection
node_planner -->|"resolves tools"| node_registry
node_registry -->|"provides tools"| node_builtin
node_registry -.->|"provides MCP tools"| node_mcp
node_mcp -.->|"calls tools"| node_mcpservers
node_memory -->|"uses"| node_conversations
node_memory -->|"uses"| node_graphmemory
node_conversations -->|"reads and writes"| node_database
node_graphmemory -->|"reads and writes"| node_database
node_hotkeyuser -->|"holds hotkey"| node_dictation
node_dictation -->|"records history"| node_history
node_dictation -->|"pastes text"| node_computer
node_desktop -->|"starts and controls"| node_daemon
node_desktop -->|"opens setup"| node_setup
node_viewer -->|"views memory"| node_database
node_desktop -->|"opens viewer"| node_viewer
node_setup -->|"configures assistant"| node_daemon

click node_daemon "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/daemon.py"
click node_listener "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/listener.py"
click node_wake "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/wake_detection.py"
click node_intent "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/intent_judge.py"
click node_state "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/state_manager.py"
click node_tts "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/output/tts.py"
click node_replyengine "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/reply/engine.py"
click node_planner "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/reply/planner.py"
click node_selection "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/tools/selection.py"
click node_registry "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/tools/registry.py"
click node_builtin "https://github.com/treevu-ai/jarvis/tree/main/src/jarvis/tools/builtin"
click node_mcp "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/tools/external/mcp_client.py"
click node_memory "https://github.com/treevu-ai/jarvis/tree/main/src/jarvis/memory"
click node_conversations "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/memory/conversation.py"
click node_graphmemory "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/memory/graph.py"
click node_database "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/memory/db.py"
click node_dictation "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/dictation/dictation_engine.py"
click node_history "https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/dictation/history.py"
click node_desktop "https://github.com/treevu-ai/jarvis/blob/main/src/desktop_app/app.py"
click node_setup "https://github.com/treevu-ai/jarvis/blob/main/src/desktop_app/setup_wizard.py"
click node_viewer "https://github.com/treevu-ai/jarvis/blob/main/src/desktop_app/memory_viewer.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_daemon,node_listener,node_wake,node_intent,node_state,node_tts,node_hotkeyuser toneBlue
class node_replyengine,node_planner,node_selection,node_registry,node_builtin,node_mcp toneAmber
class node_memory,node_conversations,node_graphmemory,node_database,node_mcpservers toneMint
class node_dictation,node_history toneRose
class node_desktop,node_setup,node_viewer,node_user,node_llm,node_computer toneIndigo
```

## Components

### Voice assistant

- [Assistant daemon](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/daemon.py): `src/jarvis/daemon.py`
- [Audio listener](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/listener.py): `src/jarvis/listening/listener.py`
- [Wake detection](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/wake_detection.py): `src/jarvis/listening/wake_detection.py`
- [Intent judge](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/intent_judge.py): `src/jarvis/listening/intent_judge.py`
- [Listening state](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/listening/state_manager.py): `src/jarvis/listening/state_manager.py`
- [Speech output](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/output/tts.py): `src/jarvis/output/tts.py`

### Conversation and tools

- [Reply engine](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/reply/engine.py): `src/jarvis/reply/engine.py`
- [Tool planner](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/reply/planner.py): `src/jarvis/reply/planner.py`
- [Tool selection](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/tools/selection.py): `src/jarvis/tools/selection.py`
- [Tool registry](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/tools/registry.py): `src/jarvis/tools/registry.py`
- [Built-in tools](https://github.com/treevu-ai/jarvis/tree/main/src/jarvis/tools/builtin): `src/jarvis/tools/builtin`
- [MCP client](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/tools/external/mcp_client.py): `src/jarvis/tools/external/mcp_client.py`

### Persistent memory

- [Memory services](https://github.com/treevu-ai/jarvis/tree/main/src/jarvis/memory): `src/jarvis/memory`
- [Conversation memory](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/memory/conversation.py): `src/jarvis/memory/conversation.py`
- [Knowledge graph](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/memory/graph.py): `src/jarvis/memory/graph.py`
- [Memory database](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/memory/db.py): `src/jarvis/memory/db.py`

### Offline dictation

- [Dictation engine](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/dictation/dictation_engine.py): `src/jarvis/dictation/dictation_engine.py`
- [Dictation history](https://github.com/treevu-ai/jarvis/blob/main/src/jarvis/dictation/history.py): `src/jarvis/dictation/history.py`

### Desktop controls

- [Desktop app](https://github.com/treevu-ai/jarvis/blob/main/src/desktop_app/app.py): `src/desktop_app/app.py`
- [Setup wizard](https://github.com/treevu-ai/jarvis/blob/main/src/desktop_app/setup_wizard.py): `src/desktop_app/setup_wizard.py`
- [Memory viewer](https://github.com/treevu-ai/jarvis/blob/main/src/desktop_app/memory_viewer.py): `src/desktop_app/memory_viewer.py`

### Other components

- **Speaker**
- **MCP servers**
- **Local Ollama**
- **Hotkey user**
- **Clipboard and apps**

## Connections

- Speaker → Audio listener: speaks to
- Assistant daemon → Audio listener: runs
- Audio listener → Wake detection: detects wake
- Audio listener → Listening state: updates state
- Audio listener → Intent judge: judges transcript
- Intent judge → Reply engine: directs query
- Reply engine → Local Ollama: requests response
- Reply engine → Tool planner: plans tools
- Reply engine → Memory services: enriches context
- Reply engine → Speech output: speaks reply
- Speech output → Speaker: returns speech
- Tool planner → Tool selection: narrows tools
- Tool planner → Tool registry: resolves tools
- Tool registry → Built-in tools: provides tools
- Tool registry → MCP client: provides MCP tools
- MCP client → MCP servers: calls tools
- Memory services → Conversation memory: uses
- Memory services → Knowledge graph: uses
- Conversation memory → Memory database: reads and writes
- Knowledge graph → Memory database: reads and writes
- Hotkey user → Dictation engine: holds hotkey
- Dictation engine → Dictation history: records history
- Dictation engine → Clipboard and apps: pastes text
- Desktop app → Assistant daemon: starts and controls
- Desktop app → Setup wizard: opens setup
- Memory viewer → Memory database: views memory
- Desktop app → Memory viewer: opens viewer
- Setup wizard → Assistant daemon: configures assistant