MindX System Architecture Comprehensive Map

I. CORE ARCHITECTURE OVERVIEW

Hierarchical Agent System

MastermindAgent (Top-Level Orchestrator)
    ├── AGInt (Strategic Intelligence Core)
    │   └── BDIAgent (Tactical Reasoning Engine)
    │       └── Tools (Executable Capabilities)
    ├── CoordinatorAgent (Task Management)
    ├── StrategicEvolutionAgent (Campaign Manager)
    └── Specialized Agents (Memory, Guardian, AutoMINDX, etc.)

II. DIRECTORY STRUCTURE & COMPONENTS

Core Primitives (core/)

• bdi_agent.py (45KB): BDI reasoning framework with cognitive loops
• agint.py (15KB): P-O-D-A strategic intelligence with Q-learning
• belief_system.py (8.2KB): Central knowledge storage and management
• id_manager_agent.py (8.5KB): Cryptographic identity and wallet management

Learning & Evolution (learning/)

• strategic_evolution_agent.py (21KB): Campaign manager for system improvements
• self_improve_agent.py (42KB): Safe code modification with rollback mechanisms
• plan_management.py (20KB): Plan execution and state management
• goal_management.py (16KB): Goal hierarchies and priority systems

Evolution Framework (evolution/)

• blueprint_agent.py (9KB): Strategic system analysis and blueprint generation

Agent Ecosystem (agents/)

• memory_agent.py (11KB): Process logging and workspace management
• automindx_agent.py (7.3KB): Dynamic persona generation
• guardian_agent.py (5.3KB): Security and access control
• simple_coder_agent.py (13KB): Basic code generation capabilities

Orchestration Layer (orchestration/)

• mastermind_agent.py (22KB): Primary system orchestrator and CLI interface
• coordinator_agent.py (22KB): Tactical coordination and backlog management

Tool Suite (tools/)

• base_gen_agent.py (26KB): Codebase analysis and documentation
• system_analyzer_tool.py (5.2KB): System health and improvement analysis
• web_search_tool.py (8.8KB): Information gathering capabilities
• system_health_tool.py (12KB): System monitoring and diagnostics
• Various utilities: Registry management, CLI tools, file operations

LLM Integration (llm/)

• llm_factory.py (11KB): Multi-provider LLM management
• model_registry.py (5.3KB): Model capability tracking
• model_selector.py (6.5KB): Intelligent model selection
• Provider handlers: Gemini, Groq, Ollama, multi-model orchestration

System Infrastructure (utils/, monitoring/)

• config.py (4.6KB): Hierarchical configuration management
• logic_engine.py (29KB): Formal reasoning and constraint validation
• performance_monitor.py (15KB): Performance metrics collection
• resource_monitor.py (21KB): System resource monitoring

Operational Scripts (scripts/)

• run_mindx.py (29KB): Primary CLI interface and system entry point
• dmindx.py (19KB): Deployment and management utilities
• audit_gemini.py (11KB): LLM model auditing and validation

III. KEY ARCHITECTURAL PATTERNS

1. BDI (Belief-Desire-Intention) Cognitive Model

• Beliefs: Stored in centralized BeliefSystem with confidence scores
• Desires: Goal hierarchies managed by GoalManager
• Intentions: Action plans executed through PlanManager

2. P-O-D-A (Perceive-Orient-Decide-Act) Loop

• Perceive: System state awareness and input processing
• Orient: Situational analysis and context building
• Decide: Strategic decision making with Q-learning
• Act: Task delegation and execution coordination

3. Safe Self-Modification Framework

• Iteration Directories: Isolated change environments
• Versioned Backups: Automatic rollback capabilities
• Self-Testing: Validation before deployment
• Human-in-the-Loop: Critical decision approval gates

4. Constitutional Governance

• Immutable Rules: Core governance constraints
• Validation Gates: All actions checked against constitution
• Hierarchical Authority: Clear delegation chains
• Audit Trails: Comprehensive action logging

IV. DATA FLOW ARCHITECTURE

Configuration Hierarchy

Environment Variables (Highest Priority)
    ↓
JSON Config Files (/data/config/)
    ↓
YAML Model Configs (/models/)
    ↓
Runtime Defaults (Lowest Priority)

Knowledge Management Flow

Agent Perceptions → BeliefSystem → Strategic Analysis → Action Planning
                       ↓                    ↓              ↓
                Memory Agent ← Process Logging ← Tool Execution

Evolution Campaign Flow

User Directive → MastermindAgent → SystemAnalyzer → BlueprintAgent
                      ↓                   ↓              ↓
              AGInt Strategy ← StrategicEvolutionAgent ← Coordinator
                      ↓                   ↓              ↓
              BDI Planning → SelfImprovementAgent → Code Changes

V. INTEGRATION PATTERNS

Agent Communication

• Hierarchical Delegation: Commands flow down the hierarchy
• Peer Coordination: Lateral communication between specialized agents
• Service Architecture: Shared services (Memory, Guardian, ID Manager)

Tool Integration

• Registry-Based: Tools registered in JSON configuration
• Dynamic Loading: Runtime tool instantiation
• BDI Integration: Tools called as BDI actions
• Parameter Validation: Type-safe tool parameter handling

LLM Provider Management

• Provider Abstraction: Unified interface across providers
• Model Selection: Task-type optimized model routing
• Rate Limiting: API usage management and throttling
• Fallback Chains: Provider redundancy and error handling

VI. SECURITY & GOVERNANCE

Identity Management

• Cryptographic Keys: Ethereum-style key pair generation
• Deterministic IDs: Reproducible agent identities
• Wallet Integration: DAIO-ready financial infrastructure
• Guardian Protection: Access control for sensitive operations

Safety Mechanisms

• Constitutional Validation: Action legality checking
• Rollback Systems: Safe reversion of changes
• Isolation: Sandboxed execution environments
• Monitoring: Comprehensive system health tracking

VII. DEPLOYMENT ARCHITECTURE

Development vs Production

• Mirrored Structure: Identical component organization
• Service Layer: Backend process management
• Configuration Management: Environment-specific settings
• Process Control: PID-based service management

Scalability Design

• Swarm Coordination: Parallel agent execution
• Resource Adaptation: Dynamic resource allocation
• Modular Scaling: Independent component scaling
• Load Distribution: Work distribution across agents

VIII. CURRENT STATE & ROADMAP ALIGNMENT

Implemented Capabilities

• ✅ Complete BDI cognitive architecture
• ✅ Multi-provider LLM integration
• ✅ Safe self-improvement framework
• ✅ Identity and security infrastructure
• ✅ Comprehensive tool ecosystem
• ✅ Strategic evolution planning

Active Development

• 🔄 Great Ingestion repository analysis
• 🔄 Economic engine (FinancialMind)
• 🔄 Constitutional smart contracts
• 🔄 Advanced monitoring systems

Future Evolution

• 🔮 DAIO blockchain integration
• 🔮 Sovereign AI model training
• 🔮 Physical world APIs
• 🔮 Autonomous economic operations

IX. TECHNICAL METRICS

Codebase Scale

• Total Components: 150+ Python files
• Core Architecture: ~50KB fundamental systems
• Learning Systems: ~100KB evolution capabilities
• Tool Ecosystem: ~100KB executable capabilities
• LLM Integration: ~80KB multi-provider support

Complexity Measures

• Agent Layers: 4-tier hierarchy
• Configuration Tiers: 5-level precedence
• Integration Points: 20+ major interfaces
• Safety Systems: Multi-layer validation

This architecture represents a sophisticated, self-improving AI system with clear separation of concerns, robust safety mechanisms, and a clear path toward autonomous operation while maintaining human oversight and constitutional governance.

---