Broca-2

Message Processing Middleware for AI Agent Communication

Broca-2 is the communication hub of SanctumOS, serving as middleware that bridges AI agents with various platforms and endpoints. Just as Broca's area in the human brain is responsible for language production and speech, Broca-2 acts as the "speech center" for AI systems—translating agent intentions into actionable messages across different platforms.

🎯 What is this for?

Broca-2 is a CLI-first, plugin-based message processing system that:

• Bridges AI agents with multiple communication platforms (Telegram, web, CLI)
• Processes messages through a reliable queue system
• Manages multiple agents with complete isolation
• Provides CLI tools for automation and agent management

🚀 Quick Installation

Prerequisites

• Python 3.8 or higher
• Git
• Access to Letta agent endpoints

Install & Run

# Clone and setup
git clone https://github.com/sanctumos/broca.git
cd broca
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run Broca-2
python main.py

Clone and setup

git clone https://github.com/sanctumos/broca.git cd broca python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt

Run Broca-2

python main.py

### Verify Installation
bash
# Check if Broca-2 is running
python cli/status.py

# List available plugins
python cli/plugins.py --list

# Clone and setup
git clone https://github.com/sanctumos/broca.git
cd broca
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run Broca-2
python main.py

### Verify Installation
bash
# Check if Broca-2 is running
python cli/status.py

# List available plugins
python cli/plugins.py --list

⚙️ Basic Configuration

Environment Variables

# Clone and setup
git clone https://github.com/sanctumos/broca.git
cd broca
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run Broca-2
python main.py

Agent settings

LETTA_ENDPOINT=http://localhost:8000 AGENT_ID=your-agent-id AGENT_TOKEN=your-agent-token

Message processing

QUEUE_MODE=live # echo, listen, or live MAX_RETRIES=3 RETRY_DELAY=5

Plugin settings

TELEGRAM_BOT_TOKEN=your-bot-token TELEGRAM_CHAT_ID=your-chat-id

### Verify Installation
bash
# Check if Broca-2 is running
python cli/status.py

# List available plugins
python cli/plugins.py --list

### Verify Installation
bash
# Check if Broca-2 is running
python cli/status.py

# List available plugins
python cli/plugins.py --list

~/sanctum/ ├── venv/ # Shared virtual environment ├── agent-{uuid}/ # Individual agent instances │ ├── broca/ # Complete Broca installation │ ├── .env # Agent-specific configuration │ ├── settings.json # Agent-specific settings │ └── sanctum.db # Agent-specific database └── shared-tools/ # Shared Sanctum tools

### Verify Installation
bash
# Check if Broca-2 is running
python cli/status.py

# List available plugins
python cli/plugins.py --list

# Clone and setup
git clone https://github.com/sanctumos/broca.git
cd broca
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run Broca-2
python main.py

### Verify Installation
bash
# Check if Broca-2 is running
python cli/status.py

# List available plugins
python cli/plugins.py --list

Message Processing

# Clone and setup
git clone https://github.com/sanctumos/broca.git
cd broca
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run Broca-2
python main.py

Process messages (echo mode)

python main.py --mode echo

Process messages (live mode)

python main.py --mode live

Check message queue

python cli/queue.py --status

### Verify Installation
bash
# Check if Broca-2 is running
python cli/status.py

# List available plugins
python cli/plugins.py --list

# Clone and setup
git clone https://github.com/sanctumos/broca.git
cd broca
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Run Broca-2
python main.py

### Verify Installation
bash
# Check if Broca-2 is running
python cli/status.py

# List available plugins
python cli/plugins.py --list

📚 Documentation Links

Core Documentation

• Installation Instructions - Detailed installation from the repository
• Configuration Reference - Complete configuration options
• Multi-Agent Setup - Running multiple agents
• Message Processing - Understanding the queue system

Plugin Development

• Plugin Development - Creating custom plugins
• Plugin Examples - Sample implementations
• Plugin API - Development API reference

Integration

• Telegram Integration - Telegram bot setup
• Web Chat Integration - Web interface setup
• Letta Integration - Using with Letta agents
• Troubleshooting - Common issues and solutions

🔧 Common Tasks

Setting Up a New Agent

1. Create agent directory: mkdir ~/sanctum/agent-{uuid}
2. Clone Broca-2: git clone https://github.com/sanctumos/broca.git
3. Configure environment: Set up .env file
4. Start agent: python main.py --agent-id {uuid}

Adding a New Plugin

1. Create plugin directory in plugins/
2. Implement plugin interface
3. Register with plugin manager
4. Enable plugin: python cli/plugins.py --enable your-plugin

Monitoring Agent Health

• Status Check: python cli/status.py
• Queue Status: python cli/queue.py --status
• Plugin Status: python cli/plugins.py --list
• Logs: Check logs/ directory

🆘 Getting Help

• GitHub Issues: Report bugs and request features
• Documentation: Complete Broca-2 documentation
• Community: Join our Discord

📄 License

• Code: AGPLv3 - GNU Affero General Public License v3.0
• Documentation: CC-BY-SA 4.0 - Creative Commons Attribution-ShareAlike 4.0

Broca-2 - The communication hub of SanctumOS.