Megan can help with your game loadout or quest, 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 with smart screen change detection.
• 🎯Game help – Screenshot-based loadout/build and quest/mission assistance.
• 🔎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.
• 👤Face tracking – Camera-based head tracking follows faces smoothly at 100Hz.
• 🎤Speaker tracking – ReSpeaker DOA turns body toward active speaker.
• 📸Camera vision – "What is this?" identifies objects via built-in camera + GPT-4o.
• 👋Visual greeting – Proactively greets people who approach while idle.

Megan is an ongoing project. Expect many more updates.

• 🎭Interactive games – Trivia, 20 questions, Simon Says.
• 👤Face recognition – Identify specific people by face, not just "a face."
• 📅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)
        └── podcasts/            # Saved podcast scripts

🎨 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.