loyal_companion/docs

Daemon Boyfriend - Technical Documentation

Welcome to the technical documentation for Daemon Boyfriend, a Discord bot with AI-powered personality, emotional depth, and relationship awareness.

Quick Navigation

Document	Description
Architecture Overview	High-level system design, components, data flow
Living AI System	Mood, relationships, fact extraction, opinions
Services Reference	API documentation for all services
Database Schema	Complete database schema reference
Configuration	All environment variables and settings
Developer Guides	How to extend and develop the bot

---

What is Daemon Boyfriend?

Daemon Boyfriend is a Discord bot that goes beyond simple chatbot functionality. It features a sophisticated "Living AI" system that gives the bot:

• Emotional States - A mood system based on psychological valence-arousal model
• Relationship Tracking - Evolving relationships from stranger to close friend
• Memory - Learns and remembers facts about users
• Opinions - Develops opinions on topics through discussion
• Personality Adaptation - Learns each user's communication style

---

Architecture at a Glance

┌─────────────────────────────────────────────────────────────────┐
│                         Discord API                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Discord Bot                               │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐                 │
│  │ AIChatCog  │  │ MemoryCog  │  │ StatusCog  │                 │
│  └────────────┘  └────────────┘  └────────────┘                 │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌────────────────┐  ┌────────────────┐  ┌────────────────────────┐
│ Core Services  │  │ Living AI      │  │    AI Providers        │
│                │  │                │  │                        │
│ UserService    │  │ MoodService    │  │ OpenAI / Anthropic /   │
│ DatabaseService│  │ RelationshipSvc│  │ Gemini / OpenRouter    │
│ ConversationMgr│  │ FactExtraction │  │                        │
│ SearXNGService │  │ OpinionService │  │                        │
└────────────────┘  └────────────────┘  └────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      PostgreSQL Database                         │
└─────────────────────────────────────────────────────────────────┘

---

Documentation Structure

Core Documentation

File	Contents
architecture.md	System architecture, design patterns, component interactions
database.md	Database schema, tables, indexes, relationships
configuration.md	All configuration options with examples

Living AI Deep Dives

File	Contents
living-ai/README.md	Overview of all Living AI systems
living-ai/mood-system.md	Valence-arousal model, mood labels, decay
living-ai/relationship-system.md	Relationship levels, scoring algorithm
living-ai/fact-extraction.md	AI-powered fact learning, deduplication
living-ai/opinion-system.md	Topic sentiment, interest tracking

Developer Resources

File	Contents
services/README.md	Complete API reference for all services
guides/README.md	How to add providers, commands, features

---

Key Concepts

Message Flow

1. User @mentions the bot in Discord
2. AIChatCog receives the message
3. User context is built (name, facts, preferences)
4. Living AI context is gathered (mood, relationship, style, opinions)
5. Enhanced system prompt is constructed
6. AI provider generates response
7. Living AI systems are updated (mood, relationship, facts)
8. Response is sent to Discord

Living AI Components

Component	Purpose	Update Frequency
Mood	Emotional state	Every interaction
Relationship	User familiarity	Every interaction
Facts	User knowledge	~30% of messages
Opinions	Topic preferences	When topics discussed
Style	Communication preferences	Rolling 50 messages

Database Modes

Mode	Configuration	Use Case
PostgreSQL	DATABASE_URL set	Production, persistence
In-Memory	DATABASE_URL not set	Development, testing

---

Quick Start

1. Install

pip install -r requirements.txt
pip install -e .

2. Configure

# Minimum .env
DISCORD_TOKEN=your_token
OPENAI_API_KEY=your_key

3. Run

python -m loyal_companion

4. Interact

Mention the bot in Discord:

@Daemon Hello! How are you today?

---

Commands Reference

User Commands

Command	Description
!setname <name>	Set your preferred name
!clearname	Reset to Discord name
!remember <fact>	Tell the bot something about you
!whatdoyouknow	See what the bot remembers
!forgetme	Clear all your facts
!relationship	See your relationship status
!mood	See the bot's current mood
!botstats	View bot statistics
!ourhistory	See your history with the bot
!birthday <date>	Set your birthday

Admin Commands

Command	Description
!setusername @user <name>	Set name for another user
!teachbot @user <fact>	Add a fact about a user
!status	View bot health metrics

---

Support

• Project Issues: GitHub Issues
• Documentation Updates: Submit a PR

---

Document Changelog

Version	Date	Changes
1.0	2024-01	Initial documentation