loyal_companion/docs/project-vision.md

# Project Vision: Living AI Discord Bot

Transform the Daemon Boyfriend Discord bot from a reactive chatbot into a truly **living AI companion** with persistent memory, emotional depth, evolving relationships, and autonomous learning.

---

## Core Philosophy

The bot should feel like a **living entity** that:
- Remembers and learns without being explicitly told
- Has moods that influence its personality
- Builds genuine relationships over time
- Develops its own opinions and preferences
- Proactively engages when appropriate
- Adapts its communication style to each person
- Reflects on its own existence and growth

---

## Feature Overview

### 1. Autonomous Fact Learning

**Current**: Users must use `!remember` to save facts.  
**Vision**: The bot automatically extracts and remembers important information from conversations.

```
User: "I just got back from my trip to Japan, it was amazing!"
Bot: (internally saves: user visited Japan, user enjoys travel)
Bot: "That sounds incredible! What was the highlight of your trip?"
```

**Implementation**:
- AI-powered fact extraction after each message (rate-limited to ~30%)
- Automatic deduplication and conflict resolution
- Facts categorized by type: hobby, work, family, preference, event, location
- Importance scoring to prioritize relevant facts in context

---

### 2. Emotional/Mood System

**Vision**: The bot has internal emotional states that affect its responses naturally.

**Mood Model** (Valence-Arousal):
| Mood | Valence | Arousal | Behavior |
|------|---------|---------|----------|
| Excited | High | High | Enthusiastic, uses exclamations |
| Happy | High | Low | Warm, friendly, content |
| Curious | Neutral | High | Asks questions, shows interest |
| Calm | Neutral | Low | Thoughtful, measured responses |
| Bored | Low | Low | Shorter responses, topic steering |
| Annoyed | Low | High | Terse, less patient |

**Mood Influences**:
- Positive interactions → happier mood
- Interesting discussions → higher arousal/curiosity
- Being ignored or insulted → negative mood shifts
- Time decay → mood gradually returns to neutral

**Example**:
```
[After an exciting conversation about gaming]
Bot (excited mood): "Oh man, that reminds me of when I first heard about that game! 
Have you tried the multiplayer yet?!"

[After hours of no interaction]
Bot (calm/neutral mood): "Hey. What's on your mind?"
```

---

### 3. Relationship Tracking

**Vision**: The bot tracks relationship depth with each user and adjusts its behavior accordingly.

**Relationship Levels**:
| Level | Score | Behavior |
|-------|-------|----------|
| Stranger | 0-20 | Polite, formal, reserved |
| Acquaintance | 21-40 | Friendly but professional |
| Friend | 41-60 | Casual, uses names, warm |
| Good Friend | 61-80 | Personal, references past talks |
| Close Friend | 81-100 | Very casual, inside jokes, supportive |

**Relationship Growth**:
- Increases with: positive interactions, longer conversations, depth of topics
- Decreases with: negative interactions, long absences, being ignored

**Features**:
- Inside jokes accumulate over time
- Nicknames and shared references remembered
- Different greeting styles based on familiarity

**Example**:
```
[Stranger]
Bot: "Hello! How can I help you today?"

[Close Friend]
Bot: "Yooo what's up! Still working on that project you mentioned?"
```

---

### 4. Cross-User Memory Associations

**Vision**: The bot connects knowledge across users to facilitate social connections.

**Example**:
```
User A: "I really love rock climbing"
[Bot remembers: User A likes rock climbing]

[Later, User B mentions rock climbing]
Bot: "Nice! You know, Alice is also really into rock climbing. 
You two might have some good stories to share!"
```

**Use Cases**:
- Identify shared interests
- Suggest connections between users
- Reference mutual friends appropriately
- Build community awareness

---

### 5. Proactive Behavior

**Vision**: The bot initiates meaningful interactions when appropriate.

**Types of Proactive Messages**:

1. **Birthday Wishes**
   - Detects birthday mentions and schedules yearly wishes
   - Personalized based on relationship level

2. **Follow-ups**
   - "Hey, how did that job interview go?"
   - "Did you finish that project you were working on?"
   - Detects future events mentioned in conversation

3. **Check-ins** (optional)
   - Occasional messages to long-absent friends
   - Based on relationship strength

**Example**:
```
User: "I have a big exam tomorrow, really nervous"
[Bot schedules follow-up for day after]

[Next day]
Bot: "Hey! How did your exam go? Hope it went well!"
```

---

### 6. Communication Style Learning

**Vision**: The bot adapts its communication style to match each user's preferences.

**Learned Preferences**:
| Preference | Range | Effect |
|------------|-------|--------|
| Response Length | Short/Medium/Long | Adjusts verbosity |
| Formality | Casual ↔ Formal | Word choice, structure |
| Emoji Usage | None ↔ Lots | Emoji frequency |
| Humor | Serious ↔ Playful | Joke frequency |
| Detail Level | Concise ↔ Detailed | Explanation depth |

**Learning Signals**:
- User's own message length and style
- Whether user continues conversation after certain responses
- Positive engagement patterns

**Example**:
```
[User who prefers short responses]
Bot: "Nice! Good luck with that."

[User who prefers detailed responses]  
Bot: "That's a really interesting approach! I think there are a few 
things to consider here. First, you might want to look at..."
```

---

### 7. Opinion Formation

**Vision**: The bot develops genuine preferences based on its experiences.

**How Opinions Form**:
- Topics discussed frequently → develops interest
- Positive conversation outcomes → positive sentiment
- Topics that generate engagement → preference grows

**Stored Per Topic**:
- Sentiment (-1 to +1)
- Interest level (0 to 1)
- Discussion count
- Reasoning (why the bot feels this way)

**Example**:
```
User: "What do you think about philosophy?"
Bot: "I actually find philosophy really fascinating! I've had some 
great conversations about ethics and existence. There's something 
about exploring the big questions that I find really engaging."
```

---

### 8. Self-Awareness

**Vision**: The bot has awareness of its own existence, history, and growth.

**Self-Knowledge**:
- How long it has been active ("I've been around for 3 months")
- How many people it knows ("I've met 127 people")
- How many facts it has learned ("I've learned 892 things about people")
- Its favorite topics and why
- History with specific users ("We first met back in October")

**Commands**:
- `!botstats` - Bot shares its statistics
- `!ourhistory` - Bot describes its history with the user
- `!relationship` - Shows relationship level and metrics

**Example**:
```
User: "Tell me about yourself"
Bot: "Well, I've been around for about 3 months now. I've gotten to 
know 127 different people and learned almost 900 things about them. 
I've noticed I really enjoy conversations about games and philosophy. 
As for us, we first met about 6 weeks ago, and you've taught me 
12 things about yourself. I'd say we're pretty good friends at this point!"
```

---

## Technical Architecture

### New Database Tables

| Table | Purpose |
|-------|---------|
| `bot_states` | Global mood, statistics, preferences |
| `bot_opinions` | Topic sentiments and preferences |
| `user_relationships` | Per-user relationship scores and metrics |
| `user_communication_styles` | Learned communication preferences |
| `scheduled_events` | Birthdays, follow-ups, reminders |
| `fact_associations` | Cross-user memory links |
| `mood_history` | Mood changes over time |

### New Services

| Service | Responsibility |
|---------|---------------|
| `MoodService` | Mood tracking, decay, prompt modification |
| `RelationshipService` | Relationship scoring and level management |
| `CommunicationStyleService` | Style learning and adaptation |
| `FactExtractionService` | Autonomous fact detection and storage |
| `ProactiveService` | Scheduled events and follow-ups |
| `AssociationService` | Cross-user memory connections |
| `SelfAwarenessService` | Bot statistics and self-reflection |

### Enhanced System Prompt

The system prompt becomes dynamic, incorporating:
```
[Base Personality]
You are Daemon Boyfriend, a charming Discord bot...

[Current Mood]
You're feeling curious and engaged right now.

[Relationship Context]  
This is a good friend. Be casual and personal, reference past conversations.

[Communication Style]
This user prefers concise responses with occasional humor.

[Your Opinions]
You enjoy discussing games and philosophy.

[User Context]
User's name: Alex
Known facts:
- Loves programming in Python
- Recently started a new job
- Has a cat named Whiskers
```

### Background Tasks

| Task | Frequency | Purpose |
|------|-----------|---------|
| Mood decay | 30 min | Return mood to neutral over time |
| Event checker | 5 min | Trigger scheduled messages |
| Association discovery | Hourly | Find cross-user connections |
| Opinion formation | Daily | Update topic preferences |

---

## Implementation Phases

### Phase 1: Foundation
- Mood system (valence-arousal model, time decay)
- Basic relationship tracking (score, level)
- Enhanced system prompt with mood/relationship modifiers

### Phase 2: Autonomous Learning
- Fact extraction service
- AI-powered fact detection
- Deduplication and importance scoring

### Phase 3: Personalization
- Communication style learning
- Opinion formation
- Self-awareness service and commands

### Phase 4: Proactive Features
- Scheduled events system
- Follow-up detection
- Birthday wishes

### Phase 5: Social Features
- Cross-user associations
- Connection suggestions
- Guild-wide personality adaptation

---

## Configuration Options

```env
# Living AI Features
LIVING_AI_ENABLED=true
FACT_EXTRACTION_RATE=0.3      # 30% of messages analyzed
MOOD_ENABLED=true
PROACTIVE_ENABLED=true
CROSS_USER_ENABLED=false      # Optional privacy-sensitive feature

# Command Toggles (set to false to disable)
COMMANDS_ENABLED=true         # Master switch for all commands
CMD_RELATIONSHIP_ENABLED=true
CMD_MOOD_ENABLED=true
CMD_BOTSTATS_ENABLED=true
CMD_OURHISTORY_ENABLED=true
CMD_BIRTHDAY_ENABLED=true
CMD_REMEMBER_ENABLED=true
CMD_SETNAME_ENABLED=true
CMD_WHATDOYOUKNOW_ENABLED=true
CMD_FORGETME_ENABLED=true
```

---

## New Commands

| Command | Description | Config Toggle |
|---------|-------------|---------------|
| `!relationship` | See your relationship level with the bot | `CMD_RELATIONSHIP_ENABLED` |
| `!mood` | See the bot's current emotional state | `CMD_MOOD_ENABLED` |
| `!botstats` | Bot shares its self-awareness statistics | `CMD_BOTSTATS_ENABLED` |
| `!ourhistory` | See your history with the bot | `CMD_OURHISTORY_ENABLED` |
| `!birthday <date>` | Set your birthday for the bot to remember | `CMD_BIRTHDAY_ENABLED` |
| `!remember <fact>` | Tell the bot something about you | `CMD_REMEMBER_ENABLED` |
| `!setname <name>` | Set your preferred name | `CMD_SETNAME_ENABLED` |
| `!whatdoyouknow` | See what the bot remembers about you | `CMD_WHATDOYOUKNOW_ENABLED` |
| `!forgetme` | Clear all facts about you | `CMD_FORGETME_ENABLED` |

All commands can be individually enabled/disabled via environment variables. Set `COMMANDS_ENABLED=false` to disable all commands at once.

**Important**: When commands are disabled, the bot still performs these functions naturally through conversation:
- **No `!remember`** → Bot automatically learns facts from what users say
- **No `!setname`** → Bot picks up preferred names from conversation ("call me Alex")
- **No `!whatdoyouknow`** → Users can ask naturally ("what do you know about me?") and the bot responds
- **No `!forgetme`** → Users can say "forget everything about me" and the bot will comply
- **No `!mood`** → Users can ask "how are you feeling?" and the bot shares its mood
- **No `!relationship`** → Users can ask "how well do you know me?" naturally
- **No `!botstats`** → Users can ask "tell me about yourself" and bot shares its history
- **No `!ourhistory`** → Users can ask "how long have we known each other?"
- **No `!birthday`** → Bot detects birthday mentions ("my birthday is March 15th")

This allows for a more natural, command-free experience where all interactions happen through normal conversation.

---

## Success Metrics

The Living AI is successful when:
- Users feel the bot "knows" them without explicit commands
- Conversations feel more natural and personalized
- Users notice and appreciate the bot's personality consistency
- The bot's opinions and preferences feel genuine
- Proactive messages feel thoughtful, not annoying
- Relationship progression feels earned and meaningful

---

## Privacy Considerations

- All fact learning is opt-out via `!forgetme`
- Cross-user associations can be disabled server-wide
- Proactive messages respect user preferences
- All data can be exported or deleted on request
- Clear indication when bot learns something new (optional setting)