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.
188 lines
8.1 KiB
Markdown
188 lines
8.1 KiB
Markdown
# 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
|
|
- [x] Codebase mapping complete (7 architectural documents)
|
|
- [x] Project vision and core value defined
|
|
- [x] Requirements inventory (99 items across 15 phases)
|
|
- [x] README with comprehensive setup and features
|
|
- [ ] Roadmap creation (distributing requirements across phases)
|
|
- [ ] First phase planning (Model Interface)
|
|
|
|
### Next Steps
|
|
1. Create detailed ROADMAP.md with phase dependencies
|
|
2. Plan Phase 1: Model Interface & Switching
|
|
3. Begin implementation of LMStudio/Ollama integration
|
|
4. 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:
|
|
1. `/gsd:plan-phase N` → Creates detailed PHASE-N-PLAN.md
|
|
2. `/gsd:execute-phase N` → Implements with automatic test coverage
|
|
3. 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 `.venv` virtual 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 progress` to see current status
|
|
- Check `.planning/STATE.md` for live project state
|
|
- Review `.planning/ROADMAP.md` for 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)
|