Document Version: 2.0
Target Audience: System Architects, Senior Developers, AI Researchers
The MindX system is a multi-layered, hierarchical cognitive architecture designed for constitutionally-bound autonomous operation. It is not a monolithic application but a society of specialized agents, each operating at a different level of abstraction and timescale. This design promotes security, scalability, and observability.
The primary hierarchy is as follows:
MastermindAgent (The Strategic Core / "Soul"): The apex agent. Operates on a long-term strategic horizon (hours, days, weeks). Its purpose is to drive the evolution of the system itself by assessing its capabilities, conceptualizing new tools or agents, and initiating development campaigns.
CoordinatorAgent (The Kernel / "Autonomic Nervous System"): The central operating system. It manages agent registration, monitors system-wide health (resources, performance), and provides a low-level API for inter-agent communication and task verification. It operates on a near-real-time basis.
AGInt (The Strategic Mind / "Application Layer"): A high-level application running on the CoordinatorAgent OS. It receives broad directives (e.g., from Mastermind or a human operator) and breaks them down into major operational phases. It manages the lifecycle of a complex project, operating on a medium-term horizon (minutes, hours).
BDIAgent (The Tactical Brain / "Function Library"): A pure, logical, task-execution engine. It receives a well-defined task from an AGInt and uses its internal LLM to generate and execute a detailed, short-term plan to accomplish it. It operates on a short-term horizon (seconds, minutes).
SimpleCoder (The Hands / "Device Driver"): The lowest-level tool. It provides a secure, stateful, sandboxed interface to the host filesystem and shell. It is stateless between BDIAgent calls but maintains state within a single logical plan (e.g., CWD, active venv).
The Core Execution Loop: From Mastermind to Codebase
This section details the primary data and control flow for a self-improvement campaign, the system's most important function.
Step 1: Mastermind - Strategic Campaign Initiation
The MastermindAgent's autonomous loop is the catalyst for all evolution.
Trigger: The _autonomous_worker task wakes up.
Directive Formulation: It calls self.launch_campaign() with a high-level, self-reflective directive like "Proactively evolve the MindX system...".
BDI Instantiation: Inside launch_campaign, a subordinate BDIAgent is given this directive as its primary goal. This BDIAgent is unique to the Mastermind and has a special set of registered "meta-actions" (e.g., _bdi_assess_tool_suite).
BDI Planning: The BDIAgent's LLM, prompted with its goal, might generate a plan like:
[
{"type": "OBSERVE_SYSTEM_STATE", "params": {}},
{"type": "ASSESS_TOOL_SUITE", "params": {"system_state": "..."}},
{"type": "PROPOSE_TOOL_STRATEGY", "params": {"assessment": "..."}},
{"type": "CONCEPTUALIZE_NEW_TOOL", "params": {"identified_need": "..."}},
{"type": "INITIATE_TOOL_DEVELOPMENT", "params": {"tool_concept": "..."}}
]
Step 2: Mastermind BDI -> Coordinator - Tasking the System
The plan execution leads to a critical handoff.
Action Execution: The BDIAgent executes the INITIATE_TOOL_DEVELOPMENT action.
_bdi_initiate_tool_development: This method is called. Its sole purpose is to format a structured request and send it to the CoordinatorAgent.
Interaction Creation: It creates a formal Interaction object with InteractionType.COMPONENT_IMPROVEMENT. The content is a high-level description, but the crucial data is packed into the metadata dictionary. This includes the full JSON specification for the new tool generated in the CONCEPTUALIZE_NEW_TOOL step.
Step 3: Coordinator -> SelfImprovementAgent (SIA) - The Code Generation
The CoordinatorAgent now orchestrates the actual code modification. (Note: The current implementation calls a CLI script, self_improve_agent.py. This represents the SIA).
Interaction Processing: The CoordinatorAgent's process_interaction method routes the COMPONENT_IMPROVEMENT type to _process_component_improvement_cli.
Subprocess Invocation: It constructs a precise command-line call to the self_improve_agent.py script. The large JSON tool specification is written to a temporary context file and passed via the --context-file argument.
The SIA's Role: The self_improve_agent.py script (not detailed here, but its function is implied) is a specialized agent that:
Reads the target file path.
Reads the detailed specification from the context file.
Uses its own LLM, fine-tuned for code generation, to write or modify the Python code for the new tool.
It may run tests, create backups, and generate diffs.
Crucially, it outputs a structured JSON result to stdout.
Result Capture: The CoordinatorAgent captures the stdout from the SIA process, parses the JSON result, and stores it as the response to the Interaction.
Step 4: Mastermind - Registration and Closing the Loop
Result Propagation: The BDIAgent receives the SUCCESS result from the CoordinatorAgent.
Final Action: The BDIAgent's plan can now proceed to the final step: REGISTER_TOOL.
_bdi_register_tool: This method takes the tool specification (which may have been updated by the SIA process) and writes it into the official_tools_registry.json file.
Campaign Completion: The BDIAgent's plan finishes. The MastermindAgent's launch_campaign method concludes, and the result is logged in the mastermind_campaign_history.json.
The system has successfully conceived of a gap in its own capabilities, designed a solution, orchestrated its creation, and integrated the result back into its core configuration. This is a complete, autonomous evolutionary cycle.
Hierarchical State Management
State is managed at the appropriate level of abstraction:
SimpleCoder: Manages low-level, ephemeral session state (CWD, active venv). This state is "real" but transient.
BDIAgent: Manages tactical state (the current plan, the current goal). This state is logical and drives short-term action.
AGInt: Manages operational state (the result of the last major action, high-level situational awareness). This is more abstract.
MastermindAgent: Manages strategic state (the official tool registry, campaign history, long-term objectives). This state is persistent and defines the SIO's identity.
The entire system is built on asyncio. This is not optional; it is essential for an agent-based system.
asyncio.Task is used to run primary loops (_cognitive_loop, _autonomous_worker) in the background without blocking.
asyncio.create_subprocess_exec is used for all external process calls (SIA, shell commands in SimpleCoder), ensuring the main agent loops remain responsive while waiting for I/O.
asyncio.Lock is used to protect access to shared resources and ensure singleton integrity (e.g., MastermindAgent.get_instance).
All executable components, from SimpleCoder to potentially the agents themselves, should inherit from a common BaseTool class. This enforces a standard interface for execution. The BDIAgent's _action_execute_tool method relies on this contract: every tool must have an async def execute(**kwargs) -> Dict method that returns a structured dictionary containing at least a status key. This allows the BDIAgent to treat all tools polymorphically.
Hardcoding is minimized. The system's behavior is defined in configuration:
SimpleCoder.v6.config.json: Defines the sandbox path and the shell command allowlist.
official_tools_registry.json: This is a critical configuration file managed by the Mastermind itself. It defines the available tools for all subordinate agents.
Config Class (utils/config.py): Provides a centralized way to manage application-level settings like timeouts, LLM model preferences, and feature flags.
Security is the foremost concern in a system designed for autonomy.
The Sandbox is Absolute: The SimpleCoder's filesystem jail is the most critical security boundary. The _resolve_and_check_path logic, using pathlib.resolve() and is_relative_to(), is the cornerstone of preventing the agent from affecting the host system.
Command Allowlisting: The run command in SimpleCoder is restricted to an explicit list of commands. The agent cannot execute arbitrary binaries.
Shell Bypass: Wherever possible, native Python functions (pathlib for file I/O) are used instead of shell commands (cat, mkdir), eliminating injection risks.
Hierarchical Trust: The Mastermind has the highest level of trust and can modify its own tools registry. The CoordinatorAgent can trigger code modifications via the SIA.
The BDIAgent and AGInt can only operate through the tools and APIs provided to them. Trust is not uniform; it is layered.
This multi-layered, defense-in-depth approach is designed to ensure that even if a high-level agent formulates a "malicious" plan (due to LLM error), the lower-level, hardened components will refuse to execute it.