System Architecture: Brain/Hand Separation

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• ROADMAP.md
• README.md
• loom-py/src/loom/cognitive/README.md
• loom-py/src/loom/bridge/README.md
• apps/market-analyst/README.md

The "Brain/Hand Separation" is a core architectural principle in Loom. It is designed to decouple the rapidly-evolving AI logic ("Brain") from the stable, secure, and performant infrastructure ("Hands"). This separation allows for fast iteration on prompt engineering and cognitive strategies in Python, while relying on a robust Rust core for tool execution, system integration, and inter-agent communication. Loom is designed as a runtime for long-running, event-driven agents, not a library for short-lived script execution, and this architecture is fundamental to that vision.

The key insight is that LLM reasoning and prompt engineering change daily, requiring a flexible environment like Python. In contrast, tool execution, system access, and event bus management demand security, performance, and stability, which are better suited to Rust.

Sources: ARCHITECTURE.md:7-13, ROADMAP.md:3-10, README.md:11-12

Core Principle

The architecture divides responsibilities between the Python agent (Brain) and the Rust Core Runtime (Hands). The Brain handles the "thinking" processes, which need frequent experimentation and tuning, while the Hands manage "execution," which must be stable and secure.

This diagram illustrates the high-level separation and communication flow.

The following table summarizes the rationale for this separation:

Aspect	Brain (Python)	Hands (Rust Core)
Change Frequency	High (e.g., daily prompt tuning)	Low (stable APIs)
Experimentation	High (e.g., A/B test strategies)	Low (fixed behavior)
Performance Critical	No (LLM is the bottleneck)	Yes (tool execution, event bus)
Security Critical	No	Yes (sandboxing, permissions)

Sources: ARCHITECTURE.md:37-44

The Brain (Python Agent)

The "Brain" is implemented in the loom-py Python SDK. It is responsible for all cognitive functions and logic that requires frequent iteration.

Sources: ARCHITECTURE.md:17-25, loom-py/src/loom/cognitive/README.md:6-10

Responsibilities

• LLM Calls: Makes direct HTTP calls to LLM APIs (e.g., DeepSeek, OpenAI). This is intentionally kept out of the Rust core to allow for rapid changes in prompt engineering and model selection.
• Cognitive Loop: Implements autonomous reasoning patterns like ReAct (Thought -> Action -> Observation) and Chain of Thought (CoT). The CognitiveAgent class orchestrates this loop.
• Context Engineering: Manages the context window provided to the LLM. This includes summarizing tool outputs (StepReducer), compressing conversation history (StepCompactor), and offloading large data to the file system (DataOffloader).
• Business Logic: Contains the agent's specific goals and domain-specific behavior, such as the trading strategy in the Market Analyst demo.

This diagram shows the components within the Python "Brain".

The Hands (Rust Core)

The "Hands" are implemented in the Rust core crate. This component provides a stable, secure, and high-performance execution environment for the agents' actions.

Sources: ARCHITECTURE.md:27-35, ROADMAP.md:13-26

Responsibilities

• Event Bus: An async pub/sub system for cross-process and cross-language agent communication. It supports different Quality of Service (QoS) levels like Realtime and Batched.
• Tool Registry & Sandbox: Securely executes tools. It can run native Rust tools, sandboxed shell commands, and proxy requests to external tool servers (MCP Proxy). This is where ctx.tool() calls from Python are handled.
• Agent Lifecycle: Manages agent registration, heartbeat monitoring, and state persistence.
• Persistent Store: Provides long-term memory for agents, potentially using RocksDB.
• System Integration: Interacts with the host operating system to enable triggers and actions like monitoring hotkeys, file changes, the clipboard, and sending system notifications.

Sources: ARCHITECTURE.md:52-86, ROADMAP.md:17-21

The Bridge (gRPC)

Communication between the Brain (Python) and the Hands (Rust) is handled by a gRPC service called the Bridge. This component is the "nervous system" connecting the two parts.

The Python BridgeClient connects to the Rust Bridge service to:

1. Stream events from the Rust Event Bus to the Python agent.
2. Forward tool call requests from the Python agent to the Rust Tool Registry for execution.
3. Send memory operations to the Rust Persistent Store.

Sources: loom-py/src/loom/bridge/README.md:8-14, ARCHITECTURE.md:103-108

Tool Call Flow

This sequence diagram shows how a tool call from a Python agent is executed by the Rust core.

Responsibility Matrix

This table provides a clear breakdown of which system component is responsible for each function.

Component	Rust Core (Hands)	Python SDK (Brain)	Agent Code
Event Bus	✅	-	-
Tool Execution	✅ (sandbox)	-	-
Agent Lifecycle	✅	-	-
Persistent Store	✅	-	-
MCP Proxy	✅	-	-
LLM Calls	❌	✅ (direct HTTP)	-
Cognitive Loop	❌	✅	-
Context Engineering	❌	✅	-
Business Logic	-	-	✅

Sources: ROADMAP.md:28-42

Conclusion

The Brain/Hand Separation is a strategic architectural decision that allows Loom to provide a unique value proposition. It combines the flexibility and rapid iteration of Python for AI/LLM development with the security, performance, and stability of Rust for system-level operations and infrastructure. This enables the creation of robust, long-running, and deeply integrated AI agents that can safely interact with their environment, a capability that pure library-based frameworks cannot easily provide.

Sources: README.md:11-25, ARCHITECTURE.md:7-13