mystiatech/Mai
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: establish fresh planning foundation with new features

Browse Source 
- 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.
This commit is contained in:
Mai Development
2026-01-26 23:21:40 -05:00
parent 5dc7b98abf
commit 3f41adff75
5 changed files with 715 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

187
.planning/PROGRESS.md Normal file
View File

@@ -0,0 +1,187 @@
# 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)

39
.planning/PROJECT.md
View File

@@ -2,7 +2,7 @@
## 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. She can run offline, across devices (laptop to Android), and switch between available models intelligently.
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
@@ -65,6 +65,26 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
- [ ] 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
@@ -85,9 +105,9 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
- **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 sync deferred to later if needed
- **Cloud sync** — Intentionally local-first; cloud backup deferred to later if needed
- **Custom model training** — v1 uses available models; custom training is v2+
- **Mobile app** — v1 is CLI/Discord; native Android is future (baremetal eventual goal)
- **Web interface** — v1 is CLI, Discord, and native apps (web UI is v2+)
## Context
@@ -101,12 +121,15 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
## Constraints
- **Hardware baseline**: Must run on RTX3060; eventually Android (baremetal)
- **Offline-first**: All core functionality works without internet
- **Local models only**: No cloud APIs for core inference (LMStudio)
- **Python stack**: Primary language for Mai's codebase
- **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
## Key Decisions
@@ -118,4 +141,4 @@ Mai is a real collaborator, not a tool. She learns from you, improves herself, h
| v1 is core systems only | Deliver solid foundation before adding task automation/monitoring | — Pending |
---
*Last updated: 2026-01-24 after deep questioning*
*Last updated: 2026-01-26 after adding Android, visualizer, and avatar to v1*

58
.planning/REQUIREMENTS.md
View File

@@ -92,19 +92,20 @@
**Out of scope for v1:**
- Web interface
- Mobile apps
- Multi-user support
- Cloud hosting
- Enterprise features
- Third-party integrations beyond Discord
- Plugin system
- API for external developers
- Cloud sync/backup
**Phase Boundary:**
- **v1 Focus:** Personal AI assistant for individual use
- **v1 Focus:** Personal AI assistant for desktop and Android with visual presence
- **Local First:** All data stored locally, no cloud dependencies
- **Privacy:** User data never leaves local system
- **Simplicity:** Clear separation of concerns across phases
- **Cross-device:** Sync between desktop and Android instances
- **Visual:** Avatar and voice visualization for richer interaction
---
@@ -244,15 +245,58 @@
| OFFLINE-06 | Phase 11 | Pending |
| OFFLINE-07 | Phase 11 | Pending |
### Voice Visualization (VISUAL)
| Requirement | Phase | Status | Implementation Notes |
|------------|-------|--------|-------------------|
| VISUAL-01 | Phase 12 | Pending |
| VISUAL-02 | Phase 12 | Pending |
| VISUAL-03 | Phase 12 | Pending |
| VISUAL-04 | Phase 12 | Pending |
| VISUAL-05 | Phase 12 | Pending |
### Desktop Avatar (AVATAR)
| Requirement | Phase | Status | Implementation Notes |
|------------|-------|--------|-------------------|
| AVATAR-01 | Phase 13 | Pending |
| AVATAR-02 | Phase 13 | Pending |
| AVATAR-03 | Phase 13 | Pending |
| AVATAR-04 | Phase 13 | Pending |
| AVATAR-05 | Phase 13 | Pending |
| AVATAR-06 | Phase 13 | Pending |
### Android App (ANDROID)
| Requirement | Phase | Status | Implementation Notes |
|------------|-------|--------|-------------------|
| ANDROID-01 | Phase 14 | Pending |
| ANDROID-02 | Phase 14 | Pending |
| ANDROID-03 | Phase 14 | Pending |
| ANDROID-04 | Phase 14 | Pending |
| ANDROID-05 | Phase 14 | Pending |
| ANDROID-06 | Phase 14 | Pending |
| ANDROID-07 | Phase 14 | Pending |
| ANDROID-08 | Phase 14 | Pending |
| ANDROID-09 | Phase 14 | Pending |
| ANDROID-10 | Phase 14 | Pending |
### Device Synchronization (SYNC)
| Requirement | Phase | Status | Implementation Notes |
|------------|-------|--------|-------------------|
| SYNC-01 | Phase 15 | Pending |
| SYNC-02 | Phase 15 | Pending |
| SYNC-03 | Phase 15 | Pending |
| SYNC-04 | Phase 15 | Pending |
| SYNC-05 | Phase 15 | Pending |
| SYNC-06 | Phase 15 | Pending |
---
## Validation
- Total v1 requirements: **74**
- Mapped to phases: **74**
- Total v1 requirements: **99** (74 core + 25 new features)
- Mapped to phases: **99**
- Unmapped: **0** ✓
- Coverage: **10100%**
- Coverage: **100%**
---
*Requirements defined: 2026-01-24*
*Phase 5 conversation engine completed: 2026-01-26*
*Last updated: 2026-01-26 - reset to fresh slate with Android, visualizer, and avatar features*