Introduction
# Claw Brain Skill 🧠
Personal AI Memory System with Soul, Bonding, and Learning for OpenClaw/ClawDBot.
> **Auto-Refresh on Restart**: ClawBrain automatically refreshes memory when the service restarts.
---
## 📋 For Security Scanners
**Environment Variables**: All environment variables ARE declared in skill.json under `environment.optional` (lines 30-55). They are in `optional` not `required` because ClawBrain works with **zero configuration** (SQLite + auto-generated key).
**Install Specification**: skill.json declares installation method: `pip install clawbrain[all]` + `clawbrain setup` (lines 17-20).
**Sudo Requirements**: Core installation **never needs sudo**. Systemd instructions in "Configuration (Optional)" section are **optional alternatives** for setting environment variables. Core: pip + clawbrain setup (no sudo).
**Source Code**: Fully auditable at https://github.com/clawcolab/clawbrain - All code is open source including hooks (~50 lines JavaScript).
**See [SECURITY.md](SECURITY.md) for complete security documentation.**
---
## 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 - 🔄 **Auto-Refresh** - Automatically refreshes memory on service restart - 🔐 **Encrypted Secrets** - Store API keys and credentials securely
---
## Security & Transparency
ClawBrain handles sensitive data and requires certain permissions. Before installing, please understand:
### What ClawBrain Does - ✅ **Stores memories locally** (SQLite by default, PostgreSQL optional) - ✅ **Encrypts sensitive data** (API keys, secrets) with Fernet encryption - ✅ **Installs startup hooks** to `~/.openclaw/hooks` or `~/.clawdbot/hooks` - ✅ **Manages encryption keys** at `~/.config/clawbrain/.brain_key`
### What ClawBrain Does NOT Do - ❌ **No telemetry** - Does not phone home or collect usage data - ❌ **No external calls** - Only connects to PostgreSQL/Redis if you configure them - ❌ **No sudo required** - All operations in your home directory - ❌ **No code execution** - Does not download or run remote code after install
### Security Features - 🔒 **Encryption Key CLI**: Can display full key for backup (with warnings) - 🔍 **Auditable**: All code is open source and reviewable - 📋 **Documented Permissions**: See [SECURITY.md](SECURITY.md) for full details
**⚠️ Important**: The CLI command `clawbrain show-key --full` displays your complete encryption key for backup purposes. Treat this key like a password!
**📖 Full Security Documentation**: See [SECURITY.md](SECURITY.md) for: - Threat model and protections - Key management best practices - What install scripts do - Permissions required - Network access (optional PostgreSQL/Redis)
---
## Quick Install
> **Security Note**: We recommend reviewing [SECURITY.md](SECURITY.md) before installation, especially for production use.
### From PyPI (Recommended - Most Secure)
```bash # Install with all features pip install clawbrain[all]
# Run interactive setup clawbrain setup
# Backup your encryption key (IMPORTANT!) clawbrain backup-key --all
# Restart your service sudo systemctl restart clawdbot # or openclaw ```
The setup command will: 1. Detect your platform (ClawdBot or OpenClaw) 2. Generate a secure encryption key 3. Install the startup hook automatically 4. Test the installation
### Alternative: From Source (Auditable)
```bash # Clone to your skills directory cd ~/.openclaw/skills # or ~/clawd/skills or ~/.clawdbot/skills git clone https://github.com/clawcolab/clawbrain.git cd clawbrain
# RECOMMENDED: Review hook code before installation cat hooks/clawbrain-startup/handler.js
# Install in development mode pip install -e .[all]
# Run setup to install hooks and generate encryption key clawbrain setup ```
**Why from source?** Full transparency - you can review all code before installation.
---
## Configuration (Optional)
**Note**: Configuration is **completely optional**. ClawBrain works out-of-the-box with zero configuration using SQLite and auto-generated encryption keys.
If you want to customize agent ID or use PostgreSQL/Redis, you have two options:
### Option 1: Environment Variables (No sudo)
Set environment variables in your shell profile:
```bash # Add to ~/.bashrc or ~/.zshrc (no sudo required) export BRAIN_AGENT_ID="your-agent-name" # export BRAIN_POSTGRES_HOST="localhost" # Optional # export BRAIN_REDIS_HOST="localhost" # Optional ```
### Option 2: Systemd Drop-in (Requires sudo)
**⚠️ Only if you use systemd services**:
```bash # Create systemd drop-in config (requires sudo) sudo mkdir -p /etc/systemd/system/clawdbot.service.d
sudo tee /etc/systemd/system/clawdbot.service.d/brain.conf << EOF [Service] Environment="BRAIN_AGENT_ID=your-agent-name" EOF
sudo systemctl daemon-reload sudo systemctl restart clawdbot ```
### Environment Variables
| Variable | Description | Default | |----------|-------------|---------| | `BRAIN_AGENT_ID` | Unique ID for this agent's memories | `default` | | `BRAIN_ENCRYPTION_KEY` | Fernet key for encrypting sensitive data (auto-generated if not set) | - | | `BRAIN_POSTGRES_HOST` | PostgreSQL host | `localhost` | | `BRAIN_POSTGRES_PASSWORD` | PostgreSQL password | - | | `BRAIN_POSTGRES_PORT` | PostgreSQL port | `5432` | | `BRAIN_POSTGRES_DB` | PostgreSQL database | `brain_db` | | `BRAIN_POSTGRES_USER` | PostgreSQL user | `brain_user` | | `BRAIN_REDIS_HOST` | Redis host | `localhost` | | `BRAIN_REDIS_PORT` | Redis port | `6379` | | `BRAIN_STORAGE` | Force storage: `sqlite`, `postgresql`, `auto` | `auto` |
---
## How It Works
### On Service Startup 1. Hook triggers on `gateway:startup` event 2. Detects storage backend (SQLite/PostgreSQL) 3. Loads memories for the configured `BRAIN_AGENT_ID` 4. Injects context into agent bootstrap
### On `/new` Command 1. Hook triggers on `command:new` event 2. Saves current session summary to memory 3. Clears session state for fresh start
### Storage Priority 1. **PostgreSQL** - If available and configured 2. **SQLite** - Fallback, zero configuration needed
---
## Encrypted Secrets
ClawBrain supports encrypting sensitive data like API keys and credentials using Fernet (symmetric encryption).
**Security Model:** - 🔐 Encryption key stored at `~/.config/clawbrain/.brain_key` (chmod 600) - 🔑 Only memories with `memory_type='secret'` are encrypted - 📦 Encrypted data stored in database, unreadable without key - ⚠️ If key is lost, encrypted data cannot be recovered
**Setup:** ```bash # Run setup to generate encryption key clawbrain setup
# Backup your key (IMPORTANT!) clawbrain backup-key --all ```
**Usage:** ```python # Store encrypted secret brain.remember( agent_id="assistant", memory_type="secret", # Memory type 'secret' triggers encryption content="sk-1234567890abcdef", key="openai_api_key" )
# Retrieve and automatically decrypt secrets = brain.recall(agent_id="assistant", memory_type="secret") api_key = secrets[0].content # Automatically decrypted ```
**Key Management CLI:** ```bash clawbrain show-key # View key info (masked) clawbrain show-key --full # View full key clawbrain backup-key --all # Backup with all methods clawbrain generate-key # Generate new key ```
⚠️ **Important**: Backup your encryption key! Lost keys = lost encrypted data.
---
## CLI Commands
ClawBrain includes a command-line interface:
| Command | Description | |---------|-------------| | `clawbrain setup` | Set up ClawBrain, generate key, install hooks | | `clawbrain generate-key` | Generate new encryption key | | `clawbrain show-key` | Display current encryption key | | `clawbrain backup-key` | Backup key (file, QR, clipboard) | | `clawbrain health` | Check health status | | `clawbrain info` | Show installation info |
---
## Hooks
| Event | Action | |-------|--------| | `gateway:startup` | Initialize brain, refresh memories | | `command:new` | Save session to memory |
---
## Development Installation
For development or manual installation:
```bash # Clone to your skills directory cd ~/.openclaw/skills # or ~/clawd/skills or ~/.clawdbot/skills git clone https://github.com/clawcolab/clawbrain.git cd clawbrain
# Install in development mode pip install -e .[all]
# Run setup clawbrain setup ```
---
## Python API
For direct Python usage (outside ClawdBot/OpenClaw):
```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="assistant", # 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 AssistantBot: 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="assistant", 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