# Send Clawbrain to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- Download the package from Yavira.
- Extract it into a folder your agent can access.
- Paste one of the prompts below and point your agent at the extracted folder.
## Suggested prompts
### New install

```text
I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete.
```
### Upgrade existing

```text
I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "brain-v3-skill",
    "name": "Clawbrain",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/clawcolab/brain-v3-skill",
    "canonicalUrl": "https://clawhub.ai/clawcolab/brain-v3-skill",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/brain-v3-skill",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=clawbrain",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SECURITY.md",
      "SKILL.md"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "brain-v3-skill",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T12:47:34.782Z",
      "expiresAt": "2026-05-07T12:47:34.782Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=clawbrain",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=clawbrain",
        "contentDisposition": "attachment; filename=\"clawbrain-0.1.15.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "brain-v3-skill"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/brain-v3-skill"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/brain-v3-skill",
    "downloadUrl": "https://openagent3.xyz/downloads/brain-v3-skill",
    "agentUrl": "https://openagent3.xyz/skills/brain-v3-skill/agent",
    "manifestUrl": "https://openagent3.xyz/skills/brain-v3-skill/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/brain-v3-skill/agent.md"
  }
}
```
## Documentation

### 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 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 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 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 before installation, especially for production use.

### From PyPI (Recommended - Most Secure)

# 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:

Detect your platform (ClawdBot or OpenClaw)
Generate a secure encryption key
Install the startup hook automatically
Test the installation

### Alternative: From Source (Auditable)

# 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:

# 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:

# 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

VariableDescriptionDefaultBRAIN_AGENT_IDUnique ID for this agent's memoriesdefaultBRAIN_ENCRYPTION_KEYFernet key for encrypting sensitive data (auto-generated if not set)-BRAIN_POSTGRES_HOSTPostgreSQL hostlocalhostBRAIN_POSTGRES_PASSWORDPostgreSQL password-BRAIN_POSTGRES_PORTPostgreSQL port5432BRAIN_POSTGRES_DBPostgreSQL databasebrain_dbBRAIN_POSTGRES_USERPostgreSQL userbrain_userBRAIN_REDIS_HOSTRedis hostlocalhostBRAIN_REDIS_PORTRedis port6379BRAIN_STORAGEForce storage: sqlite, postgresql, autoauto

### On Service Startup

Hook triggers on gateway:startup event
Detects storage backend (SQLite/PostgreSQL)
Loads memories for the configured BRAIN_AGENT_ID
Injects context into agent bootstrap

### On /new Command

Hook triggers on command:new event
Saves current session summary to memory
Clears session state for fresh start

### Storage Priority

PostgreSQL - If available and configured
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:

# Run setup to generate encryption key
clawbrain setup

# Backup your key (IMPORTANT!)
clawbrain backup-key --all

Usage:

# 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:

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:

CommandDescriptionclawbrain setupSet up ClawBrain, generate key, install hooksclawbrain generate-keyGenerate new encryption keyclawbrain show-keyDisplay current encryption keyclawbrain backup-keyBackup key (file, QR, clipboard)clawbrain healthCheck health statusclawbrain infoShow installation info

### Hooks

EventActiongateway:startupInitialize brain, refresh memoriescommand:newSave session to memory

### Development Installation

For development or manual installation:

# 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):

from clawbrain import Brain

brain = Brain()

Methods

MethodDescriptionReturnsget_full_context()Get all context for personalized responsesdictremember()Store a memoryNonerecall()Retrieve memoriesList[Memory]learn_user_preference()Learn user preferencesNoneget_user_profile()Get user profileUserProfiledetect_user_mood()Detect current mooddictdetect_user_intent()Detect message intentstrgenerate_personality_prompt()Generate personality guidancestrhealth_check()Check backend connectionsdictclose()Close connectionsNone

### get_full_context()

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:

{
    "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()

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

### detect_user_intent()

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

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()

### SQLite (Default - Zero Setup)

No configuration needed. Data stored in local SQLite database.

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

Best for: Development, testing, single-user deployments

### PostgreSQL + Redis (Production)

Requires PostgreSQL and Redis servers.

brain = Brain()  # Auto-detects

Requirements:

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

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

### ImportError: No module named 'clawbrain'

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

### PostgreSQL connection failed

# Check environment variables
echo $POSTGRES_HOST
echo $POSTGRES_PORT

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

### Redis connection failed

# Check Redis is running
redis-cli ping

### Using SQLite (fallback)

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

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
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: clawcolab
- Version: 0.1.15
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-04-30T12:47:34.782Z
- Expires at: 2026-05-07T12:47:34.782Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/brain-v3-skill)
- [Send to Agent page](https://openagent3.xyz/skills/brain-v3-skill/agent)
- [JSON manifest](https://openagent3.xyz/skills/brain-v3-skill/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/brain-v3-skill/agent.md)
- [Download page](https://openagent3.xyz/downloads/brain-v3-skill)