⚠️ REPOSITORY MOVED ⚠️

This repository has moved to: http://github.com/sanctumos/broca

Please update your git remotes and use the new repository location for all future development and contributions.

---

Sanctum: Broca 2 (v0.10.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/sanctumos/broca.git
   cd broca

2. Install dependencies:

   pip install -r requirements.txt

3. Configure environment:

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

🚦 Usage

Running the Server

python main.py

CLI Tools

# Queue management
python -m cli.btool queue list
python -m cli.btool queue flush

# User management
python -m cli.btool 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

User Documentation

• Multi-Agent Architecture Guide - Complete guide to running multiple agent instances
• Plugin Development Guide
• CLI Tools Reference
• Configuration Guide
• Telegram Plugin
• Telegram Bot Plugin
• CLI-Test Plugin
• Web Chat Bridge API
• Web Chat Bridge Project Plan

Developer Documentation

For internal development documentation, technical analysis, and project planning, see the broca2/docs/dev-docs/ folder.

🤖 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

🏠 Multi-Agent Setup

Folder Structure

For managing multiple Broca instances on the same machine, use the following structure:

~/sanctum/broca2/             # Base Broca 2 installation
├── venv/                     # Shared virtual environment
├── main.py
├── runtime/
├── plugins/
├── requirements.txt
├── 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/

Setup Instructions

1. Choose your master folder:

   # Typically your home directory or a dedicated user folder
   mkdir ~/sanctum
   cd ~/sanctum

2. Clone the base Broca 2 installation:

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

3. Create agent-specific instances:

   # For each Letta agent, create a folder named after the agent ID
   mkdir ~/sanctum/broca2/agent-721679f6-c8af-4e01-8677-dc042dc80368
   cd ~/sanctum/broca2/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:

   # From the agent folder
   cd ~/sanctum/broca2/agent-721679f6-c8af-4e01-8677-dc042dc80368
   python ../main.py
   
   # Or use the CLI tools
   python -m cli.btool queue list

Master Sanctum Provisioning Suite Integration

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

Managing Multiple Instances

Starting Instances

# Start a specific agent's Broca instance
cd ~/sanctum/broca2/agent-721679f6-c8af-4e01-8677-dc042dc80368
python ../main.py

# Or use a process manager like PM2
pm2 start "broca-agent-1" --interpreter python -- ../main.py
pm2 start "broca-agent-2" --interpreter python -- ../main.py

Configuration Management

# Each agent has its own configuration
~/sanctum/broca2/agent-721679f6-c8af-4e01-8677-dc042dc80368/.env
~/sanctum/broca2/agent-721679f6-c8af-4e01-8677-dc042dc80368/settings.json

# Shared configurations can be symlinked or copied
ln -s ~/sanctum/broca2/shared/templates/telegram_config.json ~/sanctum/broca2/agent-*/telegram_config.json

Database Management

# Each agent has its own database
~/sanctum/broca2/agent-721679f6-c8af-4e01-8677-dc042dc80368/sanctum.db

# Backup agent-specific databases
cp ~/sanctum/broca2/agent-*/sanctum.db ~/sanctum/broca2/backups/

Logging

# Each agent has its own logs
~/sanctum/broca2/agent-721679f6-c8af-4e01-8677-dc042dc80368/logs/

# Centralized logging (optional)
ln -s ~/sanctum/broca2/logs/ ~/sanctum/broca2/agent-*/logs

Benefits of This Structure

• Isolation: Each agent runs independently with its own configuration and database
• Scalability: Easy to add new agents without affecting existing ones
• Maintenance: Update the base Broca 2 installation once, affects all agents
• Backup: Simple to backup individual agent configurations and data
• Resource Efficiency: Shared base installation reduces disk usage
• Flexibility: Each agent can have different plugins, settings, and configurations

🤖 Acknowledgments

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