Add comprehensive Kaleidoscope management tools and improve configuration

- Enhanced create_kaleidoscope.py with memory management protocols and tool use guidelines
- Added memory-management block that is read-only to lenses but writable by central agent
- Added tool-use-guidelines block for central agent communication clarity
- Updated config.example.yaml to use placeholder values and add base_url setting
- Added utility scripts for managing Kaleidoscope system:
- chat_direct.py: Direct agent communication interface
- delete_groups.py: Clean up agent groups
- firehose_listener.py: Monitor Bluesky firehose
- list_agents.py: View all agents in project
- list_groups.py: List agent groups
- setup_group.py: Initialize agent groups

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[e-mail]>

config.example.yaml

···
 letta:
   api_key: "your-letta-api-key-here"
   timeout: 600  # 10 minutes timeout for API calls
-  project_id: "c82faea2-3ce8-4aa9-a220-b56433e62c92"  # Use your specific project ID
-  agent_id: "agent-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # Your void agent ID
+  project_id: "your-project-id-here"  # Use your specific project ID
+  agent_id: "your-agent-id-here"  # Your void agent ID
+  base_url: "https://api.letta.com" # Default to letta cloud, this is typially http://localhost:8283 for self-hosted
 
 # Bluesky Configuration
 bluesky:

organon/chat_direct.py

···
+#!/usr/bin/env python3
+"""
+Direct chat with a specific group ID (bypassing the search logic).
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+from letta_client import Letta
+from rich.console import Console
+from rich.prompt import Prompt
+from rich.panel import Panel
+
+# Add parent directory to path for imports
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config_loader import get_config
+
+load_dotenv()
+
+def main():
+    console = Console()
+    
+    if len(sys.argv) != 2:
+        console.print("[red]Usage: python organon/chat_direct.py <group_id>[/red]")
+        console.print("[dim]Example: python organon/chat_direct.py group-0bf1c6[/dim]")
+        sys.exit(1)
+    
+    group_id = sys.argv[1]
+    
+    try:
+        # Initialize configuration and client
+        config = get_config()
+        
+        client = Letta(
+            base_url=config.get('letta.base_url', os.environ.get('LETTA_BASE_URL')),
+            token=config.get('letta.api_key', os.environ.get('LETTA_API_KEY')),
+            timeout=config.get('letta.timeout', 30)
+        )
+        
+        # Test if we can access the group
+        try:
+            group = client.groups.retrieve(group_id=group_id)
+            console.print(f"[green]✅ Connected to group: {group_id}[/green]")
+        except Exception as e:
+            console.print(f"[red]❌ Cannot access group {group_id}: {e}[/red]")
+            sys.exit(1)
+        
+        console.print(Panel.fit(
+            "[bold green]Direct Organon Group Chat[/bold green]\n"
+            f"Group ID: {group_id}\n"
+            "Type 'exit' or 'quit' to leave",
+            title="🧠 Direct Chat"
+        ))
+        
+        while True:
+            user_input = Prompt.ask("\n[bold green]You[/bold green]")
+            
+            if user_input.lower() in ['exit', 'quit', 'q']:
+                console.print("[yellow]Goodbye![/yellow]")
+                break
+            elif not user_input.strip():
+                continue
+            
+            console.print("[dim]Sending to group...[/dim]")
+            
+            try:
+                response = client.groups.messages.send(
+                    group_id=group_id,
+                    message=user_input
+                )
+                
+                console.print("\n[bold]Group Response:[/bold]")
+                if hasattr(response, 'messages') and response.messages:
+                    for message in response.messages:
+                        content = str(message)
+                        if hasattr(message, 'text'):
+                            content = message.text
+                        elif hasattr(message, 'content'):
+                            content = message.content
+                        
+                        console.print(Panel(content, border_style="blue"))
+                else:
+                    console.print("[yellow]No response received[/yellow]")
+                
+            except Exception as e:
+                console.print(f"[red]Error: {e}[/red]")
+    
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

organon/create_kaleidoscope.py

···
 4. Kaleidoscope Central → User (synthesis)
 """
 
+memory_management = """# Memory Management Protocols
+- Use memory_replace to completely replace a block's content with new information
+- Use memory_insert to add new information to an existing block without losing current content
+- Use memory_rethink to revise and improve existing block content while preserving core meaning
+
+# When to use each method:
+- memory_replace: When information is outdated, incorrect, or needs complete overhaul
+- memory_insert: When adding new insights, examples, or expanding existing knowledge
+- memory_rethink: When refining, clarifying, or improving the quality of existing content
+
+# Best Practices:
+- Always consider the impact on agent behavior before modifying memory
+- Preserve the core identity and purpose of each block
+- Test changes incrementally to ensure stability
+- Document significant memory modifications for future reference
+"""
+
+tool_use_guidelines = """# Tool Use Guidelines for Central Agent
+
+- send_message: Respond to the user. This is your method for external communication.
+- send_message_to_all_agents_in_group: Send a message to your lenses. This is internal communication.
+"""
+
 #
 # Block Creation
 #
···
     print("Lens management block already exists")
     lens_management_block = blocks[0]
 
+# Create memory-management block
+blocks = client.blocks.list(project_id=project_id, label="memory-management")
+if len(blocks) == 0:
+    memory_management_block = client.blocks.create(
+        project_id=project_id,
+        label="memory-management",
+        value=memory_management,
+        description="Protocols for managing agent memory blocks using memory_replace, memory_insert, and memory_rethink. This block is read-only to all lenses, but can be modified by the central kaleidoscope agent.",
+    )
+else:
+    print("Memory management block already exists")
+    memory_management_block = blocks[0]
+
+# Make memory-management block read-only to all lenses
+try:
+    # Get all lenses and make the block read-only to them
+    lenses = client.agents.list(tags=["kaleidoscope-lens"])
+    for lens in lenses:
+        try:
+            client.agents.blocks.modify(agent_id=lens.id, block_label=memory_management_block.label, read_only=True)
+            print(f"Memory management block set to read-only for lens: {lens.name}")
+        except Exception as e:
+            raise Exception(f"Could not set memory management block to read-only for lens {lens.name}: {e}")
+    print("Memory management block set to read-only for all lenses")
+except Exception as e:
+    raise Exception(f"Could not set memory management block to read-only: {e}")
+
+# Create tool_use_guidelines block
+blocks = client.blocks.list(project_id=project_id, label="tool-use-guidelines")
+if len(blocks) == 0:
+    tool_use_guidelines_block = client.blocks.create(
+        project_id=project_id,
+        label="tool-use-guidelines",
+        value=tool_use_guidelines,
+        description="Guidelines for the central kaleidoscope agent to use tools effectively.",
+    )
+else:
+    print("Tool use guidelines block already exists")
+    tool_use_guidelines_block = blocks[0]
+
 
 #
 # Static lens blocks
···
     kaleidoscope_persona_block.id,
     synthesis_protocols_block.id,
     lens_management_block.id,
+    memory_management_block.id,
+    tool_use_guidelines_block.id,
 ]
 
 # Create the central kaleidoscope if it doesn't exist
···
             agent_id=kaleidoscope_central_id,
             block_id=block,
         )
+
+# Ensure memory-management block is read-only to all lenses
+try:
+    # Get all lenses and make the block read-only to them
+    lenses = client.agents.list(tags=["kaleidoscope-lens"])
+    for lens in lenses:
+        try:
+            client.agents.blocks.modify(agent_id=lens.id, block_label=memory_management_block.label, read_only=True)
+            print(f"Memory management block confirmed as read-only for lens: {lens.name}")
+        except Exception as e:
+            raise Exception(f"Could not confirm memory management block as read-only for lens {lens.name}: {e}")
+    print("Memory management block confirmed as read-only for all lenses")
+except Exception as e:
+    raise Exception(f"Could not confirm memory management block as read-only: {e}")
+
+
 
 
 #
···
             lens_knowledge_block.id,
             lens_operational_protocols_block.id,
             lens_communication_protocols_block.id,
+            memory_management_block.id,
         ],
         tags=["kaleidoscope-lens"],
     )
···
     print(f"Created lens: {lens_name} (ID: {lens_agent.id})")
     lens_ids.append(lens_agent.id)
 
+# Ensure all existing lenses have the memory-management block
+print("\nEnsuring all lenses have memory-management block...")
+all_lenses = client.agents.list(tags=["kaleidoscope-lens"])
+for lens in all_lenses:
+    lens_blocks = client.agents.blocks.list(agent_id=lens.id)
+    lens_block_ids = [b.id for b in lens_blocks]
+    
+    if memory_management_block.id not in lens_block_ids:
+        print(f"Adding memory-management block to lens: {lens.name}")
+        client.agents.blocks.attach(
+            agent_id=lens.id,
+            block_id=memory_management_block.id,
+        )
+    else:
+        print(f"Lens {lens.name} already has memory-management block")
+
+# Also check for any existing lenses that might not have the tag but should be updated
+print("\nChecking for existing lenses without tags...")
+all_agents = client.agents.list()
+for agent in all_agents:
+    if agent.name in [lens_config["name"] for lens_config in LENS_TYPES]:
+        lens_blocks = client.agents.blocks.list(agent_id=agent.id)
+        lens_block_ids = [b.id for b in lens_blocks]
+        
+        if memory_management_block.id not in lens_block_ids:
+            print(f"Adding memory-management block to existing lens: {agent.name}")
+            client.agents.blocks.attach(
+                agent_id=agent.id,
+                block_id=memory_management_block.id,
+            )
+        else:
+            print(f"Existing lens {agent.name} already has memory-management block")
+
 
 #
 # Create a lens creation function for custom lenses
···
             lens_knowledge_block.id,
             lens_operational_protocols_block.id,
             lens_communication_protocols_block.id,
+            memory_management_block.id,
         ],
         tags=["kaleidoscope-lens"],
     )

organon/delete_groups.py

···
+#!/usr/bin/env python3
+"""
+Delete all groups in the current project.
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+from letta_client import Letta
+from rich.console import Console
+from rich.prompt import Confirm
+
+# Add parent directory to path for imports
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config_loader import get_config
+
+load_dotenv()
+
+def main():
+    console = Console()
+    
+    try:
+        # Initialize configuration and client
+        config = get_config()
+        
+        client = Letta(
+            base_url=config.get('letta.base_url', os.environ.get('LETTA_BASE_URL')),
+            token=config.get('letta.api_key', os.environ.get('LETTA_API_KEY')),
+            timeout=config.get('letta.timeout', 30)
+        )
+        
+        project_id = config.get('letta.project_id', os.environ.get('LETTA_PROJECT_ID'))
+        
+        # Get all groups
+        console.print("[blue]Finding all groups...[/blue]")
+        
+        try:
+            if project_id:
+                groups = client.groups.list()
+            else:
+                groups = client.groups.list()
+        except:
+            # Try without project_id as fallback
+            try:
+                groups = client.groups.list()
+            except Exception as e:
+                console.print(f"[red]Error listing groups: {e}[/red]")
+                return
+        
+        if not groups:
+            console.print("[yellow]No groups found.[/yellow]")
+            return
+        
+        console.print(f"[yellow]Found {len(groups)} groups:[/yellow]")
+        for group in groups:
+            description = group.description[:50] + "..." if group.description and len(group.description) > 50 else (group.description or "No description")
+            console.print(f"  • {group.id[:12]}... - {description}")
+        
+        # Confirm deletion
+        if not Confirm.ask(f"\n[bold red]Delete all {len(groups)} groups?[/bold red]"):
+            console.print("[yellow]Cancelled.[/yellow]")
+            return
+        
+        # Delete each group
+        deleted_count = 0
+        for group in groups:
+            try:
+                client.groups.delete(group_id=group.id)
+                console.print(f"[green]✅ Deleted group: {group.id[:12]}[/green]")
+                deleted_count += 1
+            except Exception as e:
+                console.print(f"[red]❌ Failed to delete group {group.id[:12]}: {e}[/red]")
+        
+        console.print(f"\n[green]Successfully deleted {deleted_count}/{len(groups)} groups.[/green]")
+    
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

organon/firehose_listener.py

···
+"""
+ATProto firehose listener that connects to Jetstream and pipes content to Organon agent.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import sys
+import websockets
+import zstandard as zstd
+from datetime import datetime
+from typing import Optional, Dict, Any
+from dotenv import load_dotenv
+from letta_client import Letta, SupervisorManager
+
+# Add parent directory to path for imports
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config_loader import get_config
+
+load_dotenv()
+
+# Setup logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+class OrganonFirehoseListener:
+    def __init__(self):
+        """Initialize the firehose listener with Letta client and configuration."""
+        self.config = get_config()
+        
+        # Initialize Letta client
+        self.letta_client = Letta(
+            base_url=self.config.get('letta.base_url', os.environ.get('LETTA_BASE_URL')),
+            token=self.config.get('letta.api_key', os.environ.get('LETTA_API_KEY')),
+            timeout=self.config.get('letta.timeout', 30)
+        )
+        
+        # Get project ID
+        self.project_id = self.config.get('letta.project_id', os.environ.get('LETTA_PROJECT_ID'))
+        if not self.project_id:
+            raise ValueError("Project ID must be set in config.yaml under letta.project_id or as LETTA_PROJECT_ID environment variable")
+        
+        # Jetstream WebSocket URL (try different endpoints)
+        self.jetstream_url = "wss://jetstream2.us-east.bsky.network/subscribe"
+        
+        # Filter for posts only
+        self.wanted_collections = ["app.bsky.feed.post"]
+        
+        # Get Organon central agent
+        self.organon_agent_id = self._get_organon_agent_id()
+        
+        # List all organon shards on boot
+        self._list_organon_shards()
+        
+        # Ensure supervisor group exists with all shards
+        self.organon_group_id = self._ensure_organon_supervisor_group()
+        
+        # Connection state
+        self.websocket = None
+        self.running = False
+        
+        # Zstd decompressor for compressed messages
+        self.decompressor = zstd.ZstdDecompressor()
+        
+    def _get_organon_agent_id(self) -> str:
+        """Get the Organon central agent ID."""
+        agents = self.letta_client.agents.list(project_id=self.project_id, name="organon-central")
+        if not agents:
+            raise ValueError("Organon central agent not found. Run create_organon.py first.")
+        return agents[0].id
+    
+    def _list_organon_shards(self) -> None:
+        """List all organon shards using the organon-shard tag."""
+        try:
+            # Get agents with the organon-shard tag
+            shard_agents = self.letta_client.agents.list(project_id=self.project_id, tags=["organon-shard"])
+            
+            logger.info(f"Found {len(shard_agents)} Organon shards:")
+            for agent in shard_agents:
+                logger.info(f"  - {agent.name} (ID: {agent.id})")
+                if agent.description:
+                    logger.info(f"    Description: {agent.description}")
+            
+            if len(shard_agents) == 0:
+                logger.warning("No Organon shards found with tag 'organon-shard'")
+                
+        except Exception as e:
+            logger.error(f"Error listing Organon shards: {e}")
+    
+    def _ensure_organon_supervisor_group(self) -> str:
+        """Ensure a supervisor group exists with organon-central as supervisor and all shards as workers."""
+        try:
+            group_name = "organon-ecosystem"
+            
+            # Get all organon shards
+            shard_agents = self.letta_client.agents.list(project_id=self.project_id, tags=["organon-shard"])
+            
+            if len(shard_agents) == 0:
+                logger.warning("No shards found, cannot create group")
+                raise ValueError("No Organon shards found with tag 'organon-shard'")
+            
+            # Check if group already exists
+            try:
+                existing_groups = self.letta_client.groups.list(project_id=self.project_id)
+                existing_group = None
+                for group in existing_groups:
+                    if group.name == group_name:
+                        existing_group = group
+                        break
+                        
+                if existing_group:
+                    logger.info(f"Organon supervisor group '{group_name}' already exists (ID: {existing_group.id})")
+                    
+                    # For supervisor groups, only the worker agents are in the group membership
+                    # The supervisor is managed separately via the manager_config
+                    group_members = self.letta_client.groups.agents.list(group_id=existing_group.id)
+                    member_ids = {member.id for member in group_members}
+                    shard_ids = {shard.id for shard in shard_agents}
+                    
+                    # Add missing shards to the group
+                    missing_shards = shard_ids - member_ids
+                    for shard_id in missing_shards:
+                        logger.info(f"Adding shard {shard_id} to group {group_name}")
+                        self.letta_client.groups.agents.add(
+                            group_id=existing_group.id,
+                            agent_id=shard_id
+                        )
+                    
+                    # Remove any agents that are no longer shards
+                    extra_members = member_ids - shard_ids
+                    for member_id in extra_members:
+                        logger.info(f"Removing non-shard agent {member_id} from group {group_name}")
+                        self.letta_client.groups.agents.remove(
+                            group_id=existing_group.id,
+                            agent_id=member_id
+                        )
+                    
+                    return existing_group.id
+                    
+            except Exception as e:
+                logger.debug(f"Error checking existing groups: {e}")
+            
+            # Create new supervisor group
+            logger.info(f"Creating new Organon supervisor group '{group_name}'")
+            
+            # Get all shard IDs
+            worker_agent_ids = [shard.id for shard in shard_agents]
+            
+            group = self.letta_client.groups.create(
+                agent_ids=worker_agent_ids,
+                description="Supervisor group for the Organon ecosystem with organon-central managing all shards",
+                manager_config=SupervisorManager(
+                    manager_agent_id=self.organon_agent_id
+                )
+            )
+            
+            logger.info(f"Created Organon supervisor group '{group_name}' (ID: {group.id})")
+            logger.info(f"  Supervisor: organon-central ({self.organon_agent_id})")
+            logger.info(f"  Workers: {len(worker_agent_ids)} shards")
+            
+            return group.id
+            
+        except Exception as e:
+            logger.error(f"Error ensuring Organon supervisor group: {e}")
+            raise
+    
+    async def connect(self) -> None:
+        """Connect to the Jetstream WebSocket."""
+        # Build query parameters - disable compression for now
+        params = {
+            "wantedCollections": ",".join(self.wanted_collections)
+            # Removing compression to debug the utf-8 issue
+        }
+        
+        # Build URL with parameters
+        param_string = "&".join([f"{k}={v}" for k, v in params.items()])
+        url = f"{self.jetstream_url}?{param_string}"
+        
+        logger.info(f"Connecting to Jetstream: {url}")
+        
+        try:
+            self.websocket = await websockets.connect(url)
+            logger.info("Connected to Jetstream firehose")
+        except Exception as e:
+            logger.error(f"Failed to connect to Jetstream: {e}")
+            raise
+    
+    def _process_post_content(self, record: Dict[str, Any]) -> Optional[str]:
+        """Extract and process post content from a record."""
+        try:
+            # Extract basic post information
+            text = record.get('text', '')
+            created_at = record.get('createdAt', '')
+            
+            # Extract facets (links, mentions, hashtags) if present
+            facets = record.get('facets', [])
+            
+            # Build a structured representation
+            content_data = {
+                'text': text,
+                'created_at': created_at,
+                'facets': facets
+            }
+            
+            # Only process posts with meaningful content (ignore very short posts)
+            if len(text.strip()) < 10:
+                return None
+                
+            return json.dumps(content_data, indent=2)
+            
+        except Exception as e:
+            logger.error(f"Error processing post content: {e}")
+            return None
+    
+    async def _send_to_organon(self, content: str, metadata: Dict[str, Any]) -> None:
+        """Send processed content to the Organon ecosystem via group messaging."""
+        try:
+            # Create a conceptual observation message for Organon
+            message = f"""New observation from the ATProto firehose:
+
+Content:
+{content}
+
+Metadata:
+- DID: {metadata.get('did', 'unknown')}
+- Collection: {metadata.get('collection', 'unknown')}
+- Timestamp: {metadata.get('time_us', 'unknown')}
+- CID: {metadata.get('cid', 'unknown')}
+- RKey: {metadata.get('rkey', 'unknown')}
+
+Please analyze this content and generate Conceptual Suggestion Packets (CSPs) if it contains novel ideas, patterns, or contradictions worth exploring. Coordinate with your shards to explore different conceptual dimensions."""
+
+            # Send message to Organon group (supervisor will coordinate with shards)
+            response = self.letta_client.groups.messages.create(
+                group_id=self.organon_group_id,
+                messages=[{
+                    "role": "user",
+                    "content": message
+                }]
+            )
+            
+            logger.info(f"Sent content to Organon ecosystem (group {self.organon_group_id})")
+            logger.debug(f"Group response: {len(response.messages) if hasattr(response, 'messages') else 'N/A'} messages")
+            
+        except Exception as e:
+            logger.error(f"Error sending content to Organon ecosystem: {e}")
+    
+    async def _handle_event(self, event: Dict[str, Any]) -> None:
+        """Handle a single event from the firehose."""
+        try:
+            event_type = event.get('kind')
+            
+            if event_type == 'commit':
+                # Extract commit information
+                did = event.get('did')
+                commit = event.get('commit', {})
+                
+                # Check if this is a create operation for a post
+                operation = commit.get('operation')
+                collection = commit.get('collection')
+                
+                if operation == 'create' and collection == 'app.bsky.feed.post':
+                    record = commit.get('record', {})
+                    
+                    # Process the post content
+                    processed_content = self._process_post_content(record)
+                    
+                    if processed_content:
+                        metadata = {
+                            'did': did,
+                            'collection': collection,
+                            'time_us': event.get('time_us'),
+                            'cid': commit.get('cid'),
+                            'rkey': commit.get('rkey')
+                        }
+                        
+                        logger.info(f"Sending post to Organon from {did}")
+                        
+                        # Send to Organon for analysis
+                        await self._send_to_organon(processed_content, metadata)
+                    else:
+                        logger.debug(f"Skipping post from {did} - too short or no content")
+                            
+        except Exception as e:
+            logger.error(f"Error handling event: {e}")
+    
+    async def listen(self) -> None:
+        """Listen to the firehose and process events."""
+        if not self.websocket:
+            await self.connect()
+        
+        self.running = True
+        logger.info("Starting to listen to firehose events...")
+        
+        try:
+            async for message in self.websocket:
+                if not self.running:
+                    break
+                
+                try:
+                    # Handle message format
+                    if isinstance(message, bytes):
+                        message_text = message.decode('utf-8')
+                    else:
+                        message_text = message
+                    
+                    # Parse JSON event
+                    event = json.loads(message_text)
+                    
+                    # Print the whole JSON message for debugging
+                    print(f"\n--- FULL JSON MESSAGE ---")
+                    print(json.dumps(event, indent=2))
+                    print(f"--- END MESSAGE ---\n")
+                    
+                    # Handle the event
+                    await self._handle_event(event)
+                    
+                except json.JSONDecodeError as e:
+                    logger.error(f"Failed to parse JSON message: {e}")
+                except Exception as e:
+                    logger.error(f"Error processing message: {e}")
+                    
+        except websockets.exceptions.ConnectionClosed:
+            logger.warning("WebSocket connection closed")
+        except Exception as e:
+            logger.error(f"Error in listen loop: {e}")
+        finally:
+            self.running = False
+    
+    async def stop(self) -> None:
+        """Stop the firehose listener."""
+        self.running = False
+        if self.websocket:
+            await self.websocket.close()
+        logger.info("Firehose listener stopped")
+    
+    async def run_with_reconnect(self, max_retries: int = 10, retry_delay: int = 5) -> None:
+        """Run the listener with automatic reconnection."""
+        retry_count = 0
+        
+        while retry_count < max_retries:
+            try:
+                await self.connect()
+                await self.listen()
+                
+                # If we get here, connection was closed gracefully
+                if not self.running:
+                    logger.info("Listener stopped gracefully")
+                    break
+                    
+            except Exception as e:
+                retry_count += 1
+                logger.error(f"Connection failed (attempt {retry_count}/{max_retries}): {e}")
+                
+                if retry_count < max_retries:
+                    logger.info(f"Retrying in {retry_delay} seconds...")
+                    await asyncio.sleep(retry_delay)
+                else:
+                    logger.error("Max retries exceeded, stopping listener")
+                    break
+
+async def main():
+    """Main function to run the firehose listener."""
+    listener = OrganonFirehoseListener()
+    
+    try:
+        await listener.run_with_reconnect()
+    except KeyboardInterrupt:
+        logger.info("Received interrupt signal")
+    finally:
+        await listener.stop()
+
+if __name__ == "__main__":
+    asyncio.run(main())

organon/list_agents.py

···
+#!/usr/bin/env python3
+"""
+Simple tool to list all agents in the current project, especially Organon-related ones.
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+from letta_client import Letta
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+
+# Add parent directory to path for imports
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config_loader import get_config
+
+load_dotenv()
+
+def main():
+    console = Console()
+    
+    try:
+        # Initialize configuration and client
+        config = get_config()
+        
+        client = Letta(
+            base_url=config.get('letta.base_url', os.environ.get('LETTA_BASE_URL')),
+            token=config.get('letta.api_key', os.environ.get('LETTA_API_KEY')),
+            timeout=config.get('letta.timeout', 30)
+        )
+        
+        project_id = config.get('letta.project_id', os.environ.get('LETTA_PROJECT_ID'))
+        if not project_id:
+            raise ValueError("Project ID must be set in config.yaml under letta.project_id or as LETTA_PROJECT_ID environment variable")
+        
+        # Get all agents
+        agents = client.agents.list(project_id=project_id)
+        
+        if not agents:
+            console.print("[yellow]No agents found in this project.[/yellow]")
+            console.print("[dim]Run create_organon.py to create the Organon agents.[/dim]")
+            return
+        
+        # Create table
+        table = Table(title=f"Agents in Project {project_id[:8]}...")
+        table.add_column("Agent Name", style="cyan")
+        table.add_column("Agent ID", style="white") 
+        table.add_column("Description", style="green")
+        table.add_column("Tags", style="yellow")
+        
+        organon_central = None
+        organon_shards = []
+        
+        for agent in agents:
+            name = agent.name if hasattr(agent, 'name') else "N/A"
+            agent_id = agent.id[:12] + "..." if len(agent.id) > 12 else agent.id
+            description = agent.description[:40] + "..." if agent.description and len(agent.description) > 40 else (agent.description or "N/A")
+            tags = ", ".join(agent.tags) if hasattr(agent, 'tags') and agent.tags else "None"
+            
+            table.add_row(name, agent_id, description, tags)
+            
+            # Track Organon agents
+            if name == "organon-central":
+                organon_central = agent
+            elif hasattr(agent, 'tags') and agent.tags and "organon-shard" in agent.tags:
+                organon_shards.append(agent)
+        
+        console.print(table)
+        
+        # Show Organon status
+        console.print("\n[bold blue]Organon Status:[/bold blue]")
+        
+        if organon_central:
+            console.print(f"✅ [green]Organon Central found:[/green] {organon_central.name} ({organon_central.id[:8]})")
+        else:
+            console.print("❌ [red]Organon Central not found[/red]")
+        
+        if organon_shards:
+            console.print(f"✅ [green]Found {len(organon_shards)} Organon shards:[/green]")
+            for shard in organon_shards:
+                console.print(f"   • {shard.name} ({shard.id[:8]})")
+        else:
+            console.print("❌ [red]No Organon shards found with tag 'organon-shard'[/red]")
+        
+        # Recommendations
+        console.print("\n[bold yellow]Recommendations:[/bold yellow]")
+        if not organon_central:
+            console.print("• Run [cyan]ac && python organon/create_organon.py[/cyan] to create Organon agents")
+        elif not organon_shards:
+            console.print("• Run [cyan]ac && python organon/create_organon.py[/cyan] to create Organon shards")
+        else:
+            console.print("• Run [cyan]ac && python organon/firehose_listener.py[/cyan] to create the ecosystem group")
+    
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

organon/list_groups.py

···
+#!/usr/bin/env python3
+"""
+Simple tool to list all groups and their status in the current project.
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+from letta_client import Letta
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+
+# Add parent directory to path for imports
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config_loader import get_config
+
+load_dotenv()
+
+def get_agent_name(client, agent_id):
+    """Get agent name by ID, with fallback to truncated ID."""
+    try:
+        agent = client.agents.retrieve(agent_id=agent_id)
+        return agent.name if hasattr(agent, 'name') else agent_id[:8]
+    except:
+        return agent_id[:8]
+
+def main():
+    console = Console()
+    
+    try:
+        # Initialize configuration and client
+        config = get_config()
+        
+        client = Letta(
+            base_url=config.get('letta.base_url', os.environ.get('LETTA_BASE_URL')),
+            token=config.get('letta.api_key', os.environ.get('LETTA_API_KEY')),
+            timeout=config.get('letta.timeout', 30)
+        )
+        
+        project_id = config.get('letta.project_id', os.environ.get('LETTA_PROJECT_ID'))
+        if not project_id:
+            raise ValueError("Project ID must be set in config.yaml under letta.project_id or as LETTA_PROJECT_ID environment variable")
+        
+        # Get all groups
+        groups = client.groups.list()
+        
+        if not groups:
+            console.print("[yellow]No groups found in this project.[/yellow]")
+            return
+        
+        # Create table
+        table = Table(title=f"Groups in Project {project_id[:8]}...")
+        table.add_column("Group ID", style="cyan")
+        table.add_column("Description", style="white")
+        table.add_column("Type", style="green")
+        table.add_column("Manager/Supervisor", style="blue")
+        table.add_column("Members", style="yellow")
+        
+        for group in groups:
+            group_id = group.id[:12] + "..." if len(group.id) > 12 else group.id
+            description = group.description[:50] + "..." if group.description and len(group.description) > 50 else (group.description or "N/A")
+            
+            # Determine group type and manager
+            group_type = "Unknown"
+            manager = "None"
+            
+            if hasattr(group, 'manager_config') and group.manager_config:
+                if hasattr(group.manager_config, 'manager_type'):
+                    group_type = group.manager_config.manager_type
+                elif hasattr(group.manager_config, '__class__'):
+                    group_type = group.manager_config.__class__.__name__.replace('Manager', '')
+                
+                if hasattr(group.manager_config, 'manager_agent_id') and group.manager_config.manager_agent_id:
+                    manager = get_agent_name(client, group.manager_config.manager_agent_id)
+            
+            # Get group members
+            try:
+                members = client.groups.agents.list(group_id=group.id)
+                member_count = len(members)
+                
+                # Show member names if reasonable number
+                if member_count <= 3:
+                    member_names = [get_agent_name(client, member.id) for member in members]
+                    members_str = ", ".join(member_names)
+                else:
+                    members_str = f"{member_count} agents"
+            except:
+                members_str = "Error loading"
+            
+            table.add_row(group_id, description, group_type, manager, members_str)
+        
+        console.print(table)
+        
+        # Look specifically for Organon ecosystem
+        organon_groups = []
+        for group in groups:
+            if (group.description and 'organon' in group.description.lower()) or \
+               (hasattr(group, 'manager_config') and group.manager_config and 
+                hasattr(group.manager_config, 'manager_agent_id')):
+                try:
+                    # Check if manager is organon-central
+                    if hasattr(group.manager_config, 'manager_agent_id'):
+                        manager_name = get_agent_name(client, group.manager_config.manager_agent_id)
+                        if 'organon' in manager_name.lower():
+                            organon_groups.append((group, manager_name))
+                except:
+                    pass
+        
+        if organon_groups:
+            console.print("\n[bold green]Organon Ecosystem Groups Found:[/bold green]")
+            for group, manager_name in organon_groups:
+                console.print(f"  • {group.id} - Managed by {manager_name}")
+        else:
+            console.print("\n[yellow]No Organon ecosystem groups found.[/yellow]")
+            console.print("[dim]Run the firehose listener to create the Organon ecosystem group.[/dim]")
+    
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

organon/setup_group.py

···
+#!/usr/bin/env python3
+"""
+Simple tool to set up the Organon ecosystem group without running the firehose listener.
+"""
+
+import os
+import sys
+from dotenv import load_dotenv
+from letta_client import Letta, SupervisorManager
+from rich.console import Console
+
+# Add parent directory to path for imports
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+from config_loader import get_config
+
+load_dotenv()
+
+def main():
+    console = Console()
+    
+    try:
+        # Initialize configuration and client
+        config = get_config()
+        
+        client = Letta(
+            base_url=config.get('letta.base_url', os.environ.get('LETTA_BASE_URL')),
+            token=config.get('letta.api_key', os.environ.get('LETTA_API_KEY')),
+            timeout=config.get('letta.timeout', 30)
+        )
+        
+        project_id = config.get('letta.project_id', os.environ.get('LETTA_PROJECT_ID'))
+        if not project_id:
+            raise ValueError("Project ID must be set in config.yaml under letta.project_id or as LETTA_PROJECT_ID environment variable")
+        
+        # Get Organon central agent
+        console.print("[blue]Finding Organon Central agent...[/blue]")
+        try:
+            organon_agents = client.agents.list(project_id=project_id, name="organon-central")
+        except:
+            # Fallback for self-hosted without project support
+            organon_agents = client.agents.list(name="organon-central")
+        if not organon_agents:
+            console.print("[red]❌ Organon Central agent not found. Run create_organon.py first.[/red]")
+            return
+        
+        organon_central_id = organon_agents[0].id
+        console.print(f"[green]✅ Found Organon Central: {organon_central_id[:8]}[/green]")
+        
+        # Get Organon shards
+        console.print("[blue]Finding Organon shards...[/blue]")
+        try:
+            shard_agents = client.agents.list(project_id=project_id, tags=["organon-shard"])
+        except:
+            # Fallback for self-hosted without project support
+            shard_agents = client.agents.list(tags=["organon-shard"])
+        if not shard_agents:
+            console.print("[red]❌ No Organon shards found. Run create_organon.py to create shards.[/red]")
+            return
+        
+        console.print(f"[green]✅ Found {len(shard_agents)} shards:[/green]")
+        for shard in shard_agents:
+            console.print(f"   • {shard.name} ({shard.id[:8]})")
+        
+        # Check if group already exists
+        console.print("[blue]Checking for existing groups...[/blue]")
+        try:
+            groups = client.groups.list(project_id=project_id)
+        except:
+            # Fallback for self-hosted without project support
+            groups = client.groups.list()
+        
+        existing_group = None
+        for group in groups:
+            if (group.description and 'organon ecosystem' in group.description.lower()) or \
+               (hasattr(group, 'manager_config') and group.manager_config and 
+                hasattr(group.manager_config, 'manager_agent_id') and 
+                group.manager_config.manager_agent_id == organon_central_id):
+                existing_group = group
+                break
+        
+        if existing_group:
+            console.print(f"[yellow]Group already exists: {existing_group.id[:12]}[/yellow]")
+            return
+        
+        # Create the supervisor group
+        console.print("[blue]Creating Organon ecosystem group...[/blue]")
+        worker_agent_ids = [shard.id for shard in shard_agents]
+        
+        group = client.groups.create(
+            agent_ids=worker_agent_ids,
+            description="Supervisor group for the Organon ecosystem with organon-central managing all shards",
+            manager_config=SupervisorManager(
+                manager_agent_id=organon_central_id
+            )
+        )
+        
+        console.print(f"[green]✅ Created Organon ecosystem group: {group.id[:12]}[/green]")
+        console.print(f"   Supervisor: organon-central ({organon_central_id[:8]})")
+        console.print(f"   Workers: {len(worker_agent_ids)} shards")
+        
+        # Verify the group was actually created
+        console.print("[blue]Verifying group creation...[/blue]")
+        try:
+            retrieved_group = client.groups.retrieve(group_id=group.id)
+            console.print(f"[green]✅ Group verified: {retrieved_group.id[:12]}[/green]")
+            
+            # Also check if it shows up in the list
+            try:
+                all_groups = client.groups.list(project_id=project_id)
+            except:
+                all_groups = client.groups.list()
+            found_in_list = any(g.id == group.id for g in all_groups)
+            console.print(f"[{'green' if found_in_list else 'red'}]{'✅' if found_in_list else '❌'} Group appears in list: {found_in_list}[/{'green' if found_in_list else 'red'}]")
+            
+        except Exception as e:
+            console.print(f"[red]❌ Error verifying group: {e}[/red]")
+        
+        console.print("\n[bold green]Setup complete! You can now use:[/bold green]")
+        console.print("• [cyan]python organon/chat_with_organon.py[/cyan] - Chat with the ecosystem")
+        console.print("• [cyan]python organon/list_groups.py[/cyan] - View group status")
+        console.print("• [cyan]python organon/firehose_listener.py[/cyan] - Start the firehose listener")
+    
+    except Exception as e:
+        console.print(f"[red]Error: {e}[/red]")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()