ClawBrain is a personal AI memory system that handles sensitive data including encrypted secrets, API keys, and user preferences. This document explains our security model, what permissions are required, and how to use ClawBrain safely.

1. Stores Memories: Conversations, preferences, and learning insights in SQLite or PostgreSQL
2. Manages Encryption Keys: Generates and stores a Fernet encryption key for securing sensitive data
3. Installs Hooks: Adds startup hooks to ClawdBot/OpenClaw for automatic memory refresh
4. Optional Network Access: Connects to PostgreSQL/Redis if configured (disabled by default)

• No Telemetry: Does not phone home or send usage data anywhere
• No External APIs: Does not make network calls except to configured PostgreSQL/Redis backends
• No Code Execution: Does not download or execute remote code after installation

Core installation and operation never require root privileges:

✅ Without sudo:

• pip install clawbrain[all] - Package installation
• clawbrain setup - Generates key, installs hooks to ~/.openclaw/hooks
• All operations in user's home directory
• Default SQLite storage
• Auto-generated encryption key at ~/.config/clawbrain/.brain_key

⚠️ Sudo only needed for optional systemd configuration:

• Setting environment variables via systemd drop-ins (/etc/systemd/system/)
• Alternative: Use shell environment variables instead (no sudo)
• Not required: ClawBrain works with zero configuration

If you see sudo in documentation, it's only for optional systemd env var configuration, not core functionality.

We recommend these installation methods in order of security:

1. PyPI (Recommended)

   pip install clawbrain[all]
   clawbrain setup

   • Downloads from official PyPI with checksums
   • No shell script execution
   • Standard Python package installation
   • CLI-based setup (no bash scripts)

2. Git Clone (Auditable)

   git clone https://github.com/clawcolab/clawbrain.git
   cd clawbrain
   pip install -e .[all]
   clawbrain setup

   • Full source code available for review
   • No remote downloads during install
   • Same CLI-based setup as PyPI

The clawbrain setup command performs these actions:

1. Detects your platform (OpenClaw or ClawdBot)
2. Generates encryption key at ~/.config/clawbrain/.brain_key
3. Copies hook files to ~/.openclaw/hooks or ~/.clawdbot/hooks
4. Tests the installation with a health check
5. Does NOT:
   • Require sudo or root access
   • Modify system files outside your home directory
   • Download additional code from the internet
   • Execute shell commands or privileged operations

• Location: ~/.config/clawbrain/.brain_key
• Format: Fernet encryption key (44 bytes, base64-encoded)
• Permissions: Should be readable only by your user (chmod 600)
• Auto-generated: Created on first use if not present

The CLI provides commands to manage your encryption key:

clawbrain show-key          # Shows masked key (safe)
clawbrain show-key --full   # Shows full key (⚠️  SENSITIVE!)
clawbrain backup-key --all  # Backup key to file/QR/clipboard

⚠️ SECURITY WARNING: The show-key --full command displays your complete encryption key. This is intentional for backup purposes, but:

• Only run this command when you need to backup/migrate keys
• Never share your key in screenshots, logs, or public channels
• Treat your encryption key like a password
• If compromised, generate a new key and re-encrypt your data

1. Immediately after setup:

   clawbrain backup-key --file ~/clawbrain-key-backup.txt

   Store this file in a secure location (password manager, encrypted drive)

2. For offline backup:

   clawbrain backup-key --qr

   Print or save the QR code in a secure physical location

3. Never:

   • Commit .brain_key to git (already in .gitignore)
   • Share your key over unencrypted channels
   • Store your key in the same database as encrypted data

• Read: Configuration files, hooks directory, database files
• Write:
  • ~/.config/clawbrain/ (config and key storage)
  • ~/.openclaw/hooks/ or ~/.clawdbot/hooks/ (hook installation)
  • ./brain_data.db or custom path (SQLite database)

ClawBrain only makes network connections if you explicitly configure them:

• PostgreSQL: Only if BRAIN_POSTGRES_HOST is set
• Redis: Only if BRAIN_REDIS_HOST is set
• No other network access: No telemetry, no external APIs, no updates

ClawBrain reads these environment variables (all optional - works with zero config):

How to Set (choose one):

1. Shell environment (no sudo): Add to ~/.bashrc or ~/.zshrc
2. Systemd drop-in (requires sudo): Create /etc/systemd/system/{service}.service.d/brain.conf
3. Don't set anything: ClawBrain works with defaults (SQLite + auto-generated key)

On gateway:startup event:

1. Calls Brain.refresh_on_startup(agent_id) via Python bridge
2. Loads memories and personality for the configured agent
3. Logs startup context to ClawdBot/OpenClaw

On command:new event:

1. Saves current session summary to memory
2. Clears session state

• Source: hooks/clawbrain-startup/handler.js
• Installed to: ~/.openclaw/hooks/clawbrain-startup/ or ~/.clawdbot/hooks/clawbrain-startup/
• Review before installing: The hook code is ~50 lines and fully auditable

If you want to use ClawBrain without automatic startup:

# Remove the hook
rm -rf ~/.openclaw/hooks/clawbrain-startup

# Or disable events in skill.json
# Set "events": [] instead of ["gateway:startup", "command:new"]

ClawBrain will still work via direct API calls in Python.

• Location: ./brain_data.db (current directory) or $CLAWBRAIN_DB_PATH
• Encryption: Secrets encrypted with Fernet, rest in plaintext SQLite
• Permissions: Should be readable only by your user
• Backup: Standard SQLite backup procedures

• Connection: Via BRAIN_POSTGRES_HOST environment variable
• Encryption: Same as SQLite (Fernet for secrets, database-level encryption optional)
• Network: Connections use standard PostgreSQL protocol (can use SSL/TLS)

✅ Encrypted at Rest: Secrets in database are Fernet-encrypted ✅ Local-Only by Default: No network access unless configured ✅ No Code Execution: Cannot execute arbitrary code from memory ✅ User Isolation: Each agent has separate memory space

❌ Root Access: If attacker has root, they can read the key file ❌ Memory Dumps: Decrypted secrets exist in RAM during use ❌ Database Access: If attacker can read DB and key file, they can decrypt ❌ Compromised Python Environment: Malicious code can access Brain API

1. System Hardening:

   • Run ClawdBot/OpenClaw as dedicated user with minimal privileges
   • Use full disk encryption (LUKS, FileVault, BitLocker)
   • Restrict file permissions: chmod 600 ~/.config/clawbrain/.brain_key

2. Network Isolation:

   • Run PostgreSQL on localhost or private network
   • Use TLS for PostgreSQL connections
   • Firewall Redis to localhost only

3. Key Management:

   • Consider external key management (Vault, KMS)
   • Rotate encryption keys periodically
   • Never commit keys to version control

4. Monitoring:

   • Log access to encryption key file
   • Monitor for unusual database access patterns
   • Alert on hook modifications

If you discover a security vulnerability in ClawBrain:

1. DO NOT open a public GitHub issue
2. Email: security@clawcolab.com (if available) or use GitHub Security Advisories
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

We will acknowledge within 48 hours and provide a fix timeline.

Before using ClawBrain in production:

• Review install.sh and hook code before installation
• Verify package checksums from PyPI
• Backup encryption key to secure offline storage
• Set file permissions: chmod 600 ~/.config/clawbrain/.brain_key
• Use systemd drop-ins for environment variables (not shell rc files)
• Review what data will be stored (see Data Storage section)
• Test in isolated environment first
• Understand that CLI can display full encryption key
• Configure PostgreSQL/Redis with TLS if using over network
• Document your key backup and recovery procedure

✅ Correct: All env vars are optional. ClawBrain works with zero configuration (SQLite + auto-generated key).

✅ Correct and Intentional: clawbrain show-key --full is for backup/recovery. Users should understand this is sensitive and treat it like a password.

✅ Correct: Required for automatic memory refresh. Hook code is auditable and can be disabled.

✅ Fixed: skill.json now declares all optional env vars and includes explicit security metadata.

⚠️ Warning Valid: remote-install.sh downloads code from GitHub. We recommend pip or git clone for production. Remote install includes security warnings and confirmation prompts.

ClawBrain is designed for personal AI memory with reasonable security defaults:

• Local-only storage by default
• Encryption for sensitive data
• No telemetry or external calls
• Auditable installation

However, it requires certain privileges (file access, hooks, key management) to function. Users should:

1. Review code before installation
2. Understand what permissions are granted
3. Follow security best practices for key management
4. Use appropriate isolation for production deployments

For questions or concerns, see our GitHub Issues or contact the maintainers.