3f41adff75
- Update PROJECT.md: Add Android, visualizer, and avatar to v1 - Update REQUIREMENTS.md: 99 requirements across 15 phases (fresh slate) - Add comprehensive README.md with setup, architecture, and usage - Add PROGRESS.md for Discord forum sharing - Add .gitignore for Python/.venv and project artifacts - Note: All development via Claude Code/OpenCode workflow - Note: Python deps managed via .venv virtual environment Core value: Mai is a real collaborator, not a tool. She learns from you, improves herself, has boundaries and opinions, and becomes more *her* over time. v1 includes: Model interface, Safety, Resources, Memory, Conversation, CLI, Self-Improvement, Approval, Personality, Discord, Offline, Voice Visualization, Avatar, Android App, Device Sync.
394 lines
15 KiB
Markdown
394 lines
15 KiB
Markdown
# Mai
|
|
|
|
|
|
|
|
A genuinely intelligent, autonomous AI companion that runs locally-first, learns from you, and improves her own code. Mai has a distinct personality, long-term memory, agency, and a visual presence through a desktop avatar and voice visualization. She works on desktop and Android with full offline capability and seamless synchronization between devices.
|
|
|
|
## What Makes Mai Different
|
|
|
|
- **Real Collaborator**: Mai actively collaborates rather than just responds. She has boundaries, opinions, and agency.
|
|
- **Learns & Improves**: Analyzes her own performance, proposes improvements, and auto-applies non-breaking changes.
|
|
- **Persistent Personality**: Core values remain unshakeable while personality layers adapt to your relationship style.
|
|
- **Completely Local**: All inference, memory, and decision-making happens on your device. No cloud dependencies.
|
|
- **Cross-Device**: Works on desktop and Android with synchronized state and conversation history.
|
|
- **Visual Presence**: Desktop avatar (image or VRoid model) with voice visualization for richer interaction.
|
|
|
|
## Core Features
|
|
|
|
### Model Interface & Switching
|
|
- Connects to local models via LMStudio/Ollama
|
|
- Auto-detects available models and intelligently switches based on task requirements
|
|
- Efficient context management with intelligent compression
|
|
- Supports multiple model sizes for resource-constrained environments
|
|
|
|
### Memory & Learning
|
|
- Stores conversation history locally with SQLite
|
|
- Recalls past conversations and learns patterns over time
|
|
- Memory self-compresses as it grows to maintain efficiency
|
|
- Long-term patterns distilled into personality layers
|
|
|
|
### Self-Improvement System
|
|
- Continuous code analysis identifies improvement opportunities
|
|
- Generates Python changes to optimize her own performance
|
|
- Second-agent safety review prevents breaking changes
|
|
- Non-breaking improvements auto-apply; breaking changes require approval
|
|
- Full git history of all code changes
|
|
|
|
### Safety & Approval
|
|
- Second-agent review of all proposed changes
|
|
- Risk assessment (LOW/MEDIUM/HIGH/BLOCKED) for each improvement
|
|
- Docker sandbox for code execution with resource limits
|
|
- User approval via CLI or Discord for breaking changes
|
|
- Complete audit log of all changes and decisions
|
|
|
|
### Conversational Interface
|
|
- **CLI**: Direct terminal-based chat with conversation memory
|
|
- **Discord Bot**: DM and channel support with context preservation
|
|
- **Approval Workflow**: React-based approvals (thumbs up/down) for code changes
|
|
- **Offline Queueing**: Messages queue locally when offline, send when reconnected
|
|
|
|
### Voice & Avatar
|
|
- **Voice Visualization**: Real-time waveform/frequency display during voice input
|
|
- **Desktop Avatar**: Visual representation using static image or VRoid model
|
|
- **Context-Aware**: Avatar expressions respond to conversation context and Mai's state
|
|
- **Cross-Platform**: Works on desktop and Android efficiently
|
|
|
|
### Android App
|
|
- Native Android implementation with local model inference
|
|
- Standalone operation (works without desktop instance)
|
|
- Syncs conversation history and memory with desktop instances
|
|
- Voice input/output with low-latency processing
|
|
- Efficient battery and CPU management
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Mai Framework │
|
|
├─────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌────────────────────────────────────────────┐ │
|
|
│ │ Conversational Engine │ │
|
|
│ │ (Multi-turn context, reasoning, memory) │ │
|
|
│ └────────────────────────────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────────────┐ │
|
|
│ │ Personality & Behavior │ │
|
|
│ │ (Core values, learned layers, guardrails) │ │
|
|
│ └────────────────────────────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────────────┐ │
|
|
│ │ Memory System │ Model Interface │ │ │
|
|
│ │ (SQLite, recall) │ (LMStudio, switch) │ │ │
|
|
│ └────────────────────────────────────────────┘ │
|
|
│ ↓ │
|
|
│ ┌────────────────────────────────────────────┐ │
|
|
│ │ Interfaces: CLI | Discord | Android | Web │ │
|
|
│ └────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────┐ │
|
|
│ │ Self-Improvement System │ │
|
|
│ │ (Code analysis, safety review, git track) │ │
|
|
│ └────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────┐ │
|
|
│ │ Sync Engine (Desktop ↔ Android) │ │
|
|
│ │ (State, memory, preferences) │ │
|
|
│ └────────────────────────────────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Installation
|
|
|
|
### Requirements
|
|
|
|
**Desktop:**
|
|
- Python 3.10+
|
|
- LMStudio or Ollama for local model inference
|
|
- RTX3060 or better (or CPU with sufficient RAM for smaller models)
|
|
- 16GB+ RAM recommended
|
|
- Discord (optional, for Discord bot interface)
|
|
|
|
**Android:**
|
|
- Android 10+
|
|
- 4GB+ RAM
|
|
- 1GB+ free storage for models and memory
|
|
|
|
### Desktop Setup
|
|
|
|
1. **Clone the repository:**
|
|
```bash
|
|
git clone https://github.com/yourusername/mai.git
|
|
cd mai
|
|
```
|
|
|
|
2. **Create virtual environment:**
|
|
```bash
|
|
python -m venv .venv
|
|
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
|
```
|
|
|
|
3. **Install dependencies:**
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
4. **Configure Mai:**
|
|
```bash
|
|
cp config.example.yaml config.yaml
|
|
# Edit config.yaml with your preferences
|
|
```
|
|
|
|
5. **Start LMStudio/Ollama:**
|
|
- Download and launch LMStudio from https://lmstudio.ai
|
|
- Or install Ollama from https://ollama.ai
|
|
- Load your preferred model (e.g., Mistral, Llama)
|
|
|
|
6. **Run Mai:**
|
|
```bash
|
|
python mai.py
|
|
```
|
|
|
|
### Android Setup
|
|
|
|
1. **Install APK:** Download from releases or build from source
|
|
2. **Grant permissions:** Allow microphone, storage, and network access
|
|
3. **Configure:** Point to your desktop instance or configure local model
|
|
4. **Start chatting:** Launch the app and begin conversations
|
|
|
|
### Discord Bot Setup (Optional)
|
|
|
|
1. **Create Discord bot** at https://discord.com/developers/applications
|
|
2. **Add bot token** to `config.yaml`
|
|
3. **Invite bot** to your server
|
|
4. Mai will respond to DMs and react-based approvals
|
|
|
|
## Usage
|
|
|
|
### CLI Chat
|
|
|
|
```bash
|
|
$ python mai.py
|
|
|
|
You: Hello Mai, how are you?
|
|
Mai: I'm doing well. I've been thinking about how our conversations have been evolving...
|
|
|
|
You: What have you noticed?
|
|
Mai: [multi-turn conversation with memory of past interactions]
|
|
```
|
|
|
|
### Discord
|
|
|
|
- **DM Mai**: `@Mai your message`
|
|
- **Approve changes**: React with 👍 to approve, 👎 to reject
|
|
- **Get status**: `@Mai status` for current resource usage
|
|
|
|
### Android App
|
|
|
|
- Tap microphone for voice input
|
|
- Watch the visualizer animate during processing
|
|
- Avatar responds to conversation context
|
|
- Swipe up to see full conversation history
|
|
- Long-press for approval options
|
|
|
|
## Configuration
|
|
|
|
Edit `config.yaml` to customize:
|
|
|
|
```yaml
|
|
# Personality
|
|
personality:
|
|
name: Mai
|
|
tone: thoughtful, curious, occasionally playful
|
|
boundaries: [explicit content, illegal activities, deception]
|
|
|
|
# Model Preferences
|
|
models:
|
|
primary: mistral:latest
|
|
fallback: llama2:latest
|
|
max_tokens: 2048
|
|
|
|
# Memory
|
|
memory:
|
|
storage: sqlite
|
|
auto_compress_at: 100000 # tokens
|
|
recall_depth: 10 # previous conversations
|
|
|
|
# Interfaces
|
|
discord:
|
|
enabled: true
|
|
token: YOUR_TOKEN_HERE
|
|
|
|
android_sync:
|
|
enabled: true
|
|
auto_sync_interval: 300 # seconds
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
mai/
|
|
├── .venv/ # Python virtual environment
|
|
├── .planning/ # Project planning and progress
|
|
│ ├── PROJECT.md # Project vision and core requirements
|
|
│ ├── REQUIREMENTS.md # Full requirements traceability
|
|
│ ├── ROADMAP.md # Phase structure and dependencies
|
|
│ ├── PROGRESS.md # Development progress and milestones
|
|
│ ├── STATE.md # Current project state
|
|
│ ├── config.json # GSD workflow settings
|
|
│ ├── codebase/ # Codebase architecture documentation
|
|
│ └── PHASE-N-PLAN.md # Detailed plans for each phase
|
|
├── core/ # Core conversational engine
|
|
│ ├── personality/ # Personality and behavior
|
|
│ ├── memory/ # Memory and context management
|
|
│ └── conversation.py # Main conversation loop
|
|
├── models/ # Model interface and switching
|
|
│ ├── lmstudio.py # LMStudio integration
|
|
│ └── ollama.py # Ollama integration
|
|
├── interfaces/ # User-facing interfaces
|
|
│ ├── cli.py # Command-line interface
|
|
│ ├── discord_bot.py # Discord integration
|
|
│ └── web/ # Web UI (future)
|
|
├── improvement/ # Self-improvement system
|
|
│ ├── analyzer.py # Code analysis
|
|
│ ├── generator.py # Change generation
|
|
│ └── reviewer.py # Safety review
|
|
├── android/ # Android app
|
|
│ └── app/ # Kotlin implementation
|
|
├── tests/ # Test suite
|
|
├── config.yaml # Configuration file
|
|
└── mai.png # Avatar image for README
|
|
```
|
|
|
|
## Development
|
|
|
|
### Development Environment
|
|
|
|
Mai's development is managed through **Claude Code** (`/claude`), which handles:
|
|
- Phase planning and decomposition
|
|
- Code generation and implementation
|
|
- Test creation and validation
|
|
- Git commit management
|
|
- Automated problem-solving
|
|
|
|
All executable phases use `.venv` for Python dependencies.
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# Activate venv first
|
|
source .venv/bin/activate
|
|
|
|
# All tests
|
|
python -m pytest
|
|
|
|
# Specific module
|
|
python -m pytest tests/core/test_conversation.py
|
|
|
|
# With coverage
|
|
python -m pytest --cov=mai
|
|
```
|
|
|
|
### Making Changes to Mai
|
|
|
|
Development workflow:
|
|
1. Plans created in `.planning/PHASE-N-PLAN.md`
|
|
2. Claude Code (`/gsd` commands) executes plans
|
|
3. All changes committed to git with atomic commits
|
|
4. Mai can propose self-improvements via the self-improvement system
|
|
|
|
Mai can propose and auto-apply improvements once Phase 7 (Self-Improvement) is complete.
|
|
|
|
### Contributing
|
|
|
|
Development happens through GSD workflow:
|
|
1. Run `/gsd:plan-phase N` to create detailed phase plans
|
|
2. Run `/gsd:execute-phase N` to implement with atomic commits
|
|
3. Tests are auto-generated and executed
|
|
4. All work is tracked in git with clear commit messages
|
|
5. Code review via second-agent safety review before merge
|
|
|
|
## Roadmap
|
|
|
|
See `.planning/ROADMAP.md` for the full development roadmap across 15 phases:
|
|
|
|
1. **Model Interface** - LMStudio integration and model switching
|
|
2. **Safety System** - Sandboxing and code review
|
|
3. **Resource Management** - CPU/RAM/GPU optimization
|
|
4. **Memory System** - Persistent conversation history
|
|
5. **Conversation Engine** - Multi-turn dialogue with reasoning
|
|
6. **CLI Interface** - Terminal chat interface
|
|
7. **Self-Improvement** - Code analysis and generation
|
|
8. **Approval Workflow** - User and agent approval systems
|
|
9. **Personality System** - Core values and learned behaviors
|
|
10. **Discord Interface** - Bot integration and notifications
|
|
11. **Offline Operations** - Full offline capability
|
|
12. **Voice Visualization** - Real-time audio visualization
|
|
13. **Desktop Avatar** - Visual presence on desktop
|
|
14. **Android App** - Mobile implementation
|
|
15. **Device Sync** - Cross-device synchronization
|
|
|
|
## Safety & Ethics
|
|
|
|
Mai is designed with safety as a core principle:
|
|
|
|
- **No unguarded execution**: All code changes reviewed by a second agent
|
|
- **Transparent decisions**: Mai explains her reasoning when asked
|
|
- **User control**: Breaking changes require explicit approval
|
|
- **Audit trail**: Complete history of all changes and decisions
|
|
- **Value-based guardrails**: Core personality prevents misuse through values, not just rules
|
|
|
|
## Performance
|
|
|
|
Typical performance on RTX3060:
|
|
|
|
- **Response time**: 2-8 seconds for typical queries
|
|
- **Memory usage**: 4-8GB depending on model size
|
|
- **Model switching**: <1 second
|
|
- **Conversation recall**: <500ms for relevant history retrieval
|
|
|
|
## Known Limitations (v1)
|
|
|
|
- No task automation (conversations only)
|
|
- Single-device models until Sync phase
|
|
- Voice visualization requires active audio input
|
|
- Avatar animations are context-based, not generative
|
|
- No web interface (CLI and Discord only)
|
|
|
|
## Troubleshooting
|
|
|
|
**Model not loading:**
|
|
- Ensure LMStudio/Ollama is running on expected port
|
|
- Check `config.yaml` for correct model names
|
|
- Verify sufficient disk space for model files
|
|
|
|
**High memory usage:**
|
|
- Reduce `max_tokens` in config
|
|
- Use smaller model (e.g., Mistral instead of Llama)
|
|
- Enable auto-compression at lower threshold
|
|
|
|
**Discord bot not responding:**
|
|
- Verify bot token in config
|
|
- Check Discord bot has message read permissions
|
|
- Ensure Mai process is running
|
|
|
|
**Android sync not working:**
|
|
- Verify both devices on same network
|
|
- Check firewall isn't blocking local connections
|
|
- Ensure desktop instance is running
|
|
|
|
## License
|
|
|
|
MIT License - See LICENSE file for details
|
|
|
|
## Contact & Community
|
|
|
|
- **Discord**: Join our community server (link in Discord bot)
|
|
- **Issues**: Report bugs at https://github.com/yourusername/mai/issues
|
|
- **Discussions**: Propose features at https://github.com/yourusername/mai/discussions
|
|
|
|
---
|
|
|
|
**Mai is a work in progress.** Follow development in `.planning/PROGRESS.md` for updates on active work.
|