MAY — Personal AI Assistant 🤖

Built my own Friday. MAY is a fully functional personal AI assistant inspired by Friday from Iron Man — powered by Claude Sonnet, deployed on mobile, and always one step ahead.

---

✨ What MAY Can Do

• 🧠 Claude Sonnet 4.5 — razor-sharp AI reasoning
• 🔍 Real-time web search — Claude's native search, no extra APIs
• 📅 Google Calendar — read, create, and delete events
• 📧 Gmail — read, filter, and summarize emails
• ✅ Google Tasks — list, create, and complete tasks
• 💾 Persistent memory — Supabase + pgvector semantic search across sessions
• 📱 React Native mobile app — Chat, Dashboard, and Memory screens
• 🔊 Voice responses — TTS speaks MAY's replies aloud
• ☁️ Deployed on Render — works anywhere, not just on WiFi

---

🏗️ Architecture

React Native App  ──HTTP──▶  FastAPI (Render)  ──▶  MAYOrchestrator
                                  ├── POST /chat          (Claude + memory)
                                  ├── GET  /calendar/today (Google Calendar)
                                  ├── GET  /memories       (Supabase)
                                  └── GET  /health

---

🗂️ Project Structure

MAY/
├── serve.py                  # FastAPI server entry point
├── main.py                   # CLI entry point
├── pyproject.toml
│
├── may/
│   ├── config.py             # Centralised env/config loading
│   ├── orchestrator.py       # Claude agent + skill orchestration
│   │
│   ├── api/
│   │   └── server.py         # FastAPI REST endpoints
│   │
│   ├── memory/
│   │   └── supabase_memory.py   # Long-term memory (Supabase + pgvector)
│   │
│   ├── notifications/
│   │   └── scheduler.py      # Proactive notifications (APScheduler)
│   │
│   └── skills/
│       ├── productivity/     # Google Calendar
│       ├── gmail/            # Gmail integration
│       └── tasks/            # Google Tasks
│
├── mobile/                   # React Native app (Expo)
│   ├── src/
│   │   ├── screens/          # Chat, Dashboard, Memory
│   │   ├── components/       # MessageBubble, MicButton, EventCard...
│   │   └── api/              # mayClient.js
│   └── App.js
│
└── credentials/              # Google OAuth tokens (git-ignored)

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 20 LTS
• Supabase project with pgvector enabled
• Anthropic API key
• Google Cloud project with Calendar, Gmail, Tasks APIs enabled

Backend Setup

# Clone and install
git clone https://github.com/RYTH-07/MAY.git
cd MAY
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

# Configure environment
copy .env.example .env
# Fill in your API keys in .env

# Run Supabase migration (in Supabase SQL Editor)
# See may/memory/supabase_memory.py for the SQL

# Start backend
python serve.py

Mobile Setup

cd mobile
npm install --legacy-peer-deps

# Update src/api/mayClient.js with your backend URL
# Then start Expo
npx expo start

---

⚙️ Environment Variables

ANTHROPIC_API_KEY=           # Anthropic API key
SUPABASE_URL=                # Supabase project URL
SUPABASE_SERVICE_ROLE_KEY=   # Supabase service role key
GOOGLE_CREDENTIALS_PATH=     # Path to google_credentials.json
GOOGLE_TOKEN_PATH=           # Path to google_token.json
GOOGLE_TOKEN_JSON=           # Token JSON string (for Render deployment)
GOOGLE_CREDENTIALS_JSON=     # Credentials JSON string (for Render deployment)
VOYAGE_API_KEY=              # Voyage AI key for embeddings

---

🗃️ Memory Architecture

Layer	Storage	Purpose
Short-term	Python list	Current conversation context
Long-term	Supabase + pgvector	Semantic memories across sessions

---

🔌 Adding New Skills

1. Create may/skills/<skill_name>/handler.py
2. Define a TOOLS list with Anthropic tool definitions
3. Implement the tool functions
4. Skills are auto-discovered at startup

---

🗺️ Roadmap

• Voice mode (ElevenLabs STT + TTS dev build)
• WhatsApp integration (Twilio)
• Proactive morning briefing
• Event reminders
• Notion integration

---

📜 License

MIT