Mai/.planning/codebase/CONCERNS.md

Codebase Concerns

Analysis Date: 2026-01-26

Tech Debt

Incomplete Memory System Integration:

• Issue: Memory manager gracefully initializes but may fail silently when dependencies are missing
• Files: src/mai/memory/manager.py
• Impact: Memory features degrade ungracefully; users don't know compression or retrieval is disabled
• Fix approach: Add explicit logging and health checks on startup, expose memory system status in CLI

Large Monolithic Memory Manager:

• Issue: MemoryManager is 1036 lines with multiple responsibilities (storage, compression, retrieval orchestration)
• Files: src/mai/memory/manager.py
• Impact: Difficult to test individual memory subsystems; changes affect multiple concerns simultaneously
• Fix approach: Extract retrieval delegation and compression orchestration into separate coordinator classes

Conversation Engine Complexity:

• Issue: ConversationEngine is 648 lines handling timing, state, decomposition, reasoning, interruption, and metrics
• Files: src/mai/conversation/engine.py
• Impact: High cognitive load for maintainers; hard to isolate bugs in specific subsystems
• Fix approach: Separate concerns into focused orchestrator (engine) and behavior modules (timing/reasoning/decomposition are already separated but loosely coupled)

Permission/Approval System Fragility:

• Issue: ApprovalSystem uses regex pattern matching for risk analysis with hardcoded patterns
• Files: src/mai/sandbox/approval_system.py
• Impact: Pattern-matching approach is fragile (false positives/negatives); patterns not maintainable as code evolves
• Fix approach: Replace regex with AST-based code analysis for more reliable risk detection; move risk patterns to configuration

Docker Executor Dependency Chain:

• Issue: DockerExecutor falls back silently to unavailable state if Docker isn't installed
• Files: src/mai/sandbox/docker_executor.py
• Impact: Approval system thinks code is sandboxed when Docker is missing; security false sense of safety
• Fix approach: Require explicit Docker availability check at startup; block code execution if Docker unavailable and user requests sandboxing

Known Bugs

Session Persistence Restoration:

• Symptoms: "ConversationState object has no attribute 'set_conversation_history'" error when restarting CLI
• Files: src/mai/conversation/state.py, src/app/__main__.py
• Trigger: Start conversation, exit CLI, restart CLI session
• Workaround: None - session restoration broken; users lose conversation history
• Status: Identified in Phase 6 UAT but remediation code not applied (commit c70ee88 "Complete fresh slate" removed implementation)

Session File Feedback Missing:

• Symptoms: Users don't see where/when session files are created
• Files: src/app/__main__.py
• Trigger: Create new session or use /session command
• Workaround: Manually check ~/.mai/session.json directory
• Status: Identified in Phase 6 UAT as major issue (test 3 failed)

Resource Display Color Coding:

• Symptoms: Resource monitoring displays plain text instead of color-coded status indicators
• Files: src/app/__main__.py
• Trigger: Run CLI and observe resource display during conversation
• Workaround: Parse output manually to understand resource status
• Status: Identified in Phase 6 UAT as minor issue (test 5 failed); root cause: Rich console loses color output in non-terminal environments

Security Considerations

Approval System Risk Analysis Insufficient:

• Risk: Regex-based risk detection can be bypassed with obfuscated code (e.g., string concatenation to build dangerous commands)
• Files: src/mai/sandbox/approval_system.py
• Current mitigation: Hardcoded high-risk patterns (os.system, exec, eval); fallback to block on unrecognized patterns
• Recommendations:
  • Implement AST-based code analysis for more reliable detection
  • Add code deobfuscation step before risk analysis
  • Create risk assessment database with test cases and known bypasses
  • Require explicit docker verification before allowing code execution

Docker Fallback Security Gap:

• Risk: Code could execute without actual sandboxing if Docker unavailable, creating false sense of security
• Files: src/mai/sandbox/docker_executor.py
• Current mitigation: AuditLogger records all execution; approval system presents requests regardless
• Recommendations:
  • Fail-safe: Block code execution if Docker unavailable and user hasn't explicitly allowed non-sandboxed execution
  • Add warning dialog explaining sandbox unavailability
  • Log all non-sandboxed execution attempts explicitly
  • Require explicit override from user with confirmation

Approval Preference Learning Risk:

• Risk: User can set "auto_allow" on risky code patterns; once learned, code execution auto-approves without user intervention
• Files: src/mai/sandbox/approval_system.py (lines with user_preferences and auto_allow)
• Current mitigation: Auto-allow only applies to LOW risk level code
• Recommendations:
  • Require explicit user confirmation before enabling auto-allow (not just responding "a")
  • Log all auto-approved executions in audit trail with reason
  • Add periodic review mechanism for auto-allow rules (e.g., "You have X auto-approved rules, review them?" on startup)
  • Restrict auto-allow to strictly limited operation types (print, basic math, not file operations)

Performance Bottlenecks

Memory Retrieval Search Not Optimized:

• Problem: ContextRetriever does full database scans for semantic similarity without indexing
• Files: src/mai/memory/retrieval.py
• Cause: Vector similarity search likely using brute-force nearest-neighbor without FAISS or similar
• Improvement path:
  • Add FAISS vector index for semantic search acceleration
  • Implement result caching for frequent queries
  • Add search result pagination to avoid loading entire result sets
  • Benchmark retrieval latency and set targets (e.g., <500ms for top-10 similar conversations)

Conversation State History Accumulation:

• Problem: ConversationState.conversation_history grows unbounded during long sessions
• Files: src/mai/conversation/state.py
• Cause: No automatic truncation or archival of old turns; all conversation turns kept in memory
• Improvement path:
  • Implement sliding window of recent turns (e.g., keep last 50 turns in memory)
  • Archive old turns to disk and load on demand
  • Add compression trigger at configurable message count
  • Monitor memory usage and alert when conversation history exceeds threshold

Memory Manager Compression Not Scheduled:

• Problem: Manual compress_conversation() calls required; no automatic compression scheduling
• Files: src/mai/memory/manager.py
• Cause: Compression is triggered manually or not at all; no background task or event-driven compression
• Improvement path:
  • Implement background compression task triggered by conversation age or message count
  • Add periodic compression sweep for all old conversations
  • Make compression interval configurable (e.g., compress every 500 messages or 24 hours)
  • Track compression effectiveness and adjust thresholds

Fragile Areas

Ollama Integration Dependency:

• Files: src/mai/model/ollama_client.py, src/mai/core/interface.py
• Why fragile: Hard-coded Ollama endpoint assumption; no fallback model provider; no retry logic for model inference
• Safe modification:
  • Use dependency injection for model provider (interface-based)
  • Add configurable model provider endpoints
  • Implement retry logic with exponential backoff for transient failures
  • Add model availability detection at startup
• Test coverage: Limited tests for model switching and unavailability scenarios

Git Integration Fragility:

• Files: src/mai/git/committer.py, src/mai/git/workflow.py
• Why fragile: Assumes clean git state; no handling for merge conflicts, detached HEAD, or dirty working directory
• Safe modification:
  • Add pre-commit git status validation
  • Handle merge conflict detection and defer commits
  • Implement conflict resolution strategy (manual review or aborting)
  • Test against all git states (detached HEAD, dirty working tree, conflicted merge)
• Test coverage: No tests for edge cases like merge conflicts

Conversation State Serialization Round-Trip:

• Files: src/mai/conversation/state.py, src/mai/models/conversation.py
• Why fragile: ConversationTurn -> Ollama message -> ConversationTurn conversion can lose context
• Safe modification:
  • Add comprehensive unit tests for serialization round-trip
  • Document serialization format and invariants
  • Add validation after deserialization (verify message count, order, role integrity)
  • Create fixture tests with edge cases (unicode, very long messages, special characters)
• Test coverage: No existing tests for message serialization/deserialization

Docker Configuration Hardcoding:

• Files: src/mai/sandbox/docker_executor.py
• Why fragile: Docker image names, CPU limits, memory limits hardcoded as class constants
• Safe modification:
  • Move Docker config to configuration file
  • Add validation on startup that Docker limits match system resources
  • Document all Docker configuration assumptions
  • Make limits tunable per system resource profile
• Test coverage: Docker integration tests likely mocked; no testing on actual Docker variations

Scaling Limits

Memory Database Size Growth:

• Current capacity: SQLite with no explicit limits; storage grows with every conversation
• Limit: SQLite performance degrades significantly above ~1GB; queries become slow
• Scaling path:
  • Implement database rotation (archive old conversations, start new DB periodically)
  • Add migration path to PostgreSQL for production deployments
  • Implement automatic old conversation archival (move to cold storage after 30 days)
  • Add database vacuum and index optimization on scheduled basis

Conversation Context Window Management:

• Current capacity: Model context window determined by Ollama model selection (varies)
• Limit: ConversationEngine doesn't prevent context overflow; will fail when history exceeds model limit
• Scaling path:
  • Track token count of conversation history and refuse new messages before overflow
  • Implement automatic compression trigger at 80% context usage
  • Add model switching logic to use larger-context models if available
  • Document context budget requirements per model

Approval History Unbounded Growth:

• Current capacity: ApprovalSystem.approval_history list grows indefinitely
• Limit: Memory accumulation over time; each approval decision stored in memory forever
• Scaling path:
  • Archive approval history to database after threshold (e.g., 1000 decisions)
  • Implement approval history rotation with configurable retention
  • Add aggregate statistics (approval patterns) instead of storing raw history
  • Clean up approval history on startup or scheduled task

Dependencies at Risk

Ollama Dependency and Model Availability:

• Risk: Hard requirement on Ollama being available and having models installed
• Impact: Mai cannot function without Ollama; no fallback to cloud inference or other providers
• Migration plan:
  • Implement abstract model provider interface
  • Add support for OpenAI/other cloud models as fallback (even if v1 is offline-first)
  • Document minimum Ollama model requirements
  • Add diagnostic tool to check Ollama health on startup

Docker Dependency for Sandboxing:

• Risk: Docker required for code execution safety; no alternative sandbox implementations
• Impact: Users without Docker can't safely execute generated code; no graceful degradation
• Migration plan:
  • Implement abstract executor interface (not just DockerExecutor)
  • Add noop executor for testing
  • Consider lightweight alternatives (seccomp, chroot, or bubblewrap) for Linux systems
  • Add explicit warning if Docker unavailable

Rich Library Terminal Detection:

• Risk: Rich disables colors in non-terminal environments; users see degraded UX
• Impact: Resource monitoring and status displays lack visual feedback in non-terminal contexts
• Migration plan:
  • Use Console(force_terminal=True) to force color output when desired
  • Add configuration option for color preference
  • Implement fallback emoji/unicode indicators for non-color environments
  • Test in various terminal emulators and SSH sessions

Missing Critical Features

Session Data Portability:

• Problem: Session files are JSON but no export/import mechanism; can't backup or migrate sessions
• Blocks: Users can't back up conversations; losing ~/.mai/session.json loses all context
• Fix: Add export/import commands (/export, /import) and document session file format

Conversation Memory Persistence:

• Problem: Conversation history is session-scoped (stored in memory); not saved to memory system
• Blocks: Long-term pattern learning relies on memory system but conversations aren't automatically stored
• Fix: Implement automatic conversation archival to memory system after session ends

User Preference Learning Audit Trail:

• Problem: User preferences for auto-approval learned silently; no visibility into what patterns auto-approve
• Blocks: Users can't audit their own auto-approval rules; hard to recover from accidentally enabling auto-allow
• Fix: Add /preferences or /audit command to show all learned rules and allow revocation

Resource Constraint Graceful Degradation:

• Problem: System shows resource usage but doesn't adapt model selection or conversation behavior
• Blocks: Mai can't suggest switching to smaller models when resources tight
• Fix: Implement resource-aware model recommendation system

Approval Change Logging:

• Problem: Approval decisions not tracked in git; can't audit "who approved what when"
• Blocks: No accountability trail for approval decisions
• Fix: Log all approval decisions to git with commit messages including timestamp and user

Test Coverage Gaps

Docker Executor Network Isolation:

• What's not tested: Whether network actually restricted in Docker containers
• Files: src/mai/sandbox/docker_executor.py
• Risk: Code might have network access despite supposed isolation
• Priority: High (security-critical)

Session Persistence Edge Cases:

• What's not tested: Very large conversations (1000+ messages), unicode characters, special characters
• Files: src/mai/conversation/state.py, session persistence code
• Risk: Session files corrupt or lose data with edge case inputs
• Priority: High (data loss)

Approval System Obfuscation Bypass:

• What's not tested: Obfuscated code patterns, string concatenation attacks, bytecode approaches
• Files: src/mai/sandbox/approval_system.py
• Risk: Risky code could slip through as "low risk" via obfuscation
• Priority: High (security-critical)

Memory Compression Round-Trip Data Loss:

• What's not tested: Whether compressed conversations can be exactly reconstructed
• Files: src/mai/memory/compression.py, src/mai/memory/storage.py
• Risk: Compression could lose important context patterns; compression metrics may be misleading
• Priority: Medium (data integrity)

Model Switching During Active Conversation:

• What's not tested: Switching models mid-conversation, context migration, embedding space changes
• Files: src/mai/model/switcher.py, src/mai/conversation/engine.py
• Risk: Context might not transfer correctly when models switch
• Priority: Medium (feature reliability)

Offline Queue Conflict Resolution:

• What's not tested: What happens when offline messages conflict with new context when reconnecting
• Files: src/mai/conversation/engine.py (offline queueing)
• Risk: Offline messages might create incoherent conversation when reconnected
• Priority: Medium (conversation coherence)

Resource Detector System Resource Edge Cases:

• What's not tested: GPU detection on systems with unusual hardware, CPU count on virtual systems
• Files: src/mai/model/resource_detector.py
• Risk: Wrong model selection due to misdetected resources
• Priority: Low (graceful degradation usually handles this)

---

Concerns audit: 2026-01-26