rebased

.planning/PROJECT.md

@@ -0,0 +1,121 @@
+# 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. She can run offline, across devices (laptop to Android), and switch between available models intelligently.
+
+## 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)
+
+**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 sync 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)
+
+## 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, git for version control of her own code, Discord API for chat, lightweight local storage for memory. 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; 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
+- **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
+
+## 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-24 after deep questioning*