Companion Bot Framework

A modular, customizable AI companion bot framework built on Discord.py with advanced memory systems, voice synthesis, and personality management.

Features

• Advanced Memory System: Persistent conversation memory with semantic search and automatic summarization
• Personality Engine: Configurable personalities with different speaking styles and behaviors
• Voice Synthesis: Multi-provider voice support (ElevenLabs, Cartesia, gTTS)
• Media Triggers: Configurable automated responses based on context and emotions
• Memory Gardener: Autonomous memory organization and visualization
• Modular Architecture: Easy to extend with custom modules
• Easy Setup: Interactive setup wizard for quick configuration
• Database Support: MySQL/MariaDB for reliable data persistence

Quick Start

Prerequisites

• Python 3.8+
• MySQL or MariaDB database
• Discord bot token
• AI API key (OpenRouter or ElectronHub)

Installation

1. Clone the repository

   git clone https://github.com/your-username/companion-bot-framework.git
   cd companion-bot-framework

2. Install dependencies

   pip install -r requirements.txt

3. Run the setup wizard

   python setup_wizard.py

4. Start your bot

   python bot/main.py

📋 Configuration

The framework uses two main configuration files:

• config.json - Main bot configuration
• .env - Environment variables and API keys

Basic Configuration

{
  "discord": {
    "token": "YOUR_BOT_TOKEN",
    "command_prefix": "!"
  },
  "ai_provider": {
    "primary": "openrouter",
    "openrouter": {
      "api_key": "YOUR_API_KEY",
      "model": "google/gemma-3-27b-it:free"
    }
  },
  "personality": {
    "file": "default.json",
    "memory_enabled": true
  }
}

Personalities

The framework includes several pre-built personalities:

• Default: Friendly, helpful general companion
• Professional: Business-focused assistant
• Creative: Artistic, imaginative muse
• Supportive: Empathetic emotional support companion

Custom Personalities

Create custom personalities by adding JSON files to the personalities/ directory:

{
  "name": "Your Custom Bot",
  "system_prompt": "You are a helpful AI with a unique personality...",
  "personality": {
    "traits": ["helpful", "witty", "curious"],
    "speaking_style": "casual and friendly"
  },
  "behavioral_settings": {
    "memory_importance_threshold": 0.3,
    "voice_responses": true,
    "proactive_engagement": true
  }
}

Memory System

The memory system provides:

• Persistent Storage: All conversations saved to database
• Semantic Search: Find relevant past conversations
• Automatic Summarization: Long conversations condensed intelligently
• Importance Scoring: Prioritize meaningful interactions
• Cross-Channel Memory: Remember users across different channels

Memory Commands

• /memory_search <query> - Search through conversation history
• /save_memory - Force save current conversation to memory
• /memory_stats - View memory system statistics

Voice System

ElevenLabs

{
  "voice": {
    "provider": "elevenlabs",
    "elevenlabs": {
      "api_key": "your-api-key",
      "voice_id": "21m00Tcm4TlvDq8ikWAM"
    }
  }
}

Media Triggers

Configure automated responses to emotional contexts:

{
  "triggers": [
    {
      "name": "comfort_response",
      "keywords": ["sad", "lonely", "hurt"],
      "emotional_threshold": 0.7,
      "trigger_chance": 0.3,
      "media": [
        {
          "type": "text",
          "content": "*offers a warm virtual hug* 🤗"
        }
      ]
    }
  ]
}

🌱 Memory Gardener Module

Autonomous memory organization system:

• Automatically categorizes memories
• Posts memory summaries to designated channels
• Provides memory statistics and insights
• No external dependencies (Obsidian-free)

Enable in config.json:

{
  "modules": {
    "gardener": {
      "enabled": true,
      "channel_id": 1234567890,
      "check_interval_seconds": 300
    }
  }
}

Creating Custom Modules

Extend the framework with custom modules:

# modules/my_module.py
async def setup_my_module(bot, config):
    \"\"\"Setup function called by the main bot\"\"\"
    
    @bot.tree.command(name="my_command")
    async def my_command(interaction):
        await interaction.response.send_message("Hello from my module!")
    
    print("My custom module loaded!")

Register in bot/main.py:

from modules.my_module import setup_my_module

# In setup_modules function:
if config.modules.get("my_module", {}).get("enabled", False):
    await setup_my_module(bot, module_config)

Development

Project Structure

companion-bot-framework/
├── bot/
│   ├── main.py              # Main bot file
│   ├── config.py            # Configuration management
│   ├── ai_handler.py        # AI response generation
│   ├── memory_system.py     # Memory persistence
│   ├── voice_handler.py     # Voice synthesis
│   └── personality_loader.py # Personality management
├── modules/
│   ├── media_triggers.py    # Media trigger system
│   └── gardener.py         # Memory gardener
├── personalities/
│   ├── default.json        # Default personality
│   ├── professional.json   # Professional assistant
│   ├── creative.json       # Creative muse
│   └── supportive.json     # Supportive friend
├── setup_wizard.py         # Interactive setup
├── requirements.txt        # Python dependencies
└── README.md              # This file