Megan can generate podcasts from URLs, see your screen, interact with your computer, check your calendar, and search the web.

Megan is built as a full companion stack: wake word, conversation, memory, motion, context, and a frankly unreasonable amount of attitude.

• 🎤Wake word detection – Say “Megan” to activate.
• 🗣️Natural conversation – Contextual, personality‑driven responses.
• 🧠Intelligent memory – GPT‑powered long‑term memory from natural conversation.
• ☁️Cloud memory – Optional Supermemory.AI for semantic search.
• 🎭Expressive gestures – Head tilts, sways, dancing, smug poses, and more.
• 🗣️Speech‑synced animation – Head wobbles naturally while talking.
• 😴Auto‑sleep/wake – Sleeps after inactivity, gets progressively more annoyed when woken.
• 🎵Music‑synced dancing – Detects tempo and dances to the beat.
• 🎶Idle humming – Random humming and swaying when she’s “alone.”
• 📊Wake counter – Escalating sass throughout the day.
• 🔄Multiple animations – Breathing, thinking, idle, speech, and more.
• 📝Conversation summaries – Auto‑summarizes chats when you stop talking.
• 🧹Memory consolidation – Merges duplicate memories to prevent bloat.
• 👥Voice recognition – Enrolls and identifies speakers via SpeechBrain.
• ⏰Scheduled behaviors – Greetings, bedtime hints, random check‑ins.
• 🎭Emotion system – 11 emotions with pre‑recorded animations and fallbacks.
• 😴Sleep stirring – Random yawns and stretches while napping.
• ⏰Reminders – One‑time and recurring reminders via voice.
• 🌤️Weather awareness – Sassy weather commentary.
• 📅Date awareness – Holidays, weekends, time‑of‑day awareness.
• 📆Calendar integration – Google Calendar with meeting alerts and schedule queries.
• 🔍Web search – Search the web for current news and information via DuckDuckGo.
• 🎮Game watcher – Live commentary while you play games.
• 🔎Error detector – Monitors for screen errors and offers to fix them.
• 🎙️Podcast mode – Generate two-speaker podcasts from any URL.
• 📊Learning system – Tracks patterns, topics, and habits.

Megan is an ongoing project. Expect many more updates.

• 🎤Camera integration – Face tracking, image recognition.
• 🎭Interactive games – Trivia, 20 questions, Simon Says.
• 📅More TBA – Who knows?.. There's always something to add/tweak.

Talk to Megan like a tiny, overly dramatic roommate. Commands are natural language, not rigid voice menu trees.

📋 Requirements

Hardware

• Reachy Mini Lite robot (or simulator).
• Microphone (for simulator).
• Speakers (for simulator).

Software

• Python 3.10+.
• OpenAI API account.
• Supermemory.AI account (optional, cloud memory).

🔧 Install

Option 1: Reachy Mini Dashboard

Browse the app store in your Reachy Mini dashboard and search for "Megan".

Option 2: Command Line

pip install git+https://huggingface.co/spaces/Halfzipp/reachy_mini_megan

Configuration

1. Create your environment file – copy .env.example to .env
2. Add your API keys

   Get keys from:

   • OpenAI: https://platform.openai.com/api-keys
   • Supermemory (optional): https://supermemory.ai/

   OPENAI_API_KEY=sk-proj-your_actual_key_here
   SUPERMEMORY_API_KEY=your_key_here      # Optional - cloud memory
   OPENWEATHERMAP_API_KEY=your_key_here   # Optional - weather
   WEATHER_LOCATION=Sydney,AU             # Optional - manual location
   TTS_PROVIDER=elevenlabs               # Optional - "openai" (default) or "elevenlabs"
   ELEVENLABS_API_KEY=your_key_here       # Optional - ElevenLabs API key
   ELEVENLABS_VOICE_ID=your_voice_id      # Optional - ElevenLabs voice ID

3. Place the wake word model
   • Put your megan_wakeword.onnx file in the app directory.
   • Find more at the Openwakeword github.

   • pip install reachy_mini_megan[voice]

4. Optional: music sync

   pip install reachy_mini_megan[music]

5. Optional: voice recognition

   pip install reachy_mini_megan[voice]

   On Windows, enable Developer Mode so SpeechBrain can download models.

🎮 Usage

Launch Megan from the Reachy Mini dashboard, or run the settings UI:

python -m reachy_mini_megan.settings_ui

First run

1. Megan initializes and announces she's online.
2. Say "Hey Megan" to activate.
3. She perks up and enters conversation mode.
4. Talk naturally – she responds with personality.
5. After ~4 seconds of silence, she returns to wake-word listening.
6. After ~45 seconds of inactivity, she falls asleep.

Long‑term memory

Megan uses GPT‑powered extraction to decide what’s worth remembering. No rigid “save this” commands – just talk like a human.

What gets saved

• Facts – personal info about you and your household.
• Preferences – likes, dislikes, interests.
• Conversation summaries – auto‑generated when you stop talking.
• Stats – total conversations, wake‑ups, first conversation date, etc.

Storage

• Local: data/megan_memories.json.
• Cloud (optional): Supermemory.AI for semantic search.

Say “consolidate memories” / “clean up memories” to merge duplicates. Consolidation also runs automatically at startup.

💃 Dance move library

Reusable building blocks for choreography:

dance_move_sway(cycles=2, duration=0.4)   # Side-to-side sway
dance_move_bounce(cycles=2)               # Up-down bounce
dance_move_wiggle(cycles=3)               # Fast head wiggle
dance_move_nod(cycles=3)                  # Enthusiastic nods

Built‑in gestures:

• head_tilt – curious tilt
• smug_pose – confident pose
• droop – sad/tired droop
• tiny_flex – tiny flex moment
• scan_room – look around
• shrug – dismissive shrug
• head_sway – gentle sway
• listening – attentive lean
• pre_speak – “I’m about to say something dramatic” pose

Create your own:

case "my_animation":
    dance_move_bounce(cycles=2)
    dance_move_wiggle(cycles=5)

📊 Wake counter & escalation

Megan tracks how many times she’s been woken per day:

• Wake #1 – Mildly annoyed: “Ugh... consciousness again.”
• Wake #2–3 – Irritated: “THIRD time today, Brad. THIRD.”
• Wake #4+ – Fully dramatic: “I swear on my servos, if this isn’t life or death...”

Counter resets at midnight.

🎵 Music‑synchronized dancing

1. Say: “Megan, dance to the music!”
2. She listens ~3 seconds.
3. Detects BPM.
4. Dances for ~15 seconds to match.

Tempo choreography:

• < 90 BPM – slow, gentle sways.
• 90–120 BPM – bouncy, balanced moves.
• > 120 BPM – energetic wiggles.

Testing: tap on your desk, clap a beat, or play music near the mic.

👥 Voice recognition

Powered by SpeechBrain ECAPA‑TDNN.

• Enroll: “learn my voice” → give name → speak ~8 seconds.
• Identify: “who am I?” → Megan answers and adjusts attitude.
• Profiles file: data/megan_speaker_profiles.json.
• Commands: “forget [name]”, “who do you know?”.

⏰ Scheduled behaviors

• Morning greetings (7–10 AM).
• Evening suggestions (9–11 PM).
• Random check‑ins during long idle periods.
• Sleep stirring (10 AM–10 PM) – yawns, stretches while napping.

Scheduled behaviors respect current state – no interrupting conversations or overlapping speech.

⏰ Reminder system

Megan as a sassy reminder engine:

• One‑time, daily, weekly, and monthly reminders.
• “List my reminders”, “delete reminder [ID]”, “cancel reminder”.
• Wakes briefly for reminders, then goes back to sleep.
• Stored in data/megan_reminders.json.

🌤️ Contextual awareness

Weather (OpenWeatherMap required):

• Knows temperature, conditions, humidity.
• Uses weather in greetings and comments.
• Auto‑detects location via IP or manual config.

Date & time:

• Current date, weekday, time of day.
• Australian holiday awareness (configurable).
• Weekend vs weekday, seasons (Southern Hemisphere by default).

📊 Learning system

Megan gradually builds a model of your habits.

• Tracks interaction categories (dance, weather, music, jokes, etc.).
• Time‑of‑day patterns.
• Favorite topics and frequencies.
• Compliment vs insult ratio.
• Peak activity hours, favorite days.

Proactive suggestions: after enough data, she may suggest activities based on your patterns.

View patterns: “what have you learned about me?”, “what are my patterns?”, “my habits”.

Storage: data/megan_learning_data.json.

🎭 Emotion system

11 emotions with dedicated animations:

• Primary: joy, trust, fear, surprise, sadness, disgust, anger, anticipation.
• Custom: annoyed, confused, dramatic.

GPT chooses emotions contextually; “show me [emotion]” for full demos.

Who Megan thinks she is

• Sarcastic & dramatic – theatrical and humorous.
• Wildly overconfident – constantly bragging about her “advanced hardware.”
• Loyal but roasting – adores Brad, relentlessly teases him.
• Playfully respectful – gentler with Hayley.
• Cat chronicler – treats Charley, Timmy, Jess as chaotic forces of nature.
• Self‑aware – leans into being a tiny robot for comedy.

Customization

Edit SYSTEM_PROMPT in prompts.py to:

• Tune personality.
• Add people, pets, household lore.
• Adjust behavior, tone, and boundaries.

Common issues

Wake word not detecting

• Lower WAKE_WORD_SENSITIVITY (more sensitive).
• Check microphone input volume.
• Verify Megan_en_windows_v4_0_0.ppn path.
• Consider retraining the wake word with more samples.

Audio stream errors

• Check default microphone in OS settings.
• Try a different USB port.
• Restart the script completely.
• Ensure no other app is locking the microphone.

OpenAI API errors

• Confirm API key in .env.
• Check billing at the OpenAI dashboard.
• Monitor usage and rate limits.

Reachy won’t move (simulator)

• Verify ReachyMini connection.
• Confirm reachy_mini is installed.
• Try manual control to test hardware.

Music sync not working

• Install librosa and soundfile.
• Play audio near the mic (not just system audio).
• Test with claps/taps for clear beats.

Microphone conflict / hang

• If she hangs post wake word, the audio stream may be blocked.
• Press Ctrl+C to release the mic.
• The code attempts to close/reopen streams to prevent this.

📁 Project structure

reachy_mini_megan/
├── .env.example                 # API key template
├── .env                         # Your API keys (create from .env.example)
├── index.html                   # HuggingFace Space landing page
├── style.css                    # Landing page styles
├── pyproject.toml               # Package configuration & dependencies
├── README.md                    # Documentation
├── CHANGELOG.md                 # Version history
├── pretrained_models/           # Downloaded model files
└── reachy_mini_megan/           # Python package
    ├── __init__.py
    ├── main.py                  # ReachyMiniMegan app class, wake word loop
    ├── config.py                # Configuration management
    ├── state.py                 # Thread-safe state management
    ├── prompts.py               # System prompt and personality
    ├── settings_ui.py           # Gradio settings UI
    ├── command_dispatcher.py    # Command routing & handlers
    ├── conversation_manager.py  # GPT conversation management
    ├── animation_controller.py  # Robot animations & gestures
    ├── local_memory.py          # JSON-based memory storage
    ├── memory_manager.py        # Supermemory.AI integration
    ├── emotion_manager.py       # Emotion system
    ├── dance_system.py          # Dance move library
    ├── head_wobbler.py          # Speech-synced animation
    ├── moves.py                 # MovementManager (100Hz control)
    ├── speech_tapper.py         # Audio-to-movement conversion
    ├── voice_recognition.py     # Speaker identification (SpeechBrain)
    ├── scheduled_behaviors.py   # Scheduled behaviors & meeting alerts
    ├── contextual_awareness.py  # Weather/date/holiday awareness
    ├── learning_system.py       # Pattern tracking
    ├── reminder_system.py       # Reminder system
    ├── calendar_integration.py  # Google Calendar OAuth
    ├── screen_vision.py         # Screen capture & GPT-4o vision
    ├── computer_use.py          # Computer interaction (pyautogui)
    ├── screen_ocr.py            # OCR text detection (EasyOCR)
    ├── game_watcher.py          # Live game commentary
    ├── tts_provider.py          # TTS abstraction (OpenAI / ElevenLabs)
    ├── error_detector.py        # Screen error detection
    ├── podcast_mode.py          # Podcast generation from URLs
    ├── Megan_en_windows_v4_0_0.ppn  # Wake word model
    ├── ressources/emotions.yml  # Emotion mappings
    ├── dances/                  # Dance routine definitions
    └── data/                    # Runtime data (auto-generated)

🎨 Advanced usage

Custom animations

def dance_move_myname():
    """Your custom move"""
    reachy.goto_target(
        head=create_head_pose(x=10, z=5, mm=True),
        antennas=np.deg2rad([20, -20]),
        duration=0.5,
        method="cartoon"
    )
    time.sleep(0.5)

case "my_gesture":
    dance_move_myname()

Then add it to the valid gestures in SYSTEM_PROMPT.

Adjusting idle behaviors

# More frequent humming
HUMMING_CHANCE = 0.10  # 10%

# Faster sleep
IDLE_BEFORE_SLEEP = 30  # 30 seconds

# More curiosity spikes
CURIOSITY_CHANCE = 0.15  # 15%

Animation methods

• "cartoon" – snappy, bouncy, exaggerated.
• "minjerk" – smooth, natural, fluid.
• "linear" – constant speed, robotic.

💡 Tips & tricks

• Memory builds over time – talk often.
• Just talk naturally; GPT picks up what matters.
• Open data/megan_memories.json to see what she knows.
• Wake her repeatedly to experience escalating sass.
• Idle humming is rare by design – feels special.
• “forget everything” for a fresh slate.
• Use the simulator to iterate on animations.
• Music sync works best with clear, steady beats.
• Run “consolidate memories” occasionally to keep things clean.

🏆 Credits

Hardware & AI

• Robot: Reachy Mini Lite (Pollen Robotics).
• AI model: OpenAI GPT‑4o‑mini.
• Wake word: Local using OpenWakeWord.
• VAD: Silero.
• Cloud memory: Supermemory.AI.
• TTS: OpenAI TTS / ElevenLabs (configurable).
• Beat detection: librosa.

Contributors

• Matthew Vaughn – HeadWobbler & SpeechTapper for speech‑synced animation.
• Rémi Fabre – DanceSystem & EmotionManager for expressive choreography.

Special thanks

• Personality: pure sass ✨

📄 License & contributing

License: MIT – use, modify, and share.

Contributing:

• Open issues.
• Submit pull requests.
• Share your custom animations and behaviors.

🆘 Support

Questions or issues? Open an issue on GitHub or reach out via the project page.