Broca 3

Message Processing Middleware for AI Agent Communication

Broca 3 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 3 acts as the "speech center" for AI systems — translating agent intentions into actionable messages across different platforms.

What is this for?

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

Bridges AI agents with multiple communication platforms (Telegram, web, CLI, local spool/bridge)
Processes messages through a reliable SQLite-backed queue with atomic dequeue and retry
Manages multiple agents with complete isolation (separate repo clone, DB, config, logs per agent)
Handles images end-to-end — download, upload to tmpfiles, and attach to agent messages with automatic fallback on tool-call failures
Provides CLI tools for automation and agent management — designed to be MCP'able (machine-controllable by agents)

What's new in Broca 3

Broca 3 is a major release that finalizes all work since v0.11.0, including full compatibility with the Letta client v1.0+ breaking changes.

Highlights

Letta client v1.0+ compliance — all SDK calls updated for the breaking v1.0 release; identity creation via direct HTTP where SDK gaps exist
Image handling pipeline — Telegram photo ingress, tmpfiles upload, [Image Attachment: url] formatting, and automatic retry without images on tool-call failure
Streaming with long-running tasks — background=True, include_pings=True for robust async agent interaction
Circuit breaker and exponential backoff — production-grade retry for Letta API and database operations
1080 passing tests — unit, integration, and e2e coverage across image flow, streaming, queue, plugins, CLI, and database
Pydantic v2 migration for all configuration models
Graceful shutdown with async signal handlers and PID file hygiene
Ruff + Black code style enforcement with pre-commit hooks

Quick Installation

Prerequisites

Python 3.8 or higher
Git
Access to Letta agent endpoints

Install & Run

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

# Configure
cp .env.example .env
# Edit .env with your agent endpoint, API key, Telegram token, etc.

# Run
python main.py

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

Configure

cp .env.example .env

Edit .env with your agent endpoint, API key, Telegram token, etc.

Run

python main.py


## Configuration

### Environment Variables
bash
# Agent settings
LETTA_ENDPOINT=http://localhost:8000
AGENT_ID=your-agent-id
LETTA_API_KEY=your-api-key

# Message processing
MESSAGE_MODE=live  # echo, listen, or live

# Image handling (new in v3)
ENABLE_IMAGE_HANDLING=true
ENABLE_TMPFILES_IMAGE_ADDENDUM=true

# Telegram plugin
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_OWNER_ID=your-telegram-id


Configuration
Environment Variables
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

# Configure
cp .env.example .env
# Edit .env with your agent endpoint, API key, Telegram token, etc.

# Run
python main.py
Agent settings
LETTA_ENDPOINT=http://localhost:8000 AGENT_ID=your-agent-id LETTA_API_KEY=your-api-key
Message processing
MESSAGE_MODE=live  # echo, listen, or live
Image handling (new in v3)
ENABLE_IMAGE_HANDLING=true ENABLE_TMPFILES_IMAGE_ADDENDUM=true
Telegram plugin
TELEGRAM_BOT_TOKEN=your-bot-token TELEGRAM_OWNER_ID=your-telegram-id


## Configuration

### Environment Variables
bash
# Agent settings
LETTA_ENDPOINT=http://localhost:8000
AGENT_ID=your-agent-id
LETTA_API_KEY=your-api-key

# Message processing
MESSAGE_MODE=live  # echo, listen, or live

# Image handling (new in v3)
ENABLE_IMAGE_HANDLING=true
ENABLE_TMPFILES_IMAGE_ADDENDUM=true

# Telegram plugin
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_OWNER_ID=your-telegram-id

Multi-Agent Setup


## Configuration

### Environment Variables
bash
# Agent settings
LETTA_ENDPOINT=http://localhost:8000
AGENT_ID=your-agent-id
LETTA_API_KEY=your-api-key

# Message processing
MESSAGE_MODE=live  # echo, listen, or live

# Image handling (new in v3)
ENABLE_IMAGE_HANDLING=true
ENABLE_TMPFILES_IMAGE_ADDENDUM=true

# Telegram plugin
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_OWNER_ID=your-telegram-id


~/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


## Configuration

### Environment Variables
bash
# Agent settings
LETTA_ENDPOINT=http://localhost:8000
AGENT_ID=your-agent-id
LETTA_API_KEY=your-api-key

# Message processing
MESSAGE_MODE=live  # echo, listen, or live

# Image handling (new in v3)
ENABLE_IMAGE_HANDLING=true
ENABLE_TMPFILES_IMAGE_ADDENDUM=true

# Telegram plugin
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_OWNER_ID=your-telegram-id

Each agent gets its own isolated Broca repo clone, database, configuration, and logs. Only the virtual environment is shared.

Available Plugins

Built-in Plugins

Telegram Bot Plugin — full Telegram bot integration with photo support via aiogram
Otto Bridge Plugin — file-spool ingress/outbox for local agent-to-agent messaging (used by the broca-otto-bridge)
Web Chat Plugin — polling-based web chat integration
CLI Plugin — command-line interface and diagnostic tools

Plugin Development

Plugins implement the Plugin abstract base class and are auto-discovered from the plugins/ directory. See the repository docs for the full development guide.

CLI Tools

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

# Configure
cp .env.example .env
# Edit .env with your agent endpoint, API key, Telegram token, etc.

# Run
python main.py

Queue management

python -m cli.qtool status python -m cli.qtool list --pending

User management

python -m cli.utool list python -m cli.utool details --user-id 1

Configuration

python -m cli.ctool show python -m cli.ctool set plugins.telegram_bot.enabled true

System

python -m cli.btool status


## Configuration

### Environment Variables
`bash
# Agent settings
LETTA_ENDPOINT=http://localhost:8000
AGENT_ID=your-agent-id
LETTA_API_KEY=your-api-key

# Message processing
MESSAGE_MODE=live  # echo, listen, or live

# Image handling (new in v3)
ENABLE_IMAGE_HANDLING=true
ENABLE_TMPFILES_IMAGE_ADDENDUM=true

# Telegram plugin
TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_OWNER_ID=your-telegram-id

Documentation Links

Core Documentation

Repository & Source — full source, README, and developer docs
Troubleshooting — common issues and solutions

Related Modules

Sanctum Web Chat — web interface bridge (uses Broca's web chat plugin)
Sanctum Letta MCP — MCP server for tool access
SMCP Plugins — the MCP plugin ecosystem

License

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

Broca 3 — The communication hub of SanctumOS.