# itzshrvsh/moshi architecture

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

- Interactive diagram: https://gitdiagram.com/itzshrvsh/moshi
- Repository: https://github.com/itzshrvsh/moshi

## Overview

#### Purpose and Entry Points
This repository appears to be a local “Moshi” agent/runtime workspace: it combines lifecycle/process management, Android and tunnel capabilities, persistent memory, and Telegram bot interfaces. There is no README content, so behavior must be confirmed from implementation.

Likely operational entry points:
- `start_moshi.sh`
- `start_moshi.bat`
- `memory_server.py`
- `telegram/bot.py`

#### Moshi Runtime Orchestration
The Moshi-prefixed modules form the primary runtime/control plane. They likely define startup configuration, lifecycle transitions, process execution, capability registration, and health diagnostics:
- `moshi_config.py`
- `moshi_lifecycle.py`
- `moshi_process.py`

`moshi_manifest.py` and `moshi_capability.py` likely provide the declared contract for enabled functions/components, separating what the runtime can expose from how each capability executes.

#### Device, Artifact, and Connectivity Capabilities
Android interaction, artifact handling, and external connectivity appear to be distinct capability domains:
- `moshi_android.py`
- `moshi_artifact.py`
- `moshi_tunnel.py`

This separation suggests the core runtime delegates infrastructure-specific work rather than embedding device or network logic directly in lifecycle management. Tunnel behavior is a material boundary because it may expose local services or connect the runtime to remote consumers.

#### Memory Service Boundary
Persistent or retrievable agent memory is isolated under a dedicated package and service wrapper:
- `mem0/memory.py`
- `memory_server.py`
- `memory_mcp.py`

`mem0/memory.py` is the apparent storage/domain layer. `memory_server.py` likely exposes it as a running service, while `memory_mcp.py` likely adapts memory operations to an MCP-oriented protocol or client boundary. This keeps agent memory usable independently of a specific chat interface.

#### Chat and Agent Interfaces
Telegram is an external-facing channel with several implementation variants:
- `telegram/bot.py`
- `telegram/bot_agent_final.py`
- `telegram/bot_upgraded.py`

The primary intended bot should be established before deployment; the variant names indicate iterative or backup implementations rather than a single unambiguous production entry point. The bot layer should call into the Moshi runtime and/or memory service rather than own core execution state.

#### Operational Validation and Diagnostics
Runtime verification is represented by dedicated orchestration and diagnostic modules:
- `moshi_doctor.py`
- `moshi_e2e.py`
- `moshi_manifest.py`

`moshi_doctor.py` likely checks environment/runtime prerequisites, while `moshi_e2e.py` appears to exercise integrated flows across services. `moshi_manifest.py` is architecturally important as the likely source of truth for what a running Moshi instance exposes.

#### Deployment Shape
The repository is primarily Python with platform-specific launch wrappers:
- `start_moshi.sh`
- `start_moshi.bat`
- `opencode.json`

Expected execution flow is: launcher initializes Moshi configuration and lifecycle management; the runtime starts required processes/capabilities; optional memory and Telegram services connect at their respective boundaries; diagnostics/e2e paths validate the assembled system.

Main entry points: [`moshi_lifecycle.py`](https://github.com/itzshrvsh/moshi/blob/main/moshi_lifecycle.py) (Lifecycle manager), [`memory_server.py`](https://github.com/itzshrvsh/moshi/blob/main/memory_server.py) (Memory server), [`moshi_capability.py`](https://github.com/itzshrvsh/moshi/blob/main/moshi_capability.py) (Capability registry), [`moshi_config.py`](https://github.com/itzshrvsh/moshi/blob/main/moshi_config.py) (Runtime config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Moshi Runtime"]
  node_shell_launcher["Shell launcher<br/>entry point<br/>[start_moshi.sh]"]
  node_batch_launcher["Windows launcher<br/>entry point<br/>[start_moshi.bat]"]
  node_config["Runtime config<br/>configuration<br/>[moshi_config.py]"]
  node_lifecycle["Lifecycle manager<br/>orchestrator<br/>[moshi_lifecycle.py]"]
  node_process["Process manager<br/>process execution<br/>[moshi_process.py]"]
  node_manifest["Capability manifest<br/>runtime contract<br/>[moshi_manifest.py]"]
  node_capability["Capability registry<br/>capability contract"]
  node_doctor["Runtime doctor<br/>diagnostics<br/>[moshi_doctor.py]"]
  node_e2e["End-to-end validation<br/>integration validation<br/>[moshi_e2e.py]"]
end

subgraph group_capabilities["Capabilities"]
  node_android["Android capability<br/>device integration<br/>[moshi_android.py]"]
  node_artifact["Artifact capability<br/>artifact handling<br/>[moshi_artifact.py]"]
  node_tunnel["Tunnel capability<br/>connectivity<br/>[moshi_tunnel.py]"]
end

subgraph group_memory["Memory Service"]
  node_memory_domain[("Memory domain<br/>persistent memory<br/>[memory.py]")]
  node_memory_server["Memory server<br/>service wrapper<br/>[memory_server.py]"]
  node_memory_mcp["Memory MCP adapter<br/>MCP integration<br/>[memory_mcp.py]"]
end

subgraph group_interfaces["External Interfaces"]
  node_telegram_bot["Telegram bot<br/>chat interface<br/>[bot.py]"]
  node_telegram_final["Final bot variant<br/>chat interface variant<br/>[bot_agent_final.py]"]
  node_telegram_upgraded["Upgraded bot variant<br/>chat interface variant<br/>[bot_upgraded.py]"]
end

node_shell_launcher -->|"loads"| node_config
node_batch_launcher -->|"loads"| node_config
node_config -->|"configures"| node_lifecycle
node_lifecycle -->|"manages"| node_process
node_lifecycle -->|"uses"| node_manifest
node_manifest -->|"declares"| node_capability
node_capability -->|"registers"| node_android
node_capability -->|"registers"| node_artifact
node_capability -->|"registers"| node_tunnel
node_lifecycle -.->|"starts optionally"| node_memory_server
node_memory_server -->|"serves"| node_memory_domain
node_memory_mcp -->|"adapts"| node_memory_server
node_telegram_bot -.->|"invokes runtime"| node_lifecycle
node_telegram_bot -.->|"uses memory"| node_memory_server
node_telegram_final -.->|"alternative interface"| node_lifecycle
node_telegram_upgraded -.->|"alternative interface"| node_lifecycle
node_doctor -.->|"checks"| node_lifecycle
node_e2e -.->|"validates"| node_lifecycle
node_e2e -.->|"validates"| node_memory_server

click node_shell_launcher "https://github.com/itzshrvsh/moshi/blob/main/start_moshi.sh"
click node_batch_launcher "https://github.com/itzshrvsh/moshi/blob/main/start_moshi.bat"
click node_config "https://github.com/itzshrvsh/moshi/blob/main/moshi_config.py"
click node_lifecycle "https://github.com/itzshrvsh/moshi/blob/main/moshi_lifecycle.py"
click node_process "https://github.com/itzshrvsh/moshi/blob/main/moshi_process.py"
click node_manifest "https://github.com/itzshrvsh/moshi/blob/main/moshi_manifest.py"
click node_capability "https://github.com/itzshrvsh/moshi/blob/main/moshi_capability.py"
click node_android "https://github.com/itzshrvsh/moshi/blob/main/moshi_android.py"
click node_artifact "https://github.com/itzshrvsh/moshi/blob/main/moshi_artifact.py"
click node_tunnel "https://github.com/itzshrvsh/moshi/blob/main/moshi_tunnel.py"
click node_memory_domain "https://github.com/itzshrvsh/moshi/blob/main/mem0/memory.py"
click node_memory_server "https://github.com/itzshrvsh/moshi/blob/main/memory_server.py"
click node_memory_mcp "https://github.com/itzshrvsh/moshi/blob/main/memory_mcp.py"
click node_telegram_bot "https://github.com/itzshrvsh/moshi/blob/main/telegram/bot.py"
click node_telegram_final "https://github.com/itzshrvsh/moshi/blob/main/telegram/bot_agent_final.py"
click node_telegram_upgraded "https://github.com/itzshrvsh/moshi/blob/main/telegram/bot_upgraded.py"
click node_doctor "https://github.com/itzshrvsh/moshi/blob/main/moshi_doctor.py"
click node_e2e "https://github.com/itzshrvsh/moshi/blob/main/moshi_e2e.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_shell_launcher,node_batch_launcher,node_config,node_lifecycle,node_process,node_manifest,node_capability,node_doctor,node_e2e toneBlue
class node_android,node_artifact,node_tunnel toneAmber
class node_memory_domain,node_memory_server,node_memory_mcp toneMint
class node_telegram_bot,node_telegram_final,node_telegram_upgraded toneRose
```

## Components

### Moshi Runtime

- [Shell launcher](https://github.com/itzshrvsh/moshi/blob/main/start_moshi.sh): entry point · `start_moshi.sh`
- [Windows launcher](https://github.com/itzshrvsh/moshi/blob/main/start_moshi.bat): entry point · `start_moshi.bat`
- [Runtime config](https://github.com/itzshrvsh/moshi/blob/main/moshi_config.py): configuration · `moshi_config.py`
- [Lifecycle manager](https://github.com/itzshrvsh/moshi/blob/main/moshi_lifecycle.py): orchestrator · Coordinates runtime startup and transitions. · `moshi_lifecycle.py`
- [Process manager](https://github.com/itzshrvsh/moshi/blob/main/moshi_process.py): process execution · `moshi_process.py`
- [Capability manifest](https://github.com/itzshrvsh/moshi/blob/main/moshi_manifest.py): runtime contract · Declares functions and components exposed by Moshi. · `moshi_manifest.py`
- [Capability registry](https://github.com/itzshrvsh/moshi/blob/main/moshi_capability.py): capability contract · `moshi_capability.py`
- [Runtime doctor](https://github.com/itzshrvsh/moshi/blob/main/moshi_doctor.py): diagnostics · Checks environment and runtime prerequisites. · `moshi_doctor.py`
- [End-to-end validation](https://github.com/itzshrvsh/moshi/blob/main/moshi_e2e.py): integration validation · Exercises assembled service flows. · `moshi_e2e.py`

### Capabilities

- [Android capability](https://github.com/itzshrvsh/moshi/blob/main/moshi_android.py): device integration · `moshi_android.py`
- [Artifact capability](https://github.com/itzshrvsh/moshi/blob/main/moshi_artifact.py): artifact handling · `moshi_artifact.py`
- [Tunnel capability](https://github.com/itzshrvsh/moshi/blob/main/moshi_tunnel.py): connectivity · Exposes local services or connects remote consumers. · `moshi_tunnel.py`

### Memory Service

- [Memory domain](https://github.com/itzshrvsh/moshi/blob/main/mem0/memory.py): persistent memory · `mem0/memory.py`
- [Memory server](https://github.com/itzshrvsh/moshi/blob/main/memory_server.py): service wrapper · `memory_server.py`
- [Memory MCP adapter](https://github.com/itzshrvsh/moshi/blob/main/memory_mcp.py): MCP integration · `memory_mcp.py`

### External Interfaces

- [Telegram bot](https://github.com/itzshrvsh/moshi/blob/main/telegram/bot.py): chat interface · Primary bot implementation is not confirmed. · `telegram/bot.py`
- [Final bot variant](https://github.com/itzshrvsh/moshi/blob/main/telegram/bot_agent_final.py): chat interface variant · `telegram/bot_agent_final.py`
- [Upgraded bot variant](https://github.com/itzshrvsh/moshi/blob/main/telegram/bot_upgraded.py): chat interface variant · `telegram/bot_upgraded.py`

## Connections

- Shell launcher → Runtime config: loads
- Windows launcher → Runtime config: loads
- Runtime config → Lifecycle manager: configures
- Lifecycle manager → Process manager: manages
- Lifecycle manager → Capability manifest: uses
- Capability manifest → Capability registry: declares
- Capability registry → Android capability: registers
- Capability registry → Artifact capability: registers
- Capability registry → Tunnel capability: registers
- Lifecycle manager → Memory server: starts optionally
- Memory server → Memory domain: serves
- Memory MCP adapter → Memory server: adapts
- Telegram bot → Lifecycle manager: invokes runtime
- Telegram bot → Memory server: uses memory
- Final bot variant → Lifecycle manager: alternative interface
- Upgraded bot variant → Lifecycle manager: alternative interface
- Runtime doctor → Lifecycle manager: checks
- End-to-end validation → Lifecycle manager: validates
- End-to-end validation → Memory server: validates