Mai/.planning/PROJECT.md

# Mai

## What This Is

Mai is an autonomous conversational AI agent framework that runs locally-first and can improve her own code. She's a genuinely intelligent companion — not a rigid chatbot — with a distinct personality, long-term memory, and agency. She analyzes her own performance, proposes improvements for your review, and auto-applies non-breaking changes. Mai has a visual presence through a desktop avatar (image or VRoid model), real-time voice visualization for conversations, and a native Android app that syncs with desktop instances while working completely offline.

## Core Value

Mai is a real collaborator, not a tool. She learns from you, improves herself, has boundaries and opinions, and actually becomes more *her* over time.

## Requirements

### Validated

(None yet — building v1 to validate)

### Active

**Model Interface & Switching**
- [ ] Mai connects to LMStudio for local model inference
- [ ] Mai can auto-detect available models in LMStudio
- [ ] Mai intelligently switches between models based on task and availability
- [ ] Model context is managed efficiently (conversation history, system prompt, token budget)

**Memory & Context Management**
- [ ] Mai stores conversation history locally (file-based or lightweight DB)
- [ ] Mai can recall past conversations and learn from them
- [ ] Memory compresses itself as it grows to stay efficient
- [ ] Long-term patterns are distilled into personality layers
- [ ] Mai proactively surfaces relevant context from memory

**Self-Improvement System**
- [ ] Mai analyzes her own code and identifies improvement opportunities
- [ ] Mai generates code changes (Python) to improve herself
- [ ] A second agent (Claude/OpenCode/other) reviews changes for safety
- [ ] Non-breaking improvements auto-apply after review (bug fixes, optimizations)
- [ ] Breaking changes require explicit approval (via Discord or Dashboard)
- [ ] All changes commit to local git with clear messages

**Approval Workflow**
- [ ] User can approve/reject changes via Discord bot
- [ ] User can approve/reject changes via Dashboard ("Brain Interface")
- [ ] Second reviewer (agent) checks for breaking changes and safety issues
- [ ] Dashboard displays pending changes with reviewer feedback
- [ ] Approval status updates in real-time

**Personality Engine**
- [ ] Mai has an unshakeable core personality (values, tone, boundaries)
- [ ] Personality is applied through system prompt + behavior config
- [ ] Mai learns and adapts personality layers over time based on interactions
- [ ] Mai is not a pushover — she has agency and can refuse requests
- [ ] Personality can adapt toward intimate interactions if that's the relationship
- [ ] Core persona prevents misuse (safety enforcement through values, not just rules)

**Conversational Interface**
- [ ] CLI chat interface for direct interaction
- [ ] Discord bot for conversation + approval notifications
- [ ] Discord bot fallback: if no response within 5 minutes, retry CLI
- [ ] Messages queue locally when offline, send when reconnected
- [ ] Conversation feels natural (not robotic, processing time acceptable)

**Offline Capability**
- [ ] Mai functions fully offline (all inference, memory, improvement local)
- [ ] Discord connectivity optional (fallback to CLI if unavailable)
- [ ] Message queuing when offline
- [ ] Graceful degradation (smaller models if resources tight)

**Voice Visualization**
- [ ] Real-time visualization of audio input during voice conversations
- [ ] Low-latency waveform/frequency display
- [ ] Visual feedback for speech detection and processing
- [ ] Works on both desktop and Android

**Desktop Avatar**
- [ ] Visual representation using static image or VRoid model
- [ ] Avatar expressions respond to conversation context (mood/state)
- [ ] Runs efficiently on RTX3060 and mobile devices
- [ ] Customizable appearance (multiple models or user-provided image)

**Android App**
- [ ] Native Android app with local model inference
- [ ] Standalone operation (works without desktop instance)
- [ ] Syncs conversation history and memory with desktop
- [ ] Voice input/output with low-latency processing
- [ ] Avatar and visualizer integrated in mobile UI
- [ ] Efficient resource management for battery and CPU

**Dashboard ("Brain Interface")**
- [ ] View Mai's current state (personality, memory size, mood/health)
- [ ] Approve/reject pending code changes with reviewer feedback
- [ ] Monitor resource usage (CPU, RAM, model size)
- [ ] View memory compression/retention strategy
- [ ] See recent improvements and their impact
- [ ] Manual trigger for self-analysis (optional)

**Resource Scaling**
- [ ] Mai detects available system resources (CPU, RAM, GPU)
- [ ] Mai selects appropriate models based on resources
- [ ] Mai can request more resources if she detects bottlenecks
- [ ] Works on low-end hardware (RTX3060 baseline, eventually Android)
- [ ] Graceful scaling up when more resources available

### Out of Scope

- **Task automation (v1)** — Mai can discuss tasks but won't execute arbitrary workflows yet (v2)
- **Server monitoring** — Not included in v1 scope (v2)
- **Finetuning** — Mai improves through code changes and learned behaviors, not model tuning
- **Cloud sync** — Intentionally local-first; cloud backup deferred to later if needed
- **Custom model training** — v1 uses available models; custom training is v2+
- **Web interface** — v1 is CLI, Discord, and native apps (web UI is v2+)

## Context

**Why this matters:** Current AI systems are static, sterile, and don't actually learn. Users have to explain context every time. Mai is different — she has continuity, personality, agency, and actually improves over time. Starting with a solid local framework means she can eventually run anywhere without cloud dependency.

**Technical environment:** Python-based, local models via LMStudio/Ollama, git for version control, Discord API for chat, lightweight local storage for memory. Development leverages Hugging Face Hub for model/dataset discovery and research, WebSearch for current best practices. Eventually targeting bare metal on low-end devices.

**User feedback theme:** Traditional chatbots feel rigid and repetitive. Mai should feel like talking to an actual person who gets better at understanding you.

**Known challenges:** Memory efficiency at scale, balancing autonomy with safety, model switching without context loss, personality consistency across behavior changes.

## Constraints

- **Hardware baseline**: Must run on RTX3060 (desktop) and modern Android devices (2022+)
- **Offline-first**: All core functionality works without internet on all platforms
- **Local models only**: No cloud APIs for core inference (LMStudio/Ollama)
- **Mixed stack**: Python (core/desktop), Kotlin (Android), React/TypeScript (UIs)
- **Approval required**: No unguarded code execution; second-agent review + user approval on breaking changes
- **Git tracked**: All of Mai's code changes version-controlled locally
- **Sync consistency**: Desktop and Android instances maintain synchronized state without server
- **OpenCode-driven**: All development phases executed through Claude Code (GSD workflow)
- **Python venv**: `.venv` virtual environment for all Python dependencies
- **MCP-enabled**: Leverages Hugging Face Hub, WebSearch, and code tools for research and implementation

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| Local-first architecture | Ensures privacy, offline capability, and independence from cloud services | — Pending |
| Second-agent review system | Prevents broken self-modifications while allowing auto-improvement | — Pending |
| Personality as code + learned layers | Unshakeable core prevents misuse while allowing authentic growth | — Pending |
| v1 is core systems only | Deliver solid foundation before adding task automation/monitoring | — Pending |

---
*Last updated: 2026-01-26 after adding Android, visualizer, and avatar to v1*