Graph-Twin Assistant

A modular, local-first personal assistant system composed of 9 agents that function like a personal company, with 5 operational agents handling domain-specific tasks and 4 strategic agents coordinating the system.

Core Concept

The core metaphor is a "Graph-Twin": a personal semantic knowledge graph in Neo4j that represents the user's life, activities, and goals, continuously updated by intelligent agents that process text and voice inputs.

Target Solution

The Graph-Twin AI Personal Assistant, when fully implemented, will provide:

End-User Experience

• Multi-Agent Interface: Dedicated pages for each agent with personalized chat interfaces
• Persistent Memory: Each agent remembers past conversations and learns user preferences
• Unique Agent Personalities: Distinct communication styles and expertise areas for each agent
• Intelligent Input Triage: Automatic routing of user queries to the most appropriate agent(s)
• Cross-Domain Insights: Connections between different life areas (health, finances, tasks, etc.)
• Interactive Dashboards: Visual representations of the knowledge graph and insights
• Multi-Modal Input: Both text and voice input options (voice via Telegram integration)

Technical Capabilities

• Semantic Knowledge Graph: Structured representation of the user's life, activities, and goals
• Model Context Protocol (MCP): Sophisticated communication framework for agent coordination
• Adaptive Optimization: Self-tuning system based on usage patterns and performance metrics
• ML-Enhanced Insights: Automatic pattern detection and trend analysis across domains
• External Service Integration: Future connections to calendars, health apps, financial services
• Privacy-Preserving Design: Local-first architecture with optional cloud synchronization

System Architecture

• Environment: Ubuntu (local-only deployment)
• Language: Python 3.11
• Project Management: Poetry + pipx
• Database: Neo4j 5 (embedded mode possible)
• Event Bus: Redis Pub/Sub ("StreamBridge" pattern)
• LLMs: Claude 3.7 (primary) + GPT-4o (secondary) via API keys
• Voice Processing: OpenAI Whisper
• Frontend: Streamlit dashboard
• Input Methods:
  • Text via Streamlit UI
  • Voice via Telegram Bot
• Testing: pytest
• Documentation: Markdown + projectstatus.md

Agent System Structure

Operational Agents (5)

1. Health Agent: Track physical wellbeing, nutrition, and health activities
2. Finance Agent: Track financial transactions and budget
3. Task Agent: Manage todos and projects
4. Time Agent: Track and optimize time usage
5. Lifestyle Agent: Track habits, mood, and personal development

Strategic Agents (4)

6. CEO Agent: Provide high-level oversight and goal tracking
7. Architect Agent: Maintain system structure and provide technical insights
8. Project Manager (PM) Agent: Track feature development and maintain roadmap
9. Personal Assistant (PA) Agent: Coordinate day-to-day operations and user communication

Installation

1. Clone the repository
2. Install Poetry if not already installed
3. Install dependencies:

   poetry install
   

4. Copy .env.example to .env and set your API keys
5. Initialize Neo4j (follow instructions in docs)
6. Start the system:

   poetry run python -m src.main
   

Development

See projectstatus.md for current development status and next steps.

License

Private use only.

---

Setup & Troubleshooting Guide (Stabilized)

1. Environment Setup

• Python 3.11 is required.
• It is strongly recommended to use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

• Install dependencies:

pip install -r requirements.txt

2. Configuration

• Copy .env.example to .env and fill in all required API keys (especially TELEGRAM_BOT_TOKEN).
• Ensure Neo4j and Redis are running if using those integrations.

3. Launching the System

Web UI (Streamlit)

cd graph_twin_assistant
python run_ui.py

• The UI will be available at http://localhost:8501/
• If you see an import error or blank page, check the terminal for error messages.

Telegram Bot

cd graph_twin_assistant
python run_telegram_bot.py

• The bot will log to telegram_bot.log.
• If you see ModuleNotFoundError or import errors, ensure your venv is activated and all dependencies installed.

4. Troubleshooting

• Virtual Environment: Always activate .venv before running anything. If you see a warning, activate your venv.
• Imports: If you see import errors, ensure you are running from the correct directory and all dependencies are installed.
• Dependencies: If you get ModuleNotFoundError, run pip install -r requirements.txt inside your venv.
• Telegram Bot: Check telegram_bot.log for errors. All handler errors and incoming messages are logged.
• Streamlit UI: If the UI is blank, check your terminal for errors and ensure all required modules are present.
• .env: Make sure all required environment variables are set in .env.

5. Additional Notes

• For development, use only requirements.txt for dependency management.
• If you use Poetry, ensure it is in sync with requirements.txt.
• For further debugging, contact the project maintainer or check the logs for details.

---

This guide reflects the stabilized setup and will help prevent and diagnose the most common issues with the Graph-Twin AI Personal Assistant system.