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
• 🧠 getfullcontext() - 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 INLINECODE6
• ✅ Manages encryption keys at INLINECODE7

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)

CODEBLOCK0

The setup command will:

1. 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)

CODEBLOCK1

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:

CODEBLOCK2

Option 2: Systemd Drop-in (Requires sudo)

⚠️ Only if you use systemd services:

CODEBLOCK3

Environment Variables

How It Works

On Service Startup

1. 1. Hook triggers on gateway:startup event
2. Detects storage backend (SQLite/PostgreSQL)
3. Loads memories for the configured INLINECODE31
4. Injects context into agent bootstrap

On /new Command

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

Storage Priority

1. 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:
CODEBLOCK4

Usage:
CODEBLOCK5

Key Management CLI:
CODEBLOCK6

⚠️ Important: Backup your encryption key! Lost keys = lost encrypted data.

CLI Commands

ClawBrain includes a command-line interface:

Hooks

Development Installation

For development or manual installation:

CODEBLOCK7

Python API

For direct Python usage (outside ClawdBot/OpenClaw):

CODEBLOCK8

Methods

getfullcontext()

CODEBLOCK9

Returns:
CODEBLOCK10

detectusermood()

CODEBLOCK11

detectuserintent()

CODEBLOCK12

Example: Full Integration

CODEBLOCK13

Storage Backends

SQLite (Default - Zero Setup)

No configuration needed. Data stored in local SQLite database.

CODEBLOCK14

Best for: Development, testing, single-user deployments

PostgreSQL + Redis (Production)

Requires PostgreSQL and Redis servers.

CODEBLOCK15

Requirements:

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

CODEBLOCK16

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

Files

• - clawbrain.py - Main Brain class with all features
• INLINECODE57 - Module exports
• INLINECODE58 - This documentation
• INLINECODE59 - ClawdHub metadata
• INLINECODE60 - Quick start guide

Troubleshooting

ImportError: No module named 'clawbrain'

CODEBLOCK17

PostgreSQL connection failed

CODEBLOCK18

Redis connection failed

CODEBLOCK19

Using SQLite (fallback)

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

CODEBLOCK20

Learn More

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