clawbrain

# Claw Brain Skill 🧠

Personal AI Memory System with Soul, Bonding, and Learning for ClawDBot.

## Features

- 🎭 **Soul/Personality** - 6 evolving traits (humor, empathy, curiosity, creativity, helpfulness, honesty)
- 👤 **User Profile** - Learns user preferences, interests, communication style
- 💭 **Conversation State** - Real-time mood detection and context tracking
- 📚 **Learning Insights** - Continuously learns from interactions and corrections
- 🧠 **get_full_context()** - Everything for personalized responses

---

## Installation

### Option 1: Git Clone (Recommended for ClawDBot)

```bash
# Clone into ClawDBot workspace
git clone https://github.com/clawcolab/clawbrain.git ClawBrain
```

### Option 2: pip install

```bash
pip install git+https://github.com/clawcolab/clawbrain.git
```

---

## ClawDBot Setup

### 1. Install the Skill

```bash
# Clone to your ClawDBot workspace
cd /path/to/your/clawdbot
git clone https://github.com/clawcolab/clawbrain.git ClawBrain
```

### 2. Import in Your Bot

Add to your bot's main file (e.g., `main.py`):

```python
import sys
sys.path.insert(0, "ClawBrain")

from clawbrain import Brain

# Initialize the brain
brain = Brain()

# Make it available globally or pass to handlers
app.brain = brain
```

### 3. Use in Message Handlers

```python
def handle_message(message, channel="telegram"):
    # Get user context
    context = app.brain.get_full_context(
        session_key=f"{channel}_{message.chat.id}",
        user_id=str(message.chat.id),
        agent_id="jarvis",
        message=message.text
    )
    
    # Generate personalized response
    response = generate_response(context)
    
    # Store conversation
    app.brain.remember(
        agent_id="jarvis",
        memory_type="conversation",
        content=message.text,
        key=f"last_message_{message.chat.id}"
    )
    
    return response
```

---

## Configuration

### Environment Variables

```bash
# PostgreSQL (optional - auto-detected)
export POSTGRES_HOST=192.168.4.176
export POSTGRES_PORT=5432
export POSTGRES_DB=clawcolab
export POSTGRES_USER=postgres
export POSTGRES_PASSWORD=postgres

# Redis (optional - auto-detected)
export REDIS_HOST=192.168.4.175
export REDIS_PORT=6379
```

### Force Storage Backend

```python
# Force SQLite (zero setup)
brain = Brain({"storage_backend": "sqlite"})

# Force PostgreSQL
brain = Brain({"storage_backend": "postgresql"})

# Auto-detect (default)
brain = Brain()
```

---

## API Reference

### Brain Class

```python
from clawbrain import Brain

brain = Brain()
```

#### Methods

| Method | Description | Returns |
|--------|-------------|---------|
| `get_full_context()` | Get all context for personalized responses | dict |
| `remember()` | Store a memory | None |
| `recall()` | Retrieve memories | List[Memory] |
| `learn_user_preference()` | Learn user preferences | None |
| `get_user_profile()` | Get user profile | UserProfile |
| `detect_user_mood()` | Detect current mood | dict |
| `detect_user_intent()` | Detect message intent | str |
| `generate_personality_prompt()` | Generate personality guidance | str |
| `health_check()` | Check backend connections | dict |
| `close()` | Close connections | None |

### get_full_context()

```python
context = brain.get_full_context(
    session_key="telegram_12345",  # Unique session ID
    user_id="username",              # User identifier
    agent_id="jarvis",             # Bot identifier
    message="Hey, how's it going?" # Current message
)
```

**Returns:**
```python
{
    "user_profile": {...},        # User preferences, interests
    "mood": {"mood": "happy", ...},  # Current mood
    "intent": "question",         # Detected intent
    "memories": [...],            # Relevant memories
    "personality": "...",         # Personality guidance
    "suggested_responses": [...]  # Response suggestions
}
```

### detect_user_mood()

```python
mood = brain.detect_user_mood("I'm so excited about this!")
# Returns: {"mood": "happy", "confidence": 0.9, "emotions": ["joy", "anticipation"]}
```

### detect_user_intent()

```python
intent = brain.detect_user_intent("How does AI work?")
# Returns: "question"

intent = brain.detect_user_intent("Set a reminder for 3pm")
# Returns: "command"

intent = brain.detect_user_intent("I had a great day today")
# Returns: "casual"
```

---

## Example: Full Integration

```python
import sys
sys.path.insert(0, "ClawBrain")

from clawbrain import Brain

class JarvisBot:
    def __init__(self):
        self.brain = Brain()
    
    def handle_message(self, message, chat_id):
        # Get context
        context = self.brain.get_full_context(
            session_key=f"telegram_{chat_id}",
            user_id=str(chat_id),
            agent_id="jarvis",
            message=message
        )
        
        # Generate response using context
        response = self.generate_response(context)
        
        # Learn from interaction
        self.brain.learn_user_preference(
            user_id=str(chat_id),
            pref_type="interest",
            value="AI"
        )
        
        return response
    
    def generate_response(self, context):
        # Use user preferences
        name = context["user_profile"].name or "there"
        mood = context["mood"]["mood"]
        
        # Personalized response
        if mood == "frustrated":
            return f"Hey {name}, I'm here to help. Let me assist you."
        else:
            return f"Hi {name}! How can I help you today?"
    
    def shutdown(self):
        self.brain.close()
```

---

## Storage Backends

### SQLite (Default - Zero Setup)

No configuration needed. Data stored in local SQLite database.

```python
brain = Brain({"storage_backend": "sqlite"})
```

**Best for:** Development, testing, single-user deployments

### PostgreSQL + Redis (Production)

Requires PostgreSQL and Redis servers.

```python
brain = Brain()  # Auto-detects
```

**Requirements:**
- PostgreSQL 14+
- Redis 6+
- Python packages: `psycopg2-binary`, `redis`

```bash
pip install psycopg2-binary redis
```

**Best for:** Production, multi-user, high-concurrency

---

## Files

- `clawbrain.py` - Main Brain class with all features
- `__init__.py` - Module exports
- `SKILL.md` - This documentation
- `skill.json` - ClawdHub metadata
- `README.md` - Quick start guide

---

## Troubleshooting

### ImportError: No module named 'clawbrain'

```bash
# Ensure ClawBrain folder is in your path
sys.path.insert(0, "ClawBrain")
```

### PostgreSQL connection failed

```bash
# Check environment variables
echo $POSTGRES_HOST
echo $POSTGRES_PORT

# Verify PostgreSQL is running
pg_isready -h $POSTGRES_HOST -p $POSTGRES_PORT
```

### Redis connection failed

```bash
# Check Redis is running
redis-cli ping
```

### Using SQLite (fallback)

If PostgreSQL/Redis are unavailable, Claw Brain automatically falls back to SQLite:

```python
brain = Brain({"storage_backend": "sqlite"})
```

---

## Learn More

- **Repository:** https://github.com/clawcolab/clawbrain
- **README:** See README.md for quick start
- **Issues:** Report bugs at GitHub Issues