FAQ & Troubleshooting

This comprehensive FAQ covers common questions and solutions for MemVoice development, setup, and usage.

🚀 Getting Started

Q: How do I set up the development environment?

A: Follow these steps:

1. Prerequisites: Ensure you have Node.js 18+, Python 3.11+, and Git installed
2. Clone Repository: git clone https://github.com/sadiuysal/memvoice.git
3. Environment Setup: Copy .env.example to .env and add your API keys
4. Backend Setup: Create virtual environment and install dependencies
5. Frontend Setup: Run npm install in the frontend directory
6. Start Servers: Run backend and frontend development servers

See the Contribution Guide for detailed setup instructions.

Q: What API keys do I need?

A: You'll need the following API keys:

• OpenAI API Key - For Whisper (STT), GPT models, and embeddings
• ElevenLabs API Key - For text-to-speech voice generation
• Pinecone API Key - For vector database storage
• Zep API Key - For memory management framework

Add these to your .env file following the .env.example template.

Q: How do I run tests?

A: Testing commands vary by component:

# All tests
npm run test:all

# Backend only
cd backend && pytest

# Frontend only  
cd frontend && npm test

# E2E tests
npm run test:e2e

# With coverage
cd backend && pytest --cov=src
cd frontend && npm run test:coverage

🏗️ Architecture & Design

Q: Where is the architecture documented?

A: Comprehensive architecture documentation is available in:

• Technical Architecture - System components and data flow
• Development Plan - Implementation phases and structure
• Project Overview - High-level system overview

Q: How does the memory optimization work?

A: MemVoice achieves 70% token reduction through:

• Short-term Memory: Sliding window for conversation context
• Long-term Memory: Vector-based semantic storage with Pinecone
• Token Compression: Custom algorithms for context summarization
• Intelligent Retrieval: Semantic search with relevance scoring

See Technical Architecture for detailed implementation.

Q: What's the voice processing pipeline?

A: The voice pipeline follows this flow:

1. Audio Capture → Browser MediaRecorder API
2. Speech-to-Text → OpenAI Whisper processing
3. Memory Retrieval → Context and history lookup
4. LLM Processing → Enhanced prompt with memory
5. Memory Update → Store new conversation data
6. Text-to-Speech → ElevenLabs voice generation
7. Audio Streaming → Real-time playback to user

🔧 Development Issues

Q: Tests are failing - what should I check?

A: Common test failure causes and solutions:

1. Environment Variables: Ensure .env file has all required API keys
2. Dependencies: Run pip install -r requirements.txt and npm install
3. Database: Check if test database is available and accessible
4. API Keys: Verify API keys are valid and have sufficient quota
5. Network: Ensure external APIs (OpenAI, ElevenLabs) are accessible

Run tests with verbose output: pytest -v or npm test --verbose

Q: Local development server won't start?

A: Troubleshooting steps:

Backend Issues:

# Check Python version
python --version  # Should be 3.11+

# Verify virtual environment
which python  # Should point to venv

# Check port availability
lsof -i :8000  # Kill any processes using port 8000

# Start with debug mode
uvicorn src.main:app --reload --log-level debug

Frontend Issues:

# Check Node version
node --version  # Should be 18+

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Start with debug
npm run dev -- --verbose

Q: How do I debug API integration issues?

A: Debug external API integrations:

1. Check API Keys: Verify keys are correct and active
2. Rate Limits: Check if you've hit API rate limits
3. Network Issues: Test connectivity to external services
4. Request Format: Validate request format matches API spec
5. Response Handling: Check error response parsing

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Q: Memory management not working as expected?

A: Common memory issues and solutions:

1. Zep Configuration: Verify Zep client setup and authentication
2. Vector Database: Check Pinecone index configuration
3. Token Limits: Ensure you're not exceeding token limits
4. Context Retrieval: Verify semantic search is finding relevant content

Debug memory operations:

# Enable memory debugging
memory_service = MemoryService(debug=True)
result = memory_service.add_memory(content)
print(f"Memory result: {result}")

🚀 Deployment & Production

Q: How do I deploy to production?

A: MemVoice uses serverless deployment:

Frontend (Vercel):

1. Connect GitHub repository to Vercel
2. Configure environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

Backend (Railway):

1. Connect GitHub repository to Railway
2. Configure environment variables in Railway dashboard
3. Deploy automatically on push to main branch

See deployment documentation for detailed instructions.

Q: Environment variables for production?

A: Required production environment variables:

# API Keys
OPENAI_API_KEY=your_production_openai_key
ELEVENLABS_API_KEY=your_production_elevenlabs_key
PINECONE_API_KEY=your_production_pinecone_key
ZEP_API_KEY=your_production_zep_key

# Database
DATABASE_URL=your_production_database_url

# App Configuration
NEXT_PUBLIC_API_URL=https://your-backend-domain.com
JWT_SECRET=your_secure_jwt_secret
ENVIRONMENT=production

Q: How do I monitor production issues?

A: MemVoice includes comprehensive monitoring:

• Error Tracking: Sentry integration for backend and frontend
• Performance Monitoring: Built-in metrics and logging
• Uptime Monitoring: External monitoring service
• Analytics: Custom usage tracking

Check monitoring dashboards and set up alerts for critical issues.

🤝 Contributing & Project Management

Q: How do I contribute to the project?

A: Follow the contribution workflow:

1. Read Guidelines: Start with Contribution Guide
2. Create Issue: Create GitHub issue for bugs/features (unless trivial)
3. Fork Repository: Fork and clone the repository
4. Create Branch: git checkout -b feature/your-feature-name
5. Implement Changes: Follow coding standards and write tests
6. Submit PR: Create pull request with comprehensive description

Q: What's the project management workflow?

A: MemVoice uses integrated GitHub + Linear workflow:

• GitHub: Technical implementation, code review, automation
• Linear: Project management, cycles, goals, business metrics
• Integration: Cross-platform issue synchronization
• Automation: CI/CD, testing, deployment pipelines

See Project Management for detailed workflow.

Q: How are issues prioritized?

A: Issue prioritization follows this hierarchy:

1. Critical: System down, security issues, customer-blocking bugs
2. High: Important features, major bugs affecting multiple users
3. Medium: Standard features, minor bugs with workarounds
4. Low: Nice-to-have improvements, documentation updates

Labels are applied automatically based on content analysis and manual review.

🔍 Performance & Optimization

Q: Voice processing is too slow - how to optimize?

A: Performance optimization strategies:

1. Audio Preprocessing: Optimize audio before sending to Whisper
2. Streaming: Use streaming for real-time processing
3. Caching: Cache common responses and embeddings
4. Batch Processing: Process multiple requests together
5. CDN: Use CDN for static assets

Target: < 2 seconds end-to-end latency (< 1.5s goal)

Q: Memory usage is high - how to reduce it?

A: Memory optimization techniques:

1. Token Compression: Implement aggressive context compression
2. Garbage Collection: Regular cleanup of old conversations
3. Vector Optimization: Optimize embedding storage
4. Context Windowing: Intelligent conversation truncation

Target: 70% token reduction vs baseline approaches

Q: Database queries are slow?

A: Database optimization steps:

1. Indexing: Add indexes for frequently queried fields
2. Query Optimization: Optimize N+1 queries and joins
3. Connection Pooling: Use connection pooling for efficiency
4. Caching: Implement Redis caching for frequent reads

Monitor query performance and optimize bottlenecks.

🔒 Security & Privacy

Q: How is user data protected?

A: MemVoice implements comprehensive data protection:

• Encryption: All data encrypted at rest and in transit
• User Isolation: Complete data separation between users
• Privacy Controls: Voice data processing with opt-in consent
• Compliance: GDPR-ready data handling procedures

Q: How do I report security issues?

A: For security vulnerabilities:

1. DO NOT create public GitHub issues
2. Email security concerns to project maintainers
3. Include detailed vulnerability description
4. Allow reasonable time for investigation and fix

Security issues are prioritized and addressed immediately.

📞 Getting Additional Help

Q: Where can I get more help?

A: Multiple support channels available:

1. Documentation: Check comprehensive docs in /docs directory
2. GitHub Issues: Report bugs and request features
3. GitHub Discussions: Ask questions and get community help
4. Wiki: This comprehensive wiki with guides and FAQ

Q: How do I stay updated on project progress?

A: Stay informed through:

• GitHub Repository: Watch for updates and releases
• Project Boards: Monitor development progress
• Wiki Updates: Regular updates to documentation
• Release Notes: Detailed changelog for each release

Q: Can I use MemVoice commercially?

A: Yes, MemVoice is released under MIT License, allowing commercial use. See the LICENSE file for complete terms.

---

🆘 Quick Reference

Common Commands

# Development setup
git clone https://github.com/sadiuysal/memvoice.git
cd memvoice && cp .env.example .env

# Start development
cd backend && uvicorn src.main:app --reload
cd frontend && npm run dev

# Run tests
npm run test:all
pytest --cov=src

# Code quality
black . && isort . && flake8 .
npm run lint:fix

Important Links

• Home - Wiki homepage and navigation
• Project Overview - Business and technical overview
• Development Plan - Complete development roadmap
• Contribution Guide - How to contribute
• Technical Architecture - System architecture details
• Project Management - Workflow and process

---

Can't find what you're looking for? Create an issue or start a discussion!