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.

---