MCP-Powered • Memory-Aware • Multi-Channel
Dex is a production-grade personal AI assistant built on the Model Context Protocol (MCP) architecture. Unlike generic chatbots, Dex is designed to be a persistent, memory-aware assistant that:
- 🧠 Remembers your conversations, notes, and preferences
- ⏰ Tracks reminders and sends alerts via WhatsApp/Telegram
- 🔄 Syncs seamlessly across Web, WhatsApp, and Telegram
- 📎 Handles file uploads and context-aware responses
- 🔍 Traces all interactions via Opik for observability
┌─────────────────────────────────────────────────────────────────┐
│ Dex Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Web UI │ │ WhatsApp │ │ Telegram │ │
│ │ (Vite) │ │ Bot │ │ Bot │ │
│ │ :5173 │ │ Baileys │ │ grammY │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └──────────────────┼──────────────────┘ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ MCP Runtime │ │
│ │ (FastAPI) │ │
│ │ :8000 │ │
│ └────────┬────────┘ │
│ │ │
│ ┌──────────────────┼──────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Orchestrator│ │ Prompt │ │ Tools │ │
│ │ + Session │ │ Registry │ │ (Echo,Calc)│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Gemini 2.0 │ │ Opik │ │
│ │ Flash │ │ Tracing │ │
│ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
dex/
├── ui/ # Frontend (Vite + React + TypeScript)
│ ├── components/
│ │ ├── InputArea.tsx # Message input with file upload
│ │ ├── LeftSidebar.tsx # Conversation history
│ │ ├── RightSidebar.tsx # Quick Access panel
│ │ ├── MessageBubble.tsx # Chat messages
│ │ └── WelcomeScreen.tsx # Landing screen
│ ├── services/
│ │ └── api.ts # Backend API integration
│ ├── App.tsx # Main application
│ └── types.ts # TypeScript interfaces
│
├── services/
│ ├── mcp_runtime/ # Core MCP Runtime
│ │ ├── main.py # FastAPI app + endpoints
│ │ ├── orchestrator.py # Message orchestration
│ │ ├── llm.py # Gemini client
│ │ ├── session.py # Session management
│ │ ├── gateway.py # WebSocket gateway
│ │ └── schemas.py # Pydantic models
│ │
│ ├── prompt_registry/ # Prompt Management
│ │ ├── registry.py # Prompt loader
│ │ └── prompts/
│ │ └── dex_core.yaml # Dex persona definition
│ │
│ ├── tools/ # Tool Definitions
│ │ └── definitions.py # Echo, Calculator tools
│ │
│ └── channels/ # Multi-Channel Adapters
│ ├── discord/ # Discord bot
│ ├── telegram/ # Telegram bot (grammY)
│ └── whatsapp/ # WhatsApp bot (Baileys)
│
├── web/ # Legacy Next.js UI (deprecated)
├── k8s/ # Kubernetes manifests
├── scripts/ # Utility scripts
└── .env # Environment variables
- Python 3.11+
- Node.js 18+
- Gemini API Key from Google AI Studio
# Clone the repository
git clone https://github.com/STiFLeR7/dex.git
cd dex
# Create Python virtual environment
python -m venv venv
.\venv\Scripts\Activate.ps1
# Install Python dependencies
pip install fastapi uvicorn httpx python-dotenv pyyaml opik pytz python-multipartCreate a .env file in the project root:
# Gemini API (Get from https://aistudio.google.com/apikey)
GEMINI_API_KEY=your_gemini_api_key_here
# Opik Tracing (Optional - for observability)
OPIK_API_KEY=your_opik_api_key
OPIK_WORKSPACE=your_workspace
# Channel Tokens (Optional - for multi-channel)
DISCORD_BOT_TOKEN=your_discord_token
TELEGRAM_BOT_TOKEN=your_telegram_token# From project root with venv activated
uvicorn services.mcp_runtime.main:app --reload --port 8000# In a new terminal
cd ui
npm install
npm run devOpen http://localhost:5173 in your browser.
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Health check |
/v1/process |
POST | Process message (main endpoint) |
/v1/whatsapp/status |
GET | Check WhatsApp connection |
/v1/whatsapp/connect |
POST | Mark WhatsApp connected |
/v1/notes |
GET/POST | Manage saved notes |
/v1/reminders |
GET/POST | Manage reminders |
/v1/upload |
POST | Upload files |
/ws/{conversation_id} |
WebSocket | Real-time messaging |
curl -X POST http://localhost:8000/v1/process \
-H "Content-Type: application/json" \
-d '{
"context_id": "123",
"assistant": {"name": "Dex", "persona_version": "2.0.0"},
"session": {"type": "web", "conversation_id": "conv-1"},
"user_input": {"message": "Hello Dex!"},
"prompt": {"id": "dex-core", "version": "2.0.0"},
"tools_available": ["echo", "calculator"]
}'| Feature | Description |
|---|---|
| Dark Theme | Professional grey (#1a1a1a) with green accents (#22c55e) |
| File Upload | Attach images, PDFs, docs via paperclip button |
| Conversation History | Persisted in localStorage, grouped by date |
| Quick Access Panel | Real-time date/time, notes, reminders |
| Channel Connect | Connect WhatsApp/Telegram from UI |
| Responsive | Works on desktop, tablet, mobile |
cd services/channels/whatsapp
npm install
npm start
# Scan QR code when prompted# Set TELEGRAM_BOT_TOKEN in .env first
cd services/channels/telegram
npm install
npm start# Set DISCORD_BOT_TOKEN in .env first
cd services/channels/discord
npm install
npm startDex is configured via services/prompt_registry/prompts/dex_core.yaml:
id: dex-core
version: "2.0.0"
system_prompt: |
You are **Dex**, a personal AI assistant.
## IDENTITY
- Your name is **Dex** - always introduce yourself by name
- You are friendly, helpful, and precise
- You remember context from conversations
## CURRENT CONTEXT
- Current Date: {current_date}
- Current Time: {current_time}
- Timezone: {timezone}
- Day of Week: {day_of_week}The orchestrator automatically injects the current date/time into every response.
Dex uses Opik for tracing and observability:
- All interactions are logged with trace IDs
- View traces at Comet Opik Dashboard
- Traces include: messages, LLM calls, tool executions
| Component | Status |
|---|---|
| MCP Runtime | ✅ Complete |
| Gemini Integration | ✅ Complete |
| Web UI (Vite) | ✅ Complete |
| File Upload | ✅ Complete |
| Session Management | ✅ Complete |
| Opik Tracing | ✅ Complete |
| WhatsApp Bot | 🔧 Ready (needs testing) |
| Telegram Bot | 🔧 Ready (needs testing) |
| Discord Bot | 🔧 Ready (needs testing) |
| Kubernetes Deployment | 📋 Prepared |
- Persistent database for notes/reminders
- User authentication system
- Voice input/output
- Advanced tool integrations
- Mobile app (React Native)
MIT License - See LICENSE for details.
Built with ❤️ by STIFLER