loyal_companion/docs/living-ai/README.md

Living AI System

The Living AI system gives the bot personality, emotional depth, and relationship awareness. It transforms a simple chatbot into a character that learns, remembers, and evolves through interactions.

Table of Contents

• Overview
• System Components
• How It Works Together
• Feature Toggle Reference

Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Living AI System                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │    Mood      │  │ Relationship │  │    Fact      │  │   Opinion    │    │
│  │   System     │  │   System     │  │  Extraction  │  │   System     │    │
│  │              │  │              │  │              │  │              │    │
│  │ Valence +    │  │  5 levels    │  │   AI-based   │  │   Topic      │    │
│  │ Arousal      │  │  0-100 score │  │   learning   │  │  sentiments  │    │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘    │
│                                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐    │
│  │Communication │  │  Proactive   │  │ Association  │  │    Self      │    │
│  │    Style     │  │   Events     │  │   System     │  │  Awareness   │    │
│  │              │  │              │  │              │  │              │    │
│  │   Learned    │  │  Birthdays,  │  │ Cross-user   │  │    Stats,    │    │
│  │ preferences  │  │  follow-ups  │  │   memory     │  │  reflection  │    │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

System Components

1. Mood System

File: services/mood_service.py
Documentation: mood-system.md

The bot has emotions that affect how it responds. Uses a valence-arousal psychological model:

• Valence (-1 to +1): Negative to positive emotional state
• Arousal (-1 to +1): Calm to excited energy level

Mood Labels:

Valence	Arousal	Label
High	High	Excited
High	Low	Happy
Neutral	Low	Calm
Neutral	Neutral	Neutral
Low	Low	Bored
Low	High	Annoyed
Neutral	High	Curious

Key Features:

• Time decay: Mood gradually returns to neutral
• Inertia: Changes are dampened (30% absorption rate)
• Mood affects response style via prompt modifiers

---

2. Relationship System

File: services/relationship_service.py
Documentation: relationship-system.md

Tracks relationship depth with each user:

Score	Level	Behavior
0-20	Stranger	Polite, formal
21-40	Acquaintance	Friendly, reserved
41-60	Friend	Casual, warm
61-80	Good Friend	Personal, references past
81-100	Close Friend	Very casual, inside jokes

Relationship Score Factors:

• Interaction sentiment (+/- 0.5 base)
• Message length (up to +0.3 bonus)
• Conversation depth (up to +0.2 bonus)
• Minimum interaction bonus (+0.1)

---

3. Fact Extraction System

File: services/fact_extraction_service.py
Documentation: fact-extraction.md

Autonomously learns facts about users from conversations:

Fact Types:

• hobby - Activities and interests
• work - Job, career, professional life
• family - Family members and relationships
• preference - Likes, dislikes, preferences
• location - Where they live, travel to
• event - Important life events
• relationship - Personal relationships
• general - Other facts

Extraction Process:

1. Rate-limited (default 30% of messages)
2. AI analyzes message for extractable facts
3. Deduplication against existing facts
4. Facts stored with confidence and importance scores

---

4. Opinion System

File: services/opinion_service.py
Documentation: opinion-system.md

Bot develops opinions on topics over time:

Opinion Attributes:

• Sentiment (-1 to +1): How positive/negative about the topic
• Interest Level (0 to 1): How engaged when discussing
• Discussion Count: How often topic has come up
• Reasoning: AI-generated explanation (optional)

Topic Detection: Simple keyword-based extraction for categories like:

• Hobbies (gaming, music, movies, etc.)
• Technology (programming, AI, etc.)
• Life (work, family, health, etc.)
• Interests (philosophy, science, nature, etc.)

---

5. Communication Style System

File: services/communication_style_service.py

Learns each user's preferred communication style:

Tracked Preferences:

• Response Length: short / medium / long
• Formality: 0 (casual) to 1 (formal)
• Emoji Usage: 0 (none) to 1 (frequent)
• Humor Level: 0 (serious) to 1 (playful)
• Detail Level: 0 (brief) to 1 (thorough)

Learning Process:

• Analyzes last 50 messages (rolling window)
• Requires 10+ samples for confidence > 0.3
• Generates prompt modifiers to adapt response style

---

6. Proactive Events System

File: services/proactive_service.py

Schedules and triggers proactive messages:

Event Types:

• Birthday: Remembers and celebrates birthdays
• Follow-up: Returns to check on mentioned events
• Reminder: General scheduled reminders

Detection Methods:

• Birthday: Regex patterns for dates
• Follow-up: AI-based event detection or keyword matching

Event Lifecycle:

1. Detection from conversation
2. Scheduled in database
3. Triggered when due
4. Personalized message generated

---

7. Association System

File: services/association_service.py

Links facts across different users (optional, disabled by default):

Use Cases:

• "User A and User B both work at the same company"
• "Multiple users share an interest in hiking"
• Enables group context and shared topic suggestions

---

8. Self-Awareness System

File: services/self_awareness_service.py

Provides the bot with statistics about itself:

Available Stats:

• Age (time since first activation)
• Total messages sent
• Total facts learned
• Total users known
• Favorite topics (from opinions)

Used for the !botstats command and self-reflection in responses.

---

How It Works Together

When a user sends a message, the Living AI components work together:

┌──────────────────────────────────────────────────────────────────────────────┐
│                           Message Processing                                  │
└──────────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
            ┌──────────────┐┌──────────────┐┌──────────────┐
            │  Get Mood    ││Get Relationship│ Get Style   │
            │              ││              ││              │
            │ Current state││ Level + refs ││ Preferences  │
            └──────────────┘└──────────────┘└──────────────┘
                    │               │               │
                    └───────────────┼───────────────┘
                                    ▼
                    ┌──────────────────────────────────────┐
                    │     Build Enhanced System Prompt      │
                    │                                       │
                    │  Base personality + mood modifier +   │
                    │  relationship context + style prefs + │
                    │  relevant opinions                    │
                    └──────────────────────────────────────┘
                                    │
                                    ▼
                    ┌──────────────────────────────────────┐
                    │          Generate Response            │
                    └──────────────────────────────────────┘
                                    │
                    ┌───────────────┼───────────────┐
                    ▼               ▼               ▼
            ┌──────────────┐┌──────────────┐┌──────────────┐
            │ Update Mood  ││   Record     ││   Maybe      │
            │              ││ Interaction  ││Extract Facts │
            │Sentiment +   ││              ││              │
            │arousal delta ││Score update  ││ Rate-limited │
            └──────────────┘└──────────────┘└──────────────┘
                                    │
                                    ▼
                    ┌──────────────────────────────────────┐
                    │       Check for Proactive Events      │
                    │                                       │
                    │   Detect birthdays, follow-ups        │
                    └──────────────────────────────────────┘

Example System Prompt Enhancement

[Base Personality]
You are Daemon, a friendly AI companion...

[Mood Modifier]
You're feeling enthusiastic and energetic right now! Be expressive, 
use exclamation marks, show genuine excitement.

[Relationship Context]  
This is a good friend you know well. Be relaxed and personal. 
Reference things you've talked about before. Feel free to be playful.
You have inside jokes together: "the coffee incident".

[Communication Style]
This user prefers longer, detailed responses with some humor. 
They use casual language, so match their tone.

[Relevant Opinions]
You really enjoy discussing programming; You find gaming interesting.

---

Feature Toggle Reference

All Living AI features can be individually enabled/disabled:

Environment Variable	Default	Description
LIVING_AI_ENABLED	true	Master switch for all Living AI features
MOOD_ENABLED	true	Enable mood system
RELATIONSHIP_ENABLED	true	Enable relationship tracking
FACT_EXTRACTION_ENABLED	true	Enable autonomous fact extraction
FACT_EXTRACTION_RATE	0.3	Probability of extracting facts (0-1)
PROACTIVE_ENABLED	true	Enable proactive messages
CROSS_USER_ENABLED	false	Enable cross-user associations
OPINION_FORMATION_ENABLED	true	Enable opinion formation
STYLE_LEARNING_ENABLED	true	Enable communication style learning
MOOD_DECAY_RATE	0.1	How fast mood returns to neutral (per hour)

---

Detailed Documentation

• Mood System Deep Dive
• Relationship System Deep Dive
• Fact Extraction Deep Dive
• Opinion System Deep Dive