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.
8.1 KiB
8.1 KiB
Mai Development Progress
Last Updated: 2026-01-26 Status: Fresh Slate - Roadmap Under Construction
Project Description
Mai is an autonomous conversational AI companion that runs locally-first and can improve her own code. She's not a rigid chatbot, but a genuinely intelligent collaborator with a distinct personality, long-term memory, and real agency. Mai learns from your interactions, analyzes her own performance, and proposes improvements for your review before auto-applying them.
Key differentiators:
- Real Collaborator: Mai actively contributes ideas, has boundaries, and can refuse requests
- Learns & Evolves: Conversation patterns inform personality layers; she remembers you
- Completely Local: All inference, memory, and decision-making on your device—no cloud, no tracking
- Visual Presence: Desktop avatar (image or VRoid) with real-time voice visualization
- Cross-Device: Works on desktop and Android with seamless synchronization
- Self-Improving: Analyzes her own code, generates improvements, and gets your approval before applying
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.
Phase Breakdown
Status Summary
- Total Phases: 15
- Completed: 0
- In Progress: 0
- Planned: 15
- Requirements Mapped: 99/99 (100%)
Phase Details
| # | Phase | Goal | Requirements | Status |
|---|---|---|---|---|
| 1 | Model Interface | Connect to local models and intelligently switch | MODELS (7) | 🔄 Planning |
| 2 | Safety System | Sandbox code execution and implement review workflow | SAFETY (8) | 🔄 Planning |
| 3 | Resource Management | Monitor CPU/RAM/GPU and adapt model selection | RESOURCES (6) | 🔄 Planning |
| 4 | Memory System | Persistent conversation storage with vector search | MEMORY (8) | 🔄 Planning |
| 5 | Conversation Engine | Multi-turn dialogue with reasoning and context | CONVERSATION (9) | 🔄 Planning |
| 6 | CLI Interface | Terminal-based chat with history and commands | CLI (8) | 🔄 Planning |
| 7 | Self-Improvement | Code analysis, change generation, and auto-apply | SELFMOD (10) | 🔄 Planning |
| 8 | Approval Workflow | User approval via CLI and Dashboard for changes | APPROVAL (9) | 🔄 Planning |
| 9 | Personality System | Core values, behavior configuration, learned layers | PERSONALITY (8) | 🔄 Planning |
| 10 | Discord Interface | Bot integration with DM and approval reactions | DISCORD (10) | 🔄 Planning |
| 11 | Offline Operations | Full local-only functionality with graceful degradation | OFFLINE (7) | 🔄 Planning |
| 12 | Voice Visualization | Real-time audio waveform and frequency display | VISUAL (5) | 🔄 Planning |
| 13 | Desktop Avatar | Visual presence with image or VRoid model support | AVATAR (6) | 🔄 Planning |
| 14 | Android App | Native mobile app with local inference and UI | ANDROID (10) | 🔄 Planning |
| 15 | Device Sync | Synchronization of state and memory between devices | SYNC (6) | 🔄 Planning |
Current Focus
Phase: Infrastructure & Planning Work: Establishing project structure and execution approach
What's Happening Now
- Codebase mapping complete (7 architectural documents)
- Project vision and core value defined
- Requirements inventory (99 items across 15 phases)
- README with comprehensive setup and features
- Roadmap creation (distributing requirements across phases)
- First phase planning (Model Interface)
Next Steps
- Create detailed ROADMAP.md with phase dependencies
- Plan Phase 1: Model Interface & Switching
- Begin implementation of LMStudio/Ollama integration
- Setup development infrastructure and CI/CD
Recent Milestones
🎯 Project Initialization (2026-01-26)
- Codebase mapping with 7 structured documents (STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, INTEGRATIONS, CONCERNS)
- Deep questioning and context gathering completed
- PROJECT.md created with core value and vision
- REQUIREMENTS.md with 99 fully mapped requirements
- Feature additions: Android app, voice visualizer, desktop avatar included in v1
- README.md with comprehensive setup and architecture documentation
- Progress report framework for regular updates
📋 Planning Foundation
- All v1 requirements categorized into logical phases
- Cross-device synchronization included as core feature
- Safety and self-improvement as phase 2 priority
- Offline capability planned as phase 11 (ensures all features work locally first)
Development Methodology
All phases are executed through Claude Code (/gsd workflow) which provides:
- Automated phase planning with task decomposition
- Code generation with test creation
- Atomic git commits with clear messages
- Multi-agent verification (research, plan checking, execution verification)
- Parallel task execution where applicable
- State tracking and checkpoint recovery
Each phase follows the standard GSD pattern:
/gsd:plan-phase N→ Creates detailed PHASE-N-PLAN.md/gsd:execute-phase N→ Implements with automatic test coverage- Verification and state updates
This ensures consistent quality, full test coverage, and clean git history across all 15 phases.
Technical Highlights
Stack
- Primary: Python 3.10+ (core/desktop) with
.venvvirtual environment - Mobile: Kotlin (Android)
- UI: React/TypeScript (eventual web)
- Model Interface: LMStudio/Ollama
- Storage: SQLite (local)
- IPC/Sync: Local network (no server)
- Development: Claude Code (OpenCode) for all implementation
Key Architecture Decisions
| Decision | Rationale | Status |
|---|---|---|
| Local-first, no cloud | Privacy and independence from external services | ✅ Approved |
| Second-agent review for all changes | Safety without blocking innovation | ✅ Approved |
| Personality as code + learned layers | Unshakeable core + authentic growth | ✅ Approved |
| Offline-first design (phase 11 early) | Ensure full functionality before online features | ✅ Approved |
| Android in v1 | Mobile-first future vision | ✅ Approved |
| Cross-device sync without server | Privacy-preserving multi-device support | ✅ Approved |
Known Challenges & Solutions
| Challenge | Current Approach |
|---|---|
| Memory efficiency at scale | Auto-compressing conversation history with pattern distillation (phase 4) |
| Model switching without context loss | Standardized context format + token budgeting (phase 1) |
| Personality consistency across changes | Personality as code + test suite for behavior (phases 7-9) |
| Safety vs. autonomy balance | Dual review system: agent checks breaking changes, user approves (phase 2/8) |
| Android model inference | Quantized models + resource scaling (phase 14) |
| Cross-device sync without server | P2P sync on local network + conflict resolution (phase 15) |
How to Follow Progress
Discord Forum
Regular updates posted in the #mai-progress forum channel with:
- Weekly milestone summaries
- Blocker alerts if any
- Community feedback requests
Git & Issues
- All work tracked in git with atomic commits
- Phase plans in
.planning/PHASE-N-PLAN.md - Progress in git commit history
Local Development
- Run
make progressto see current status - Check
.planning/STATE.mdfor live project state - Review
.planning/ROADMAP.mdfor phase dependencies
Get Involved
Providing Feedback
- React to forum posts with 👍 / 👎 / 🎯
- Reply with thoughts on design decisions
- Suggest priorities for upcoming phases
Contributing
- Development contributions coming as phases execute
- Code review and testing needed starting Phase 1
- Security audit important for self-improvement system
Questions?
- Ask in the Discord thread
- Reply to this forum post with questions
- Issues/discussions: https://github.com/yourusername/mai
Mai's development is transparent and community-informed. Updates will continue as phases progress.
Next Update: After Phase 1 Planning Complete (target: next week)