Claw Brain 🧠

Personal AI Memory System for AI Agents

A sophisticated memory and learning system that enables truly personalized AI-human communication.

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
• 🔐 Encrypted Secrets - Securely store API keys and credentials

Security

ClawBrain handles sensitive data responsibly:

• ✅ Local-only storage (SQLite by default)
• ✅ Fernet encryption for secrets
• ✅ No telemetry or external calls
• ✅ Auditable open-source code

📖 Full security documentation: See SECURITY.md for details on:

• What permissions are required
• Key management best practices
• What install scripts do
• Threat model and protections

Installation

From PyPI (Recommended)

# Basic installation
pip install clawbrain

# With encryption support (recommended)
pip install clawbrain[encryption]

# With all optional features
pip install clawbrain[all]

Post-Installation Setup

After installation, run the setup command:

# Interactive setup (generates encryption key, installs hooks)
clawbrain setup

# Backup your encryption key (important!)
clawbrain backup-key --all

For ClawdBot / OpenClaw

# Install with all features
pip install clawbrain[all]

# Run setup to install hooks
clawbrain setup

# Restart your service
sudo systemctl restart clawdbot  # or openclaw

The setup command will:

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

Configure your agent ID (optional, add to systemd service):

sudo mkdir -p /etc/systemd/system/clawdbot.service.d  # or openclaw.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  # or openclaw

For Python Projects

pip install clawbrain[encryption]

Quick Start

pip install clawbrain[encryption]

from clawbrain import Brain

brain = Brain()
context = brain.get_full_context(
    session_key="chat_123",
    user_id="user",
    agent_id="assistant",
    message="Hey, how's it going?"
)

Storage Options

Option 1: SQLite (Zero Setup) ✅ Recommended for development

from clawbrain import Brain

# Automatically uses SQLite
brain = Brain({"storage_backend": "sqlite"})

Requirements: Python 3.10+, no external dependencies

Best for:

• Development and testing
• Single-user deployments
• Quick prototyping

Option 2: PostgreSQL + Redis (Production) 🚀

from clawbrain import Brain

# Auto-detects PostgreSQL and Redis
brain = Brain()

Requirements:

• PostgreSQL 14+ (port 5432)
• Redis 6+ (port 6379)
• Python packages: psycopg2-binary, redis

Install dependencies:

pip install psycopg2-binary redis

Environment variables (optional):

export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export POSTGRES_DB=brain_db
export POSTGRES_USER=brain_user
export POSTGRES_PASSWORD=your_password

export REDIS_HOST=localhost
export REDIS_PORT=6379

Best for:

• Production deployments
• High-concurrency environments
• Distributed AI agents
• Multi-user platforms

Auto-Detection Order

1. PostgreSQL (if available)
2. Redis (if available, used as cache)
3. SQLite (fallback)

You can also force a specific backend:

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

Encrypted Secrets 🔐

ClawBrain supports encrypting sensitive data like API keys and credentials.

Installation:

pip install clawbrain[encryption]

Setup:

# Generate encryption key (done automatically during setup)
clawbrain setup

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

Usage:

from clawbrain import Brain

brain = Brain()

# 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

Encryption Key Management:

The encryption key is automatically generated during clawbrain setup. Manage it with CLI:

# View key info (masked)
clawbrain show-key

# View full key
clawbrain show-key --full

# Backup key to file
clawbrain backup-key --output ~/my_backup.txt

# Backup with QR code (requires: pip install clawbrain[qr])
clawbrain backup-key --qr

# Copy to clipboard (requires: pip install clawbrain[clipboard])
clawbrain backup-key --clipboard

# All backup methods
clawbrain backup-key --all

Key Storage Locations:

• ~/.config/clawbrain/.brain_key (default)
• Or set via environment: BRAIN_ENCRYPTION_KEY

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

CLI Commands

ClawBrain includes a command-line interface for setup and management:

# Setup ClawBrain (generate key, install hooks)
clawbrain setup

# Generate new encryption key
clawbrain generate-key

# Show current encryption key
clawbrain show-key --full

# Backup encryption key
clawbrain backup-key --all

# Check health status
clawbrain health

# Show installation info
clawbrain info

Optional Dependencies

Install with specific features:

# Encryption only
pip install clawbrain[encryption]

# PostgreSQL support
pip install clawbrain[postgres]

# Redis caching
pip install clawbrain[redis]

# Semantic search
pip install clawbrain[embeddings]

# QR code key backup
pip install clawbrain[qr]

# All features
pip install clawbrain[all]

Development Installation

From GitHub

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

From Local Development

cd /path/to/clawbrain
pip install -e .

For ClawDBot

# Install as skill
git clone https://github.com/clawcolab/clawbrain.git ClawBrain

Then in your bot:

import sys
sys.path.insert(0, "ClawBrain")
from clawbrain import Brain

brain = Brain()

API Reference

Core Class

from clawbrain import Brain

brain = Brain()

Methods:

Data Classes

from clawbrain import Memory, UserProfile

# Memory
memory = Memory(
    id="...",
    agent_id="assistant",
    memory_type="fact",
    key="job",
    content="User works at Walmart",
    importance=0.8
)

# User Profile
profile = UserProfile(
    user_id="user",
    name="Alex",
    interests=["AI", "crypto"],
    communication_preferences={"style": "casual"}
)

Repository Structure

clawbrain/
├── clawbrain.py      ← Main module
├── __init__.py       ← Exports
├── SKILL.md          ← ClawDBot skill docs
├── skill.json        ← ClawdHub metadata
└── README.md         ← This file

For ClawDBot

Install as a skill via ClawdHub or manually:

git clone https://github.com/clawcolab/clawbrain.git ClawBrain

Usage in your bot:

import sys
sys.path.insert(0, "ClawBrain")
from clawbrain import Brain

brain = Brain()

# Get context for responses
context = brain.get_full_context(
    session_key=session_id,
    user_id=user_id,
    agent_id=agent_id,
    message=user_message
)

License

MIT