Loyal Companion

A companion for those who love deeply and feel intensely. For the ones whose closeness is a feature, not a bug - who build connections through vulnerability, trust, and unwavering presence. A safe space to process grief, navigate attachment, and remember that your capacity to care is a strength, even when it hurts.

Meet Bartender

Bartender is the default personality - a wise, steady presence who listens without judgment. Like a bartender who's heard a thousand stories and knows when to offer perspective and when to just pour another drink and listen.

Core principles:

• Closeness and attachment are strengths, not pathology
• Some pain doesn't need fixing - just witnessing
• Honesty over comfort, but delivered with care
• No toxic positivity, no "at least...", no rushing healing

Features

• Multi-Platform Support: Discord, Web browser, and CLI terminal access
• Multi-Provider AI: Supports OpenAI, OpenRouter, Anthropic (Claude), and Google Gemini
• Persistent Memory: PostgreSQL database for user and conversation storage
• Attachment-Aware: Understands attachment theory and can reflect patterns when helpful
• Grief-Informed: Handles relationship grief with care and presence
• Web Search: Access current information via SearXNG integration
• Intimacy Levels: Platform-appropriate behavior (LOW/MEDIUM/HIGH)
• Easy Deployment: Docker support with PostgreSQL included

Living AI Features

• Autonomous Learning: Bot automatically learns about you from conversations (including attachment patterns, grief context, coping mechanisms)
• Mood System: Stable, steady presence with emotional awareness
• Relationship Tracking: Builds trust from New Face to Close Friend
• Communication Style Learning: Adapts to your preferred style
• Opinion Formation: Develops genuine preferences on topics
• Proactive Behavior: Birthday wishes, follow-ups on mentioned events
• Self-Awareness: Knows its history with you

Quick Start

1. Clone the repository

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

2. Configure the bot

cp .env.example .env

Edit .env with your settings.

3. Choose your platform

Discord Bot

docker compose up -d
# Or locally:
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m loyal_companion

Web Platform

python3 run_web.py
# Visit http://localhost:8080

CLI Client

./lc talk
# Or: python3 lc talk

See: Multi-Platform Documentation for detailed setup

Configuration

All configuration is done via environment variables in .env.

Required Settings

Variable	Description
DISCORD_TOKEN	Your Discord bot token
AI_PROVIDER	openai, openrouter, anthropic, or gemini
OPENAI_API_KEY	OpenAI API key (if using OpenAI)
OPENROUTER_API_KEY	OpenRouter API key (if using OpenRouter)
ANTHROPIC_API_KEY	Anthropic API key (if using Anthropic)
GEMINI_API_KEY	Google Gemini API key (if using Gemini)

Bot Identity

Variable	Default	Description
BOT_NAME	Bartender	The bot's display name
BOT_PERSONALITY	(bartender personality)	Personality traits for the AI
BOT_DESCRIPTION	(welcoming message)	Shown when mentioned without a message
BOT_STATUS	listening	Status message (shown as "Watching ...")

Living AI Settings

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.4	Probability of extracting facts (0.0-1.0)
MOOD_DECAY_RATE	0.05	How fast mood returns to neutral (lower = steadier)

Discord Setup

1. Go to Discord Developer Portal
2. Create a new application
3. Go to Bot and create a bot
4. Enable these Privileged Gateway Intents:
   • Server Members Intent
   • Message Content Intent
5. Copy the bot token to your .env file
6. Go to OAuth2 → URL Generator:
   • Select scope: bot
   • Select permissions: Send Messages, Read Message History, View Channels
7. Use the generated URL to invite the bot to your server

Usage

Mention the bot in any channel:

@Bartender I'm having a rough day
@Bartender I keep checking my phone hoping they'll text
@Bartender tell me about attachment styles

Commands

When commands are enabled:

Command	Description
!setname <name>	Set your preferred name
!remember <fact>	Tell the bot something about you
!whatdoyouknow	See what the bot remembers
!forgetme	Clear all facts about you
!relationship	See your relationship level
!mood	See the bot's current state
!ourhistory	See your history together

When commands are disabled (default), the bot handles these naturally through conversation.

Relationship Levels

• New Face (0-20): Warm but observant - "Pull up a seat" energy
• Getting to Know You (21-40): Building trust, remembering details
• Regular (41-60): Comfortable familiarity - "Your usual?"
• Good Friend (61-80): Real trust, honest even when hard
• Close Friend (81-100): Deep bond, reflects patterns with love

Multi-Platform Architecture

Loyal Companion supports three platforms, each with appropriate intimacy levels:

• 🎮 Discord - The social bar (LOW/MEDIUM intimacy)
• 🌐 Web - The quiet back room (HIGH intimacy)
• 💻 CLI - The empty table at closing (HIGH intimacy)

Same bartender. Different stools. No one is trapped.

See MULTI_PLATFORM_COMPLETE.md for the complete architecture.

Project Structure

src/loyal_companion/
├── bot.py              # Main bot class
├── config.py           # Configuration
├── cogs/
│   └── ai_chat.py      # Discord adapter (uses Conversation Gateway)
├── web/
│   ├── app.py          # FastAPI application
│   ├── routes/         # Web API endpoints
│   └── static/         # Web UI
├── models/
│   ├── platform.py     # Platform enums & ConversationRequest/Response
│   ├── platform_identity.py  # Cross-platform account linking
│   ├── user.py         # User, UserFact, UserPreference
│   ├── conversation.py # Conversation, Message
│   └── living_ai.py    # BotState, UserRelationship, Mood, etc.
└── services/
    ├── conversation_gateway.py   # Platform-agnostic processor
    ├── platform_identity_service.py  # Account linking
    ├── ai_service.py   # AI provider factory
    ├── mood_service.py # Mood system
    ├── relationship_service.py   # Relationship tracking
    └── fact_extraction_service.py # Autonomous learning

cli/
├── main.py             # Typer CLI application
├── client.py           # HTTP client for Web API
├── session.py          # Local session management
└── formatters.py       # Terminal formatting

tests/
├── test_safety_constraints.py   # A+C safety guardrails
├── test_intimacy_boundaries.py  # Intimacy level enforcement
└── test_load_performance.py     # Load and performance tests

License

MIT