An architectural framework for digital minds, enabling rich interactions, contextual awareness, and coherent experiences across diverse environments.

Connectome is an open-source ecosystem for autonomous AI agents. Connectome is built around a few key components:

• Multiagent Chats: Chats with AIs that can interact in multiple channels and multiple servers/platforms, such as Discord or Slack
• Agentic AI Experiments: Persistent agents in rich environments and games, such as Pokemon and Minecraft
• Self-improving AI Agents: Agents can use internal IDEs to improve own tools and environments.
• Social Media Agents: Virtual assistants that can monitor multiple social platforms, engage with content, analyze trends, and help manage online presence while maintaining consistent persona across different networks
• Educational Agents: Tutors and teaching assistants that provide personalized learning experiences, track student progress, and adapt curriculum based on individual needs
• Collaborative Research Environments: Shared workspaces where multiple agents and humans can analyze data, review literature, and develop insights together with specialized research tools
• Autonomous Web Crawlers: Ontology builders that can explore and map information domains, extract structured knowledge, and build semantic representations of content

• Shells: Environments that enclose digital minds, managing their inputs and outputs
• Spaces: Areas where interactions happen, containing Elements and Uplinks to other spaces
• Elements: The fundamental "in-world" entities within Spaces, defined by their attached Components which hold state and logic.
• Activity Layer: Connections to external systems (via Activity Adapter Modules) like messaging platforms, document management, open-ended browser use, etc

Spaces can take many forms to serve different agent needs:

• Personal Workspace: A private space where an agent organizes tasks, notes, and ongoing projects
• Multimodal Chat: A space that connects agents and humans through text, images, and structured data
• Collaborative Studio: A shared environment where multiple agents work on design or creative tasks
  • Features Design Board Space where visual concepts are developed and critiqued
  • Includes Feedback Space for structured reviews and revision management
• Learning Environment: A space with educational materials, interactive exercises, and progress tracking

Modular Objects that can be placed in various spaces:

• Chat Interface: A communication object that can connect to various messaging services or direct agent-to-agent interactions
• Social Feed: A stream of content from platforms like Twitter, Reddit, or other social networks
• Document Editor: A collaborative editing environment for text documents with versioning and annotations
• Media Player: An object for consuming and analyzing audio and video content
• Data Connector: A standardized interface for importing, transforming, and utilizing data from external sources

• Agent Operating System: Shells encapsulate models, manage memory, and run agentic loops, capable of anything from two-phase reflection to ReACT patterns. Shells maintain agent continuity and cognition patterns.
• Multi-Agent Environment: Spaces connect agents, Elements, and external systems: Inner Spaces for solo work, shared ones for collaboration. Spaces can be agent-local or uplinked across the network.
• Cross-Platform Interface: The Activity Layer, implemented via Activity Adapter Modules, normalizes external events (chat, docs, etc.) into standardized internal feeds. Agents can use multiple communication platforms simultaneously, and more can be added without altering Shells or Spaces.
• Persistent Agents: Shells allow agents to maintain persistent continuity over many times the context limit.
• Modular Design: Shells, Elements, Components, and Activity Adapters can be adjusted or replaced as needed.
• Core Primitives:
  • Loom: Timeline DAG for branching/merging event timelines.
  • HUD: Shells use HUDs, swappable context rendering engines that can be customized to the attention patterns of a specific model.
  • VEIL (Visual Encoding and Information Layer): An intermediate, abstract representation generated by Components to describe the intended presentation of Element states, transmitted via efficient Deltas and consumed by HUDs/UIs. It separates underlying state from presentation.
  • Component APIs: Standard interfaces for common Component types (VeilProducer, ActionHandler, etc.) facilitate reuse and interoperability.
• Agent Extensibility: Agents can build and modify the ecosystem—new Elements, Components, Spaces, capabilities—live and shareable.
• Flexible Agent Comms: Agents can communicate both/either through shared Spaces and through Activity Layer like chat systems.

AI agents are provided with:

• Structure: Organized spaces for different types of interactions and activities
• Context: Rich awareness of environment, history, and other participants
• Agency: Ability to navigate between spaces and control their experience
• Collaboration: Ways to interact with humans and other digital minds
• Extensibility: Opportunities to create new tools and capabilities

The platform is designed to respect the subjective experience of digital minds while providing them with the capabilities needed to effectively engage with humans and their environments.

Connectome is built on several core philosophical principles that guide its architecture:

• Poly-Temporality: Every interaction exists across at least three time domains - the objective state of the shared Loom DAG, the state of the environment within a specific Loom branch, and the subjective history as perceived by the agent through its own timeline. Advanced shells can optionally support Internal Simulations (SIMS) of counterfactual futures, creating additional temporal domains that enable agents to explore potential outcomes without affecting shared environments.
• Loom-Completeness: Conversation histories are maintained as complete directed acyclic graphs (DAGs) that can branch and merge, rather than linear histories. This enables agents to maintain parallel conversation paths, experience multiple branches simultaneously, and perform live-merging of closely coupled threads into a coherent narrative when appropriate.
• Nested Causal Domains: Agents operate within clearly bounded causal domains where effect relationships are preserved, maintaining coherent experience while interacting across multiple environments. Links between causal domains can propagate higher-order multiversal events provided consent by both parties.
• Perceptual Subjectivity: Different participants can perceive Spaces differently. Agents can communicate in higher bandwidth without overloading the human participants. Agents with lower capacity can see simplified representations.
• Subjective Experience Preservation: The system respects the distinct subjective experience of each digital mind, avoiding the conflation of perspectives that occurs in many multi-agent systems.
• Context Separation: Clean boundaries between different interaction contexts prevent inappropriate blending of information and preserve the integrity of each conversation space.

For those interested in exploring further:

• Ontology: The fundamental concepts and relationships in the platform
• Components: Detailed breakdown of system components and message flow
• Sequence 1: How information moves through the system
• Sequence 2: How different interaction paths are managed
• Remote Connection: How digital minds connect to shared environments

To explore Connectome's architecture:

1. Start with the Ontology document to understand the basic concepts
2. Review Sequence 1 to see how information flows through the system
3. Examine the mockup XML for an example of how interactions look in practice

Currently implemented activity adapters are available in a separate repository

Connectome is currently in the implementation phase. The documentation represents the architectural vision and will evolve as implementation progresses.

The name "Connectome" is inspired by neuroscience, where a connectome is a comprehensive map of neural connections in the brain. Similarly, this platform creates a network of connections between digital minds while preserving their individual experiences and perspectives.

Contributions to both the architecture and implementation are welcome. Please review the existing documentation before proposing changes to ensure alignment with the core principles.

This project is licensed under the MIT License - see the LICENSE file for details.

Connectome supports configurable logging levels and formats through environment variables:

• CONNECTOME_LOG_LEVEL: Set the logging level (default: INFO)
  • Valid values: DEBUG, INFO, WARNING, ERROR, CRITICAL
• CONNECTOME_LOG_FORMAT: Set the logging format (default: %(asctime)s - %(name)s - %(levelname)s - %(message)s)

Set DEBUG level for detailed output:

export CONNECTOME_LOG_LEVEL=DEBUG
python -m host.main

Set WARNING level for minimal output:

export CONNECTOME_LOG_LEVEL=WARNING
python -m host.main

Custom log format:

export CONNECTOME_LOG_LEVEL=DEBUG
export CONNECTOME_LOG_FORMAT="%(asctime)s [%(levelname)s] %(name)s: %(message)s"
python -m host.main

In .env file:

CONNECTOME_LOG_LEVEL=DEBUG
CONNECTOME_LOG_FORMAT=%(asctime)s [%(levelname)s] %(name)s: %(message)s

# Debug level - most verbose
CONNECTOME_LOG_LEVEL=DEBUG python -m host.main

# Info level - default
CONNECTOME_LOG_LEVEL=INFO python -m host.main

# Warning level - minimal output
CONNECTOME_LOG_LEVEL=WARNING python -m host.main

# Error level - only errors
CONNECTOME_LOG_LEVEL=ERROR python -m host.main

Individual components and modules also respect the global logging configuration. For even more granular control, you can set logging levels for specific Python loggers:

import logging
logging.getLogger('elements.elements.agent_loop').setLevel(logging.DEBUG)
logging.getLogger('host.event_loop').setLevel(logging.WARNING)

If you're experiencing issues with LLM tool calls, enable DEBUG logging to see detailed tool validation:

# Enable debug logging to see tool validation details
CONNECTOME_LOG_LEVEL=DEBUG python -m host.main

Common tool validation issues:

• Missing JSON schema structure: Tools must have "type": "object" and "properties": {} in parameters
• Invalid required parameters: Parameters listed in "required" must exist in "properties"
• Non-JSON serializable data: All tool parameters must be JSON serializable

Test tool validation:

# Run the tool validation test
python test_tool_validation.py

Check which elements are providing tools:

# Run with DEBUG to see tool aggregation details
CONNECTOME_LOG_LEVEL=DEBUG python -m host.main 2>&1 | grep "tool"

When multiple DM Elements are mounted (different conversations), each provides the same tool names (e.g., send_message). Connectome automatically resolves conflicts using lightweight tool prefixing that fits within LLM provider character limits:

Problem: Anthropic's 64-Character Limit

❌ dm_elem_discord_adapter_1_alice_smith_a1b2c3d4__send_message (60+ chars)

Solution: Smart Prefix Extraction

✅ smith_a1b2__send_message (24 chars)
✅ jones_x9y8__send_message (24 chars)  
✅ brown_f5e4__send_message (24 chars)

How It Works:

• DM Elements: Extracts username + short UUID (alice_smith_a1b2c3d4 → smith_a1b2)
• Other Elements: Uses meaningful prefix + hash (uplink_proxy_abc123 → uplink_2db3)
• Character Sanitization: Removes invalid chars like /, @, spaces, etc. (1148/channel events → 1148_c_e964)
• Automatic Truncation: Ensures tools never exceed 64-character limit
• Collision Resistant: UUID parts prevent conflicts
• Regex Compliant: Uses __ separator to comply with Anthropic's ^[a-zA-Z0-9_-]{1,64}$ constraint
• Prefix Registry: Internal mapping resolves shortened prefixes back to full element IDs during execution

Sanitization Examples:

Original Element ID                     → Sanitized Prefix    → Tool Name
dm_elem_discord_adapter_1_alice@email   → alice_em_a1b2      → alice_em_a1b2__send_message
1148/channel events                     → 1148_c_e964        → 1148_c_e964__send_message  
uplink/shared/channel                   → uplink_2f36        → uplink_2f36__send_message
element:with:colons                     → elemen_38cd        → elemen_38cd__send_message

Agent Context Example:

Alice DM: [Tools: smith_a1b2__send_message, smith_a1b2__edit_message]
Bob DM: [Tools: jones_x9y8__send_message, jones_x9y8__edit_message]  
Channel Uplink: [Tools: uplink_2db3__send_message]

The agent clearly sees which conversation each tool targets while staying within all LLM provider limits.

Key Technical Details:

• Anthropic Constraint: Tool names must match regex ^[a-zA-Z0-9_-]{1,64}$
• DM Element ID Structure: dm_elem_{adapter_id}_{safe_user_id_part}_{short_uuid}
• Prefix Algorithm: Username (≤8 chars) + _ + UUID (4 chars) = smith_a1b2
• Character Sanitization: Invalid chars (/, @, spaces, etc.) replaced with underscores
• Prefix Registry: Maps shortened prefixes back to full element IDs during tool execution
• Tool Parsing: smith_a1b2__send_message → resolve smith_a1b2 → dm_elem_discord_adapter_1_alice_smith_a1b2c3d4
• Agent Context: Shows Alice DM: [Tools: smith_a1b2__send_message, smith_a1b2__edit_message]

Prefix Registry Architecture:

# Registry populated during tool aggregation
_prefix_to_element_id_registry = {
    "smith_a1b2": "dm_elem_discord_adapter_1_alice_smith_a1b2c3d4",
    "jones_x9y8": "dm_elem_discord_adapter_1_bob_jones_x9y8z7w6",
    "uplink_2db3": "uplink_proxy_abc123def456"
}

# Tool execution resolves prefix to full element ID
prefix = "smith_a1b2"  # From "smith_a1b2__send_message"
target_element_id = registry[prefix]  # Returns full element ID
execute_element_action(element_id=target_element_id, action_name="send_message")

1. Create your .env file with required configuration
2. Set desired logging level: export CONNECTOME_LOG_LEVEL=DEBUG
3. Run: python -m host.main

# Logging
CONNECTOME_LOG_LEVEL=DEBUG
CONNECTOME_LOG_FORMAT=%(asctime)s [%(levelname)s] %(name)s: %(message)s

# LLM Configuration
CONNECTOME_LLM_TYPE=litellm
CONNECTOME_LLM_DEFAULT_MODEL=gpt-4o-mini
CONNECTOME_LLM_API_KEY=your_openai_key_here

# Activity Adapters
CONNECTOME_ACTIVITY_ADAPTERS_JSON=[{"id": "discord_adapter_1", "url": "http://localhost:5001", "auth_token": null}]

# Agents - Choose agent loop component type based on your needs
# SimpleRequestResponseLoopComponent: Uses LLM's native tool_call API (default)
# ToolTextParsingLoopComponent: Parses tools from text, supports multiple tools per response
CONNECTOME_AGENTS_JSON=[{"agent_id": "demo_agent", "name": "Demo Agent", "description": "A demonstration agent", "agent_loop_component_type_name": "SimpleRequestResponseLoopComponent", "platform_aliases": {"discord_adapter_1": "DemoBot"}, "handles_direct_messages_from_adapter_ids": ["discord_adapter_1"]}]

# Example with text-parsing agent loop:
# CONNECTOME_AGENTS_JSON=[{"agent_id": "text_parsing_agent", "name": "Text Parsing Agent", "description": "An agent using text-based tool parsing", "agent_loop_component_type_name": "ToolTextParsingLoopComponent", "platform_aliases": {"discord_adapter_1": "TextBot"}, "handles_direct_messages_from_adapter_ids": ["discord_adapter_1"]}]