# Miku Discord Bot — Commands & Features Reference

> **Last updated:** February 18, 2026
>
> Comprehensive documentation of every Discord command, API endpoint, and feature in the Miku bot.

---

## Table of Contents

- [Discord Commands](#discord-commands)
  - [Voice Commands (`!miku`)](#voice-commands-miku)
  - [UNO Commands (`!uno`)](#uno-commands-uno)
  - [Inline / Special Commands](#inline--special-commands)
- [Conversational Features](#conversational-features)
  - [Addressing Miku](#addressing-miku)
  - [Direct Messages (DMs)](#direct-messages-dms)
  - [Media Analysis](#media-analysis)
  - [Image Generation](#image-generation)
  - [Kindness Reactions](#kindness-reactions)
- [Mood System](#mood-system)
  - [Available Moods](#available-moods)
  - [Evil Mode Moods](#evil-mode-moods)
  - [Mood Auto-Detection](#mood-auto-detection)
- [Personality Modes](#personality-modes)
  - [Evil Mode](#evil-mode)
  - [Bipolar Mode](#bipolar-mode)
  - [Persona Dialogue](#persona-dialogue)
- [Voice Chat System](#voice-chat-system)
  - [Architecture](#voice-architecture)
  - [STT (Speech-to-Text)](#stt-speech-to-text)
  - [TTS (Text-to-Speech)](#tts-text-to-speech)
  - [Resource Locking](#resource-locking)
- [Autonomous Behavior System](#autonomous-behavior-system)
- [Memory System (Cheshire Cat)](#memory-system-cheshire-cat)
- [Profile Picture System](#profile-picture-system)
- [Language Modes](#language-modes)
- [Figurine Notifier](#figurine-notifier)
- [Web UI API Endpoints](#web-ui-api-endpoints)
  - [General Status](#general-status)
  - [Mood Management (DM)](#mood-management-dm)
  - [Mood Management (Per-Server)](#mood-management-per-server)
  - [Language](#language)
  - [Evil Mode API](#evil-mode-api)
  - [Bipolar Mode API](#bipolar-mode-api)
  - [GPU Selection](#gpu-selection)
  - [Autonomous Actions](#autonomous-actions)
  - [Profile Picture & Role Color](#profile-picture--role-color)
  - [Manual Messaging](#manual-messaging)
  - [Server Management](#server-management)
  - [DM Logging & Management](#dm-logging--management)
  - [DM Interaction Analysis](#dm-interaction-analysis)
  - [Image Generation API](#image-generation-api)
  - [Figurine DM Subscriptions](#figurine-dm-subscriptions)
  - [Chat Interface](#chat-interface)
  - [Voice Call Management](#voice-call-management)
  - [Memory (Cheshire Cat) API](#memory-cheshire-cat-api)
  - [Configuration Management](#configuration-management)
  - [Logging Configuration](#logging-configuration)
  - [Message Reactions](#message-reactions)
  - [Autonomous V2 Endpoints](#autonomous-v2-endpoints)
  - [Conversation Management](#conversation-management)

---

## Discord Commands

### Voice Commands (`!miku`)

All voice commands are prefixed with `!miku` and must be used in a **server** (not DMs).

| Command | Arguments | Description | File |
|---------|-----------|-------------|------|
| `!miku join` | `[#channel]` | Join the user's voice channel (or the mentioned channel). Locks GPU resources for voice. | `bot/commands/voice.py` ~L57 |
| `!miku leave` | — | Leave the current voice channel and release all resources. | `bot/commands/voice.py` ~L131 |
| `!miku voice-status` | — | Show current voice session status, resource allocation, and active features. | `bot/commands/voice.py` ~L168 |
| `!miku test` | `[text]` | Test TTS audio playback with custom or default text. | `bot/commands/voice.py` ~L252 |
| `!miku say` | `<message>` | Send a message to the LLM, speak the response in voice chat. | `bot/commands/voice.py` ~L284 |
| `!miku listen` | `[@user]` | Start listening to a user's voice via STT (defaults to command author). | `bot/commands/voice.py` ~L381 |
| `!miku stop-listening` | `[@user]` | Stop listening to a user's voice (defaults to command author). | `bot/commands/voice.py` ~L431 |

**Permissions required:** Bot needs `Connect` and `Speak` permissions in the target voice channel.

---

### UNO Commands (`!uno`)

Miku can play UNO card games as Player 2, controlled via a Playwright browser automation.

| Command | Arguments | Description | File |
|---------|-----------|-------------|------|
| `!uno join` | `<room_code>` | Join an existing UNO game room as Player 2. | `bot/commands/uno.py` ~L25 |
| `!uno list` | — | List all active UNO games Miku is playing. | `bot/commands/uno.py` ~L82 |
| `!uno quit` | `[room_code]` | Quit a specific game (or all games if no code provided). | `bot/commands/uno.py` ~L106 |
| `!uno help` | — | Show UNO command help and how to play. | `bot/commands/uno.py` ~L158 |

**No special permissions required.** Miku uses AI to make strategic moves and trash-talks during games.

---

### Inline / Special Commands

These are handled directly in the `on_message` handler in `bot/bot.py`:

| Command / Trigger | Description | File |
|-------------------|-------------|------|
| `!monday` | Manually trigger the Monday video feature. Server messages only. | `bot/bot.py` ~L708 |
| `miku, rape this nigga balls` | *Must be a reply to another message.* Overlays the replied-to user's name on the `MikuMikuBeam.mp4` video and sends it as a reply. Easter egg command. | `bot/bot.py` ~L196 |

---

## Conversational Features

### Addressing Miku

Miku responds when she detects she is being addressed. The detection logic is in `bot/utils/core.py` (`is_miku_addressed`).

**Miku will respond when:**
- **In DMs:** Always responds to every message.
- **@Mentioned** in a server channel.
- **Replying** to one of Miku's messages.
- **Her name is mentioned** — supports multiple scripts:
  - Latin: `miku`
  - Cyrillic: `мику`
  - Hiragana: `みく`
  - Katakana: `ミク`
  - Kanji: `未来`
  - Plus any combination with Japanese honorifics (`-chan`, `-san`, `-kun`, `-nyan`, `-senpai`, etc.) in all scripts.

### Direct Messages (DMs)

- Any user can DM Miku directly and get a response.
- DMs use the global `DM_MOOD` (auto-rotating) instead of per-server moods.
- All DM conversations are logged for the admin Web UI.
- Users can be **blocked** from DMs via the API.
- The bot logs reactions added/removed in DM conversations.

### Media Analysis

When a user sends media while addressing Miku, she analyzes it with the vision model:

| Media Type | Supported Formats | Description |
|------------|-------------------|-------------|
| **Images** | `.jpg`, `.jpeg`, `.png`, `.webp` | Analyzed by Qwen vision model, then rephrased as Miku |
| **Videos** | `.mp4`, `.webm`, `.mov` | Frames extracted, analyzed by vision model |
| **GIFs** | `.gif` | Converted to MP4, frames extracted, analyzed |
| **Tenor GIFs** | Discord `/gif` embeds | Extracted from Tenor URLs, processed as GIFs |
| **Rich embeds** | Articles, images, videos, links | Text extracted and images/videos analyzed |

All media analysis is blocked during active voice sessions.

### Image Generation

Miku can generate images using ComfyUI when users make natural language requests. Detection is pattern-based in `bot/utils/image_generation.py`.

**Trigger phrases include:**
- "draw me a picture of..."
- "generate an image of..."
- "show me yourself swimming"
- "can you paint..."
- "I want to see you..."
- "what do you look like?"

Image generation is blocked during voice sessions.

### Kindness Reactions

Defined in `bot/utils/kindness.py`. When users say kind things to Miku, she reacts with a heart emoji.

**Keyword triggers:** "thank you", "love you", "luv u", "you're the best", "so cute", "adorable", "amazing", "sweet", "kind", "great job", "well done", "precious", "good girl", "cutie", "angel", "my favorite", "so helpful"

**Heart reactions pool:** 💙 💝 💖 💕 💜 ❤️‍🔥 ☺️

Falls back to LLM-based kindness detection if keywords don't match.

---

## Mood System

### Available Moods

Each mood changes Miku's personality, response style, and nickname emoji. Defined in `bot/moods/` (one `.txt` file per mood) and `bot/globals.py`.

| Mood | Emoji | Description File |
|------|-------|------------------|
| `neutral` | *(none)* | `moods/neutral.txt` |
| `bubbly` | ✨ | `moods/bubbly.txt` |
| `sleepy` | 💤 | `moods/sleepy.txt` |
| `curious` | 🔍 | `moods/curious.txt` |
| `shy` | 🥺 | `moods/shy.txt` |
| `serious` | 😐 | `moods/serious.txt` |
| `excited` | 🎉 | `moods/excited.txt` |
| `silly` | 🤪 | `moods/silly.txt` |
| `melancholy` | 💙 | `moods/melancholy.txt` |
| `flirty` | 💕 | `moods/flirty.txt` |
| `romantic` | 💖 | `moods/romantic.txt` |
| `irritated` | 😤 | `moods/irritated.txt` |
| `angry` | 😠 | `moods/angry.txt` |
| `asleep` | 😴 | `moods/asleep.txt` |

**Mood behavior:**
- **DM moods** rotate automatically on a schedule.
- **Server moods** are per-server and can be set manually via the API or auto-detected from conversation tone.
- Mood affects the system prompt, nickname emoji, and profile picture selection.
- The `asleep` mood can only be reached from `sleepy` (prevents accidental sleep).

### Evil Mode Moods

When Evil Mode is active, a separate mood set is used:

| Evil Mood | Emoji |
|-----------|-------|
| `aggressive` | 👿 |
| `cunning` | 🐍 |
| `sarcastic` | 😈 |
| `evil_neutral` | *(none)* |

### Mood Auto-Detection

After Miku responds in a server, the system analyzes her response to detect if a mood shift occurred naturally. Handled by `detect_mood_shift()` in `bot/utils/moods.py`. If detected, the server mood updates automatically and the bot nickname updates.

---

## Personality Modes

### Evil Mode

**File:** `bot/utils/evil_mode.py`

Evil Mode transforms Miku into "Evil Miku" — an uncensored, darker alter ego. When enabled:
- Uses the `EVIL_TEXT_MODEL` (DarkIdol uncensored model) instead of the standard text model.
- Loads evil-specific prompts from `bot/evil_miku_prompt.txt`, `bot/evil_miku_lore.txt`, `bot/evil_miku_lyrics.txt`.
- Changes the bot's username and profile picture across all servers.
- Changes role color to a dark theme.
- Uses the evil mood set (`aggressive`, `cunning`, `sarcastic`, `evil_neutral`).
- State persists across restarts via `memory/evil_mode_state.json`.

### Bipolar Mode

**File:** `bot/utils/bipolar_mode.py`

When enabled, **both** Regular Miku and Evil Miku coexist. After Miku responds to a message, there's a chance (15%) the opposite persona "breaks through" and starts an argument. Arguments happen via Discord webhooks so both personas appear as different users.

**Features:**
- Minimum 4 exchanges before an argument can end.
- 2-5 second delay between messages for realism.
- Scoreboard tracks wins (`memory/bipolar_scoreboard.json`).
- Webhooks are created per-channel and cached.
- Paused during voice sessions.
- Arguments can be manually triggered via the API.

### Persona Dialogue

**File:** `bot/utils/persona_dialogue.py`

After Miku sends a response in bipolar mode, the system checks if the opposite persona wants to "interject" and start a dialogue. This creates multi-turn conversations between the two Miku personas.

---

## Voice Chat System

### Voice Architecture

The voice system uses a dual-GPU setup:
- **AMD RX 6800 XT:** Text model inference + RVC (voice conversion)
- **GTX 1660:** Soprano TTS (text-to-speech)

### STT (Speech-to-Text)

**File:** `bot/utils/stt_client.py`, `bot/utils/voice_receiver.py`

- Uses a separate STT server container.
- Listens to user audio via Discord voice receive.
- Transcribes speech and sends it to the LLM for a response.
- Can be enabled per-user with `!miku listen`.

### TTS (Text-to-Speech)

**File:** `bot/utils/voice_audio.py`

- Streams LLM output tokens directly to Soprano TTS.
- Audio is played back through the Discord voice connection.
- RVC converts the voice to sound like Miku.

### Resource Locking

When a voice session is active, the following features are **blocked**:
- ❌ Vision model (images/videos can't be analyzed)
- ❌ Image generation (ComfyUI)
- ❌ Bipolar mode arguments
- ❌ Profile picture changes
- ⏸️ Autonomous engine (paused)
- ⏸️ Scheduled events (paused)
- 📦 Other text channel messages (queued for later)

Resources are fully released when the session ends with `!miku leave`.

---

## Autonomous Behavior System

**Files:** `bot/utils/autonomous.py`, `bot/utils/autonomous_engine.py`, `bot/utils/autonomous_v1_legacy.py`

Miku has an AI-driven autonomous system (V2) that decides when and how to interact without being prompted. The system uses context signals and mood profiles to make decisions.

**Autonomous actions:**
| Action | Description |
|--------|-------------|
| `general` | Say something spontaneous in the autonomous channel |
| `engage_user` | Engage a random active user (based on activity, status, etc.) |
| `share_tweet` | Share a Miku-related tweet |
| `join_conversation` | Detect and join an ongoing conversation |
| `change_profile_picture` | Autonomously change the bot's profile picture |
| `reaction` | React to a recent message with an emoji |

**Context signals the engine considers:**
- Messages in the last 5 minutes / last hour
- Unique active users
- Conversation momentum
- Users who recently joined / changed status / started activities
- Time since last action / last interaction
- Hour of day and whether it's a weekend
- Current mood energy level

**Scheduling:** Each server has its own autonomous tick scheduler. Actions are rate-limited (minimum 30s between actions).

---

## Memory System (Cheshire Cat)

**Files:** `bot/utils/cat_client.py`, `cheshire-cat/` directory

Miku uses the Cheshire Cat AI framework for long-term memory:
- **Declarative memory:** Learned facts about users and the world.
- **Episodic memory:** Conversation snippets and experiences.
- Memories are stored in vector databases (Qdrant).
- When enabled, all responses are augmented with relevant memories.
- Falls back to direct LLM queries if Cat is unavailable.
- Memory consolidation can be triggered manually (like a "sleep" process).
- Individual memories can be created, edited, and deleted via the API.

Toggle state: `USE_CHESHIRE_CAT` global (default: `true`).

---

## Profile Picture System

**File:** `bot/utils/profile_picture_manager.py`, `bot/utils/danbooru_client.py`, `bot/utils/pfp_context.py`

- Miku's profile picture can change based on mood.
- Sources images from Danbooru (anime art database).
- Extracts dominant colors for role color matching.
- Face detection ensures the selected image has a face.
- Saves a fallback image for restoration.
- Can be triggered autonomously or manually via the API.
- Custom images can be uploaded.

---

## Language Modes

Miku supports switching between English and Japanese:
- **English mode** (default): Uses the standard `TEXT_MODEL`.
- **Japanese mode**: Uses `JAPANESE_TEXT_MODEL` (Llama 3.1 Swallow) for Japanese responses.
- Persisted across restarts via `config_runtime.yaml`.

---

## Figurine Notifier

**File:** `bot/utils/figurine_notifier.py`

DM-based subscription system for Miku figurine notifications:
- Users can subscribe/unsubscribe to figurine alerts.
- When new Miku figurines are posted (via tweet URLs), subscribers get DMs.
- Individual or bulk DM sending supported.

---

## Web UI API Endpoints

The bot runs a FastAPI server on port `3939` for the Web UI dashboard. All endpoints are defined in `bot/api.py`.

### General Status

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/` | Serve the Web UI dashboard |
| `GET` | `/status` | Bot status, DM mood, server count, per-server moods |
| `GET` | `/logs` | Last 100 lines of `bot.log` |
| `GET` | `/prompt` | Last full prompt sent to the LLM |

### Mood Management (DM)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/mood` | Get current DM mood and description |
| `POST` | `/mood` | Set DM mood (`{ "mood": "bubbly" }`) |
| `POST` | `/mood/reset` | Reset DM mood to `neutral` |
| `POST` | `/mood/calm` | Calm DM mood to `neutral` |
| `GET` | `/moods/available` | List all available mood names |

### Mood Management (Per-Server)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/servers/{guild_id}/mood` | Get current mood for a server |
| `POST` | `/servers/{guild_id}/mood` | Set mood for a server |
| `POST` | `/servers/{guild_id}/mood/reset` | Reset server mood to `neutral` |
| `GET` | `/servers/{guild_id}/mood/state` | Get complete mood state for a server |
| `POST` | `/test/mood/{guild_id}` | Debug endpoint to test mood changes |

### Language

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/language` | Get current language mode and model |
| `POST` | `/language/toggle` | Toggle between English and Japanese |
| `POST` | `/language/set` | Set language (`?language=english` or `japanese`) |

### Evil Mode API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/evil-mode` | Get evil mode status and current mood |
| `POST` | `/evil-mode/enable` | Enable evil mode |
| `POST` | `/evil-mode/disable` | Disable evil mode |
| `POST` | `/evil-mode/toggle` | Toggle evil mode |
| `GET` | `/evil-mode/mood` | Get current evil mood |
| `POST` | `/evil-mode/mood` | Set evil mood (`{ "mood": "aggressive" }`) |

### Bipolar Mode API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/bipolar-mode` | Status, active arguments, webhooks count |
| `POST` | `/bipolar-mode/enable` | Enable bipolar mode |
| `POST` | `/bipolar-mode/disable` | Disable bipolar mode |
| `POST` | `/bipolar-mode/toggle` | Toggle bipolar mode |
| `POST` | `/bipolar-mode/trigger-argument` | Manually trigger an argument in a channel |
| `POST` | `/bipolar-mode/trigger-dialogue` | Force persona dialogue from a message |
| `GET` | `/bipolar-mode/scoreboard` | Miku vs Evil Miku win/loss record |
| `GET` | `/bipolar-mode/arguments` | Get all currently active arguments |
| `POST` | `/bipolar-mode/cleanup-webhooks` | Clean up all bipolar webhooks |

### GPU Selection

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/gpu-status` | Current GPU selection (`nvidia` or `amd`) |
| `POST` | `/gpu-select` | Switch GPU (`{ "gpu": "nvidia" }` or `"amd"`) |

### Autonomous Actions

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/autonomous/general` | Trigger a general autonomous message (all servers or `?guild_id=`) |
| `POST` | `/autonomous/engage` | Trigger user engagement (`?guild_id=`, `?user_id=`, `?engagement_type=`) |
| `POST` | `/autonomous/tweet` | Share a Miku tweet |
| `POST` | `/autonomous/custom` | Send custom prompt as autonomous message (`{ "prompt": "..." }`) |
| `POST` | `/autonomous/reaction` | Trigger an emoji reaction to a recent message |
| `POST` | `/autonomous/join-conversation` | Detect and join an active conversation |
| `GET` | `/autonomous/stats` | V1 autonomous engine stats for all servers |
| `POST` | `/servers/{guild_id}/autonomous/general` | Trigger general message for one server |
| `POST` | `/servers/{guild_id}/autonomous/engage` | Trigger engagement for one server |
| `POST` | `/servers/{guild_id}/autonomous/custom` | Send custom prompt to one server |
| `POST` | `/servers/{guild_id}/autonomous/tweet` | Share tweet in one server |

### Profile Picture & Role Color

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/profile-picture/change` | Change PFP (optional `file` upload, optional `?guild_id=`) |
| `GET` | `/profile-picture/metadata` | Get current PFP metadata (source, tags, etc.) |
| `POST` | `/profile-picture/restore-fallback` | Restore the original saved PFP |
| `POST` | `/role-color/custom` | Set custom role color (form field `hex_color`) |
| `POST` | `/role-color/reset-fallback` | Reset role color to Miku teal (#86cecb) |

### Manual Messaging

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/manual/send` | Send a message to a channel (supports files, replies) |
| `POST` | `/manual/send-webhook` | Send as Miku or Evil Miku via webhook (`persona=miku|evil`) |
| `POST` | `/dm/{user_id}/custom` | Send a custom LLM-generated DM to a user |
| `POST` | `/dm/{user_id}/manual` | Send a manual DM message (supports files, replies) |

### Server Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/servers` | List all configured servers |
| `POST` | `/servers` | Add a new server configuration |
| `PUT` | `/servers/{guild_id}` | Update server configuration |
| `DELETE` | `/servers/{guild_id}` | Remove a server |
| `POST` | `/servers/{guild_id}/bedtime-range` | Update bedtime reminder schedule |
| `GET` | `/servers/{guild_id}/memory` | Get server-specific memory |
| `POST` | `/servers/{guild_id}/memory` | Set server-specific memory |
| `POST` | `/servers/repair` | Repair corrupted server configuration |

### DM Logging & Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/dms/users` | List all users who have DMed the bot |
| `GET` | `/dms/users/{user_id}` | Get conversation summary for a user |
| `GET` | `/dms/users/{user_id}/conversations` | Get recent conversations (`?limit=50`) |
| `GET` | `/dms/users/{user_id}/search` | Search conversations (`?query=...`) |
| `GET` | `/dms/users/{user_id}/export` | Export conversations (`?format=json`) |
| `DELETE` | `/dms/users/{user_id}` | Delete all DM logs for a user |
| `GET` | `/dms/blocked-users` | List all blocked users |
| `POST` | `/dms/users/{user_id}/block` | Block a user from DMs |
| `POST` | `/dms/users/{user_id}/unblock` | Unblock a user |
| `POST` | `/dms/users/{user_id}/conversations/{id}/delete` | Delete a specific message from Discord + logs |
| `POST` | `/dms/users/{user_id}/conversations/delete-all` | Delete all conversations (Discord + logs) |
| `POST` | `/dms/users/{user_id}/delete-completely` | Completely remove all user data |

### DM Interaction Analysis

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/dms/analysis/run` | Manually trigger daily DM analysis |
| `POST` | `/dms/users/{user_id}/analyze` | Analyze a specific user's interactions |
| `GET` | `/dms/analysis/reports` | Get recent analysis reports (`?limit=20`) |
| `GET` | `/dms/analysis/reports/{user_id}` | Get reports for a specific user |

### Image Generation API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/image/generate` | Manually trigger image generation (`{ "prompt": "..." }`) |
| `GET` | `/image/status` | Check ComfyUI availability |
| `POST` | `/image/test-detection` | Test natural language image request detection |
| `GET` | `/image/view/{filename}` | Serve a generated image file |

### Figurine DM Subscriptions

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/figurines/subscribers` | List all figurine notification subscribers |
| `POST` | `/figurines/subscribers` | Add a subscriber (form field `user_id`) |
| `DELETE` | `/figurines/subscribers/{user_id}` | Remove a subscriber |
| `POST` | `/figurines/send_now` | Send figurine DMs to all subscribers |
| `POST` | `/figurines/send_to_user` | Send figurine DM to a specific user |

### Chat Interface

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/chat/stream` | Stream a chat response via SSE (supports text and vision models, conversation history, mood selection) |

### Voice Call Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/voice/call` | Initiate a voice call to a user (starts containers, joins channel, sends DM invite) |
| `GET` | `/voice/debug-mode` | Get voice debug mode status |
| `POST` | `/voice/debug-mode` | Set voice debug mode on/off |

### Memory (Cheshire Cat) API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/memory/status` | Cat connection status, circuit breaker state |
| `POST` | `/memory/toggle` | Enable/disable Cheshire Cat integration |
| `GET` | `/memory/stats` | Memory collection statistics (point counts) |
| `GET` | `/memory/facts` | Get all declarative memory facts |
| `GET` | `/memory/episodic` | Get all episodic memories |
| `POST` | `/memory/consolidate` | Trigger memory consolidation |
| `POST` | `/memory/delete` | **Delete ALL memories** (requires exact confirmation string) |
| `DELETE` | `/memory/point/{collection}/{point_id}` | Delete a single memory point |
| `PUT` | `/memory/point/{collection}/{point_id}` | Edit a memory point's content/metadata |
| `POST` | `/memory/create` | Create a new memory (declarative or episodic) |

### Configuration Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/config` | Full config (static + runtime + state) |
| `GET` | `/config/static` | Static config from `config.yaml` |
| `GET` | `/config/runtime` | Runtime config (overrides) |
| `POST` | `/config/set` | Set a runtime config value |
| `POST` | `/config/reset` | Reset config to defaults |
| `POST` | `/config/validate` | Validate current configuration |
| `GET` | `/config/state` | Get current config state |

### Logging Configuration

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/log/config` | Get current logging configuration |
| `POST` | `/api/log/config` | Update logging config for a component |
| `GET` | `/api/log/components` | List all logging components and stats |
| `POST` | `/api/log/reload` | Reload all loggers from config |
| `POST` | `/api/log/filters` | Update API request log filters |
| `POST` | `/api/log/reset` | Reset logging config to defaults |
| `POST` | `/api/log/global-level` | Set global log level |
| `POST` | `/api/log/timestamp-format` | Set timestamp format |
| `GET` | `/api/log/files/{component}` | Get last N lines from a component's log file |

### Message Reactions

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/messages/react` | Add a reaction emoji to a specific message |

### Autonomous V2 Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/autonomous/v2/stats/{guild_id}` | V2 social stats for a server |
| `GET` | `/autonomous/v2/check/{guild_id}` | Manual V2 context check (debug) |
| `GET` | `/autonomous/v2/status` | V2 system status for all servers |

### Conversation Management

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/conversation/{user_id}` | Get conversation history for a user |
| `POST` | `/conversation/reset` | Reset conversation history (`{ "user_id": "..." }`) |
| `POST` | `/sleep` | Force Miku to sleep (legacy) |
| `POST` | `/wake` | Wake Miku up (legacy) |
| `POST` | `/bedtime` | Send bedtime reminder (`?guild_id=` or all servers) |

---

## Discord Event Handlers

These are non-command behaviors handled by Discord events in `bot/bot.py`:

| Event | Handler | Description |
|-------|---------|-------------|
| `on_ready` | `bot.py` ~L89 | Initialize all systems, restore modes, start schedulers |
| `on_message` | `bot.py` ~L160 | Main message handler — routes commands, handles conversations |
| `on_raw_reaction_add` | `bot.py` ~L716 | Log DM reactions (user and bot) |
| `on_raw_reaction_remove` | `bot.py` ~L756 | Log DM reaction removals |
| `on_presence_update` | `bot.py` ~L793 | Track user presence for autonomous V2 |
| `on_member_join` | `bot.py` ~L799 | Track member joins for autonomous V2 |
| `on_voice_state_update` | `bot.py` ~L803 | Track voice channel joins/leaves, auto-listen for voice calls |

---

## Environment Variables

Key configuration from `bot/globals.py` and `bot/config.py`:

| Variable | Default | Description |
|----------|---------|-------------|
| `DISCORD_BOT_TOKEN` | — | Discord bot token |
| `LLAMA_URL` | `http://llama-swap:8080` | NVIDIA GPU llama-swap URL |
| `LLAMA_AMD_URL` | `http://llama-swap-amd:8080` | AMD GPU llama-swap URL |
| `TEXT_MODEL` | `llama3.1` | Default text model name |
| `VISION_MODEL` | `vision` | Vision model name (Qwen) |
| `EVIL_TEXT_MODEL` | `darkidol` | Uncensored model for evil mode |
| `JAPANESE_TEXT_MODEL` | `swallow` | Japanese text model |
| `OWNER_USER_ID` | `209381657369772032` | Bot owner's Discord ID (for reports) |
| `CHESHIRE_CAT_URL` | `http://cheshire-cat:80` | Cheshire Cat memory server URL |
| `USE_CHESHIRE_CAT` | `true` | Enable/disable memory system |
| `AUTONOMOUS_DEBUG` | `false` | Verbose autonomous decision logging |
| `VOICE_DEBUG_MODE` | `false` | Show voice transcriptions in text channel |