What is Broca 2

Sanctum: Broca 2 is a refactored middleware message processing system designed for agent communication, featuring a CLI-first architecture and a plugin-based framework for extensible message handling. It serves to bridge the Letta Agentic Framework with various communication endpoints, translating high-level agent intentions into actionable messages across platforms.

Use cases

Sanctum: Broca 2 can be utilized in various scenarios, including integrating AI agents with different messaging platforms like Telegram and command-line interfaces. Its extensible plugin system allows for seamless integration of new endpoints and adapts to different communication requirements, while CLI tools facilitate administration and debugging.

How to use

To use Sanctum: Broca 2, clone the repository, install dependencies, and configure environment variables. The server can be run using a command, and standard CLI tools are available for managing queues, users, and settings. Plugins integrate automatically upon server launch, with specific commands available for each plugin.

Key features

Key features of Sanctum: Broca 2 include versatile message processing modes (Echo, Listen, Live), a robust plugin system for platform-specific message handling, comprehensive CLI tools for administration, and MCP readiness for integration into agent networks or orchestration systems. It incorporates error handling and event routing.

Where to use

Sanctum: Broca 2 is suitable for environments requiring agent communication across diverse platforms, such as customer support systems, automation tools, and AI-driven applications. It can be deployed in both standalone scenarios and as part of larger multi-agent architectures within enterprise systems.

Sanctum: Broca 2 (v0.9.0)

A CLI-first, plugin-based message processing system for agent communication.

🚀 Overview

Sanctum: Broca 2 is a refactored version of Broca, focusing on:

• CLI-first architecture for better control and automation
• Plugin-based system for extensible message handling
• Clean separation between core and platform-specific code
• Improved maintainability and testing capabilities

Broca: The Middleware Bridge

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:

• Translating Agent Intentions: Converting high-level agent decisions into platform-specific messages.
• Unifying Communication: Providing a standardized interface for different endpoints (Telegram, CLI, APIs, etc.).
• Enabling Extensibility: Allowing new endpoints to be integrated seamlessly through the plugin system.

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.

🏗️ Architecture

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

🔧 Core Components

Runtime

• Application: Main coordinator
• QueueProcessor: Message queue handling
• AgentClient: Agent API interaction
• PluginManager: Plugin lifecycle management

CLI Tools

• Queue Management: List, flush, delete messages
• User Management: List and manage users
• Conversation Tools: View and manage conversations
• Settings: Configure system behavior

Plugins

• Telegram Plugin: Telegram message handling
• CLI Plugin: Diagnostic/testing interface

🎯 Features

Message Processing

• Multiple processing modes:
  • Echo: Direct message return
  • Listen: Store without processing
  • Live: Process through agent
• Core block management
• Error handling and recovery

Plugin System

• Standardized plugin interface
• Platform-specific message handling
• Event routing
• Settings management per plugin

CLI Interface

• Comprehensive admin tools
• Diagnostic capabilities
• Settings management
• Queue operations

🛠️ Installation

1. Clone the repository:

   git clone https://github.com/yourusername/broca-2.git
   cd broca-2
   

2. Install dependencies:

   pip install -e .
   

3. Configure environment:

   cp .env.example .env
   # Edit .env with your settings
   

🚦 Usage

Running the Server

python -m broca2.main

CLI Tools

# Queue management
broca-admin queue list
broca-admin queue flush

# User management
broca-admin users list

# Settings
broca-admin settings set message_mode live

Plugins

• Telegram plugin runs as part of the server
• CLI plugin is a standalone diagnostic tool

📝 Configuration

Settings

• Message processing mode
• Queue refresh interval
• Debug mode
• Plugin-specific settings

Environment Variables

• Agent API credentials
• Database configuration
• Plugin-specific settings

🔌 Plugin Development

Plugin Structure

from plugins import Plugin

class 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

Required Methods

• get_name(): Plugin identifier
• get_platform(): Platform name
• get_message_handler(): Message handler
• start(): Plugin initialization
• stop(): Plugin cleanup

🧪 Testing

Core Functionality

• Message processing modes
• Queue operations
• Core block management
• Error handling

Plugin Integration

• Plugin lifecycle
• Message routing
• Event handling
• Settings propagation

📚 Documentation

• Plugin Development Guide
• CLI Tools Reference
• Configuration Guide
• Telegram Plugin
• Telegram Bot Plugin
• CLI-Test Plugin

🤖 Agent/MCP-Ready Design

Sanctum: Broca 2 is built so that all CLI tools and plugin interfaces are MCP’able (machine-controllable by agents):

• Every CLI and admin tool is scriptable and can be operated by other AI agents or automation systems.
• All commands support machine-friendly output (e.g., JSON) and error handling.
• This enables Sanctum: Broca 2 to be embedded in agent networks, automated test harnesses, or orchestration systems.
• When extending Sanctum: Broca 2, always consider both human and agent/automation use cases.

🔮 Planned Updates

Multi-Agent Architecture

Sanctum: Broca 2 will support multiple Letta agents through a simple, efficient architecture:

• Each agent will run in its own Broca instance
• Instances will share a common virtual environment to minimize resource usage
• Simple git-based update system that preserves agent-specific configurations
• Clear 1:1 mapping between Broca instances and Letta agents

Broca MCP Server

A new Management Control Panel server will be added to manage multiple Broca instances:

• Instance Management: Deploy, monitor, and update Broca instances
• Agent Configuration: Manage Letta agent credentials and settings
• Monitoring & Logging: Centralized logging and performance metrics
• Resource Management: Monitor shared resources and system health
• Security: Centralized credential management and access control

🤖 Acknowledgments

• Original Broca project (It was me).
• Contributors and maintainers (Also me).
• Community support (the AI agents I made to help me).