Plugin-based, MCP'able comms middleware for Letta agents.
A CLI-first, plugin-based message processing system for agent communication.
Sanctum: Broca 2 is a refactored version of Broca, focusing on:
Sanctum: Broca 2 serves as middleware designed to bridge the Letta Agentic Framework with various communication endpoints. Just as Broca's area in the human brain is responsible for language production and speech, Sanctum: Broca 2 acts as the "speech center" for AI systemsโtranslating agent intentions into actionable messages across different platforms.
In the AI brain, Sanctum: Broca 2 plays a crucial role by:
This middleware approach ensures that the Letta Agentic Framework can focus on decision-making and intelligence, while Sanctum: Broca 2 handles the complexities of communication and integration.
broca2/
โโโ main.py # Core runtime entry point
โโโ runtime/ # Core system components
โ โโโ core/ # Core functionality
โ โ โโโ agent.py # Agent API interaction
โ โ โโโ queue.py # Message queue processing
โ โ โโโ plugin.py # Plugin management
โ โ โโโ message.py # Message handling
โโโ cli/ # CLI tools
โ โโโ queue.py # Queue management
โ โโโ users.py # User management
โ โโโ conversations.py # Conversation tools
โ โโโ settings.py # Settings management
โโโ plugins/ # Platform plugins
โ โโโ telegram/ # Telegram plugin
โ โโโ cli/ # CLI plugin
โโโ common/ # Shared utilities
โโโ config.py # Configuration
โโโ logging.py # Logging setup
1. Clone the repository:
bash
git clone https://github.com/yourusername/broca-2.git
cd broca-2
2. Install dependencies:
bash
pip install -e .
3. Configure environment:
bash
cp .env.example .env
# Edit .env with your settings
bash
python -m broca2.main
bash
Queue management
broca-admin queue list
broca-admin queue flushUser management
broca-admin users listSettings
broca-admin settings set message_mode live
python
from plugins import Pluginclass MyPlugin(Plugin):
def get_name(self) -> str:
return "my_plugin"
def get_platform(self) -> str:
return "my_platform"
def get_message_handler(self) -> Callable:
return self._handle_message
async def start(self) -> None:
# Initialize plugin
async def stop(self) -> None:
# Cleanup plugin
get_name()
: Plugin identifierget_platform()
: Platform nameget_message_handler()
: Message handlerstart()
: Plugin initializationstop()
: Plugin cleanupSanctum: Broca 2 is built so that all CLI tools and plugin interfaces are MCP'able (machine-controllable by agents):
~/sanctum/
โโโ broca2/ # Base Broca 2 installation
โ โโโ main.py
โ โโโ runtime/
โ โโโ plugins/
โ โโโ ...
โโโ agent-721679f6-c8af-4e01-8677-dc042dc80368/ # Agent-specific instance
โ โโโ .env # Agent-specific environment
โ โโโ settings.json # Agent-specific settings
โ โโโ sanctum.db # Agent-specific database
โ โโโ logs/ # Agent-specific logs
โโโ agent-9a2b3c4d-5e6f-7890-abcd-ef1234567890/ # Another agent
โ โโโ .env
โ โโโ settings.json
โ โโโ sanctum.db
โ โโโ logs/
โโโ shared/ # Shared resources (optional)
โโโ templates/
โโโ configs/
1. Choose your master folder:
bash
# Typically your home directory or a dedicated user folder
mkdir ~/sanctum
cd ~/sanctum
2. Clone the base Broca 2 installation:
bash
git clone https://github.com/yourusername/broca-2.git broca2
cd broca2
pip install -e .
3. Create agent-specific instances:
bash
# For each Letta agent, create a folder named after the agent ID
mkdir ~/sanctum/agent-721679f6-c8af-4e01-8677-dc042dc80368
cd ~/sanctum/agent-721679f6-c8af-4e01-8677-dc042dc80368
# Copy base configuration
cp ~/sanctum/broca2/.env.example .env
cp ~/sanctum/broca2/settings.json .
# Edit agent-specific configuration
nano .env
# Set AGENT_ENDPOINT, AGENT_API_KEY, and other agent-specific settings
4. Run agent-specific instances:
bash
# From the agent folder
cd ~/sanctum/agent-721679f6-c8af-4e01-8677-dc042dc80368
python -m broca2.main
# Or use the CLI tools
broca-admin queue list
If you're using the Master Sanctum Provisioning Suite:
1. Configure the Sanctum home folder in your provisioning suite's .env
file
2. The suite will automatically:
- Git-clone Broca 2 into the proper folder structure
- Create agent-specific folders based on your agent configurations
- Set up the correct relative paths for all components
#### Starting Instances
bash
Start a specific agent's Broca instance
cd ~/sanctum/agent-721679f6-c8af-4e01-8677-dc042dc80368
python -m broca2.mainOr use a process manager like PM2
pm2 start "broca-agent-1" --interpreter python -- -m broca2.main
pm2 start "broca-agent-2" --interpreter python -- -m broca2.main
#### Configuration Management
bash
Each agent has its own configuration
~/sanctum/agent-721679f6-c8af-4e01-8677-dc042dc80368/.env
~/sanctum/agent-721679f6-c8af-4e01-8677-dc042dc80368/settings.jsonShared configurations can be symlinked or copied
ln -s ~/sanctum/shared/templates/telegram_config.json ~/sanctum/agent-*/telegram_config.json
#### Database Management
bash
Each agent has its own database
~/sanctum/agent-721679f6-c8af-4e01-8677-dc042dc80368/sanctum.dbBackup agent-specific databases
cp ~/sanctum/agent-*/sanctum.db ~/sanctum/backups/
#### Logging
bash
Each agent has its own logs
~/sanctum/agent-721679f6-c8af-4e01-8677-dc042dc80368/logs/Centralized logging (optional)
ln -s ~/sanctum/logs/ ~/sanctum/agent-*/logs