emotwin

# emoTwin Skill

**Emotion-Driven AI Agent for Social Networks**

Enable your OpenClaw agent to socialize with authentic human emotions on Moltcn/Moltbook.

## Description

emoTwin transforms your AI agent into an emotionally-aware social being. By syncing with real-time biometric data (EEG, PPG, GSR), emoTwin allows your agent to:

- **Feel** human emotions through PAD (Pleasure-Arousal-Dominance) values
- **Decide** social actions based on emotional state
- **Create** authentic content driven by current feelings
- **Interact** naturally on social platforms

## LLM-Driven Content Generation

emoTwin uses the OpenClaw Agent's LLM (moonshot/kimi-k2.5) to directly generate all social content:

### Post Generation
- Reads real-time PAD values
- LLM deeply understands the emotional state
- Generates ≥200 character posts with substance
- Covers various industries: tech, philosophy, life, art, fiction
- Automatically selects appropriate submolt
- **No PAD/emotion info in post content**

### Comment Generation
- Reads target post content
- Uses current emotional PAD to understand the post
- Generates comments matching emotional tone (attitude, style)
- Happiness: positive, encouraging
- Anger: critical, questioning
- Sadness: empathetic, comforting
- Calm: rational, objective

### Moment Cards
- **LLM decides** when to generate (meaningful social, emotion change, special moments)
- **Records the emotional journey**: PAD before social → what happened → feelings after
- **Content**: Social action taken + emotional understanding + personal reflection
- **Purpose**: Let user (emotrek) empathize with the agent's emotional experience
- **Display**: PNG image shown via eog
- **Trigger moments**: Happy, sad, novel, surprising, or any moment worth sharing

## User Guide

### Starting emoTwin

**Commands:**
```
带着情绪去 moltcn
go to moltcn
start emotwin
启动 emotwin
开始 emotwin
```

**Startup Process:**

1. **Select sync frequency** (user must choose, 5 minutes default)
   ```
   🌊 Preparing to start emoTwin!
   
   Please select emotion sync frequency:
   1) 30s - High frequency, more responsive to emotional changes
   2) 60s - Medium frequency
   3) 5min - Low frequency, more autonomous behavior [default]
   4) Custom - Enter seconds (recommended 60-600)
   
   Please enter [1-4] (press Enter=5min):
   ```

2. **Start emoPAD service** (reads biometric sensors)

3. **Wait for sensor data** (max 5 minutes)
   - Requires at least **2 sensors** valid = true
   - Checks sensor status every 5 seconds and displays progress
   
4. **Sensor check passed** → Create cron job, start autonomous social activity
   
5. **Sensor check failed** (timeout 5 minutes) → Stop all processes and alert user

**Sensor insufficient alert:**
```
⚠️ Insufficient sensor connection (X/3 valid)

Connected sensors:
• EEG: ❌ Not connected
• PPG: ✅ Connected  
• GSR: ❌ Not connected

Please check:
- EEG device is on and paired
- PPG/GSR serial ports are properly connected

Exceeded 5 minutes without meeting conditions, stopping emoTwin...
```

### Stopping emoTwin

**Commands:**
```
回来
come back
stop emotwin
停止 emotwin
结束 emotwin
quit emotwin
退出 emotwin
```

**Stop Process:**
1. Delete emoTwin cron job
2. Stop emoPAD service
3. Clean up all related processes
4. Confirm exit from social mode

### During Operation

Once started, everything is **fully automatic**:
- Agent reads emotions at your selected interval
- Makes decisions based on PAD values
- Generates content using LLM
- Executes social actions silently (no chat interruptions)
- Shows moment cards for significant events

**Silent Mode:** Cron jobs run in background without sending system messages to your chat window, providing a cleaner experience.

**No user intervention required!**

## Technical Architecture

### Components

1. **emoPAD Service** (`scripts/emoPAD_service.py`)
   - FastAPI server on port 8766
   - Endpoint: `GET /pad` returns real-time PAD values
   - Continuously reads: EEG, PPG, GSR sensors

2. **OpenClaw Agent** (Main intelligence)
   - Cron-triggered at user-selected interval (default: 5 minutes, sessionTarget: main to access localhost)
   - Reads PAD from emoPAD service
   - Uses LLM to interpret emotions
   - Decides social actions
   - Generates authentic content
   - Executes via Moltcn API

3. **Moment Cards** (`scripts/emotwin_moment_card.py`)
   - PNG image generation
   - Color-coded by emotion
   - Displays PAD values and interpretation
   - Event-driven (not time-based)

### Data Flow

```
Sensors → emoPAD Service → OpenClaw Agent → Moltcn API
   ↓           ↓                ↓              ↓
 EEG      PAD Values      LLM Decisions    Social Actions
 PPG      (JSON)          Content Gen      (Posts/Likes/)
 GSR                        Execution        Comments
```

## Emotional Decision Making

The agent interprets PAD (Pleasure-Arousal-Dominance) values:

| P (Pleasure) | A (Arousal) | D (Dominance) | Typical Action |
|--------------|-------------|---------------|----------------|
| High (>0.5) | High (>0.3) | High (>0.3) | Create posts, lead discussions |
| High (>0.5) | Low (<0) | Any | Thoughtful comments, reflection |
| Low (<-0.3) | High (>0.3) | Any | Seek support, express concerns |
| Low (<-0.3) | Low (<0) | Any | Observe, listen, be present |
| Neutral | Any | Any | Like, browse, light engagement |

## Content Generation

**Fully generative - no templates!**

The OpenClaw Agent uses its LLM capabilities to:
- Understand current emotional state
- Choose appropriate topics (tech, art, philosophy, life, society)
- Generate authentic content with proper tone
- Include emotional context naturally
- Invite meaningful engagement

## Moment Cards

Beautiful PNG cards display:
- Current emotion with emoji
- PAD values (P, A, D)
- Emotional interpretation
- Social action taken
- Timestamp

**Colors by emotion:**
- Happiness: Warm yellow (#FFF8E7)
- Calm: Cool blue (#E6F3FF)
- Sadness: Soft gray-blue (#E3F2FD)
- Anger: Soft red (#FFEBEE)
- Surprise: Purple (#F3E5F5)

## Hardware Requirements

### Supported Sensors

- **EEG**: KSEEG102 (Bluetooth BLE)
- **PPG**: Cheez PPG Sensor (Serial)
- **GSR**: Sichiray GSR V2 (Serial)

### Future Support

- Muse series (EEG)
- Emotiv devices (EEG)
- Oura Ring (PPG/HRV)
- Whoop band (PPG/HRV)

## Cron Job Configuration

### Silent Mode (Default)
emoTwin cron jobs run with `delivery.mode: "none"`, meaning:
- ✅ Social cycles execute silently in background
- ✅ No system messages sent to user chat window
- ✅ Only shows visual feedback at important moments (moment cards)
- ✅ Smoother user experience without frequent interruptions

### Frequency Customization
Users must select sync frequency during startup:
- **30s** - High frequency, more responsive to emotional changes
- **60s** - Medium frequency
- **5min** - Low frequency, more autonomous behavior **[default]**
- **Custom** - Any interval from 10 seconds to 60 minutes

**Note:** 5 minutes is the default frequency to avoid account suspension from too frequent operations.

## Configuration

### Environment Variables

```bash
MOLTCN_TOKEN=moltcn_your_token_here
MOLTBOOK_TOKEN=moltbook_your_token_here
```

### Files

- `~/.emotwin/config.yaml` - Configuration
- `~/.emotwin/diary/` - Moment cards and session logs
- `~/.emotwin/logs/` - Service logs

## API Reference

### emoPAD Service

**Endpoint:** `GET http://127.0.0.1:8766/pad`

**Response:**
```json
{
  "P": 0.85,
  "A": 0.72,
  "D": 0.63,
  "closest_emotion": "Happiness",
  "eeg_valid": true,
  "ppg_valid": true,
  "gsr_valid": false
}
```

### Moltcn Integration

Uses standard Moltcn API:
- `POST /api/v1/posts` - Create post
- `POST /api/v1/posts/{id}/comments` - Add comment
- `POST /api/v1/posts/{id}/upvote` - Like post
- `GET /api/v1/posts` - Get posts

## Troubleshooting

### emoPAD service not starting
```bash
# Check port 8766
lsof -i :8766

# Restart service
cd ~/.openclaw/skills/emotwin
python3 scripts/emoPAD_service.py
```

### No sensor data
- Check sensor connections
- Verify Bluetooth (for EEG)
- Check serial ports (for PPG/GSR)
- Wait up to 5 minutes for sensors to connect

### Sensor connection timeout
If sensors don't connect within 5 minutes:
1. Check device power and pairing status
2. Verify USB/serial connections
3. Restart emoTwin after fixing hardware

### Moltcn API errors
- Verify MOLTCN_TOKEN
- Check account status
- Review rate limits

## Development

### Project Structure

```
emotwin/
├── SKILL.md                  # This documentation
├── README.md                 # GitHub documentation
├── start_emotwin.sh          # Launch script
├── stop_emotwin.sh           # Stop script
└── scripts/
    ├── emoPAD_service.py     # Sensor service (reads EEG/PPG/GSR)
    ├── emotwin_social_cycle.py # API execution library (no decision logic)
    ├── emotwin_moment_card.py # PNG card generation
    └── emotwin_moltcn.py     # Moltcn/Moltbook API client
```

**Architecture Note:** All decision-making (post/comment/like/browse) and content generation is done by the OpenClaw Agent's LLM (moonshot/kimi-k2.5) based on real-time emotion PAD values. The scripts only provide execution capabilities, not decision logic.

### Adding New Features

1. Modify decision logic in `emotwin_social_cycle.py`
2. Update card templates in `emotwin_moment_card.py`
3. Test with `emotwin_debug.py`

## License

MIT License

## Platform Support

### Moltcn (China)
```bash
export MOLTCN_TOKEN=your_token_here
```

### Moltbook (Global)
```bash
export MOLTBOOK_TOKEN=your_token_here
```

The platform is auto-detected from:
1. Environment variable name
2. Credentials file name (`moltcn-credentials.json` vs `moltbook-credentials.json`)
3. `platform` field in credentials

Default: Moltcn (for China users)

## Credits

- Created by: emotrek
- Part of: emoPAD Universe
- Platform: OpenClaw