mindXdashboard/docs/book/journal/api/dojo/inference/governance/origin
philosophymanifestothesisoriginwhitepaperataraxiaroadmappress|archovervieworchestrationcodebasehierarchycore|agentsmindXagentceomastermindbdievolutionauthorall
govdaiocivilizationidentitysecurity|memorypgvectorembedaglmmemory|inferencevllmollamamistralgemini|timeoracle
toolsindextoolsa2amcpshell|publishauthoragentbookjournal|deployproductionsecuritymonitoring|apireferenceswagger|learnusageguidehackathon
codebase_map.md · 17.3 KB

MindX Codebase Comprehensive Architecture Map

Last Updated: December 2024 Purpose: Complete system comprehension and architectural overview of the MindX Augmentic Intelligence codebase

I. ARCHITECTURAL PHILOSOPHY & DESIGN PRINCIPLES

Core Design Philosophy

MindX is architected as a hierarchical multi-agent system with clear separation of concerns:

Key Architectural Patterns

  1. BDI (Belief-Desire-Intention) Model: Core reasoning framework
  2. P-O-D-A Loop: Perceive-Orient-Decide-Act cognitive cycle
  3. Agent Composition: Hierarchical delegation and specialization
  4. Safe Self-Modification: Iterative improvement with rollback mechanisms
  5. Constitutional Framework: Immutable governance rules and validation

II. CORE SYSTEM COMPONENTS

Core Primitives (core/)

1. bdi_agent.py (45KB, 898 lines)

- run(): Main cognitive loop (max 100 cycles) - plan(): Goal decomposition and action planning - execute_current_intention(): Action execution - deliberate(): Strategic decision making

2. agint.py (15KB, 284 lines)

- _cognitive_loop(): P-O-D-A cycle implementation - _perceive(), _orient_and_decide(), _act(): Cognitive phases - _delegate_task_to_bdi(): Task delegation to BDI agents

3. belief_system.py (8.2KB, 210 lines)

- add_belief(), get_belief(), update_belief(): Knowledge management - query_beliefs(): Knowledge retrieval with filtering

4. id_manager_agent.py (8.5KB, 178 lines)

- Ethereum-style key pair generation - Deterministic agent identity creation - Secure private key storage in environment variables - Public address management and verification

III. LEARNING & EVOLUTION SYSTEMS

Learning Layer (learning/)

1. strategic_evolution_agent.py (21KB, 392 lines)

1. Blueprint generation via BlueprintAgent 2. Strategic plan creation and execution 3. Coordinator backlog seeding 4. Campaign monitoring and recovery

2. self_improve_agent.py (42KB, 524 lines)

- Iteration directories for isolated changes - Versioned backups and rollback capability - Self-testing with timeout protection - LLM critique and validation - analyze_target(): Code analysis for improvement opportunities - implement_improvement(): Safe code modification - evaluate_improvement(): Post-change validation - run_self_improvement_cycle(): Complete improvement workflow

3. plan_management.py (20KB, 388 lines)

4. goal_management.py (16KB, 318 lines)

Evolution Layer (evolution/)

1. blueprint_agent.py (9KB, 190 lines)

- Holistic system state analysis - Strategic blueprint generation - BDI todo list creation for coordinators - LLM-driven strategic planning

IV. AGENT ECOSYSTEM

Specialized Agents (agents/)

1. memory_agent.py (11KB, 265 lines)

- Agent workspace creation and management - Process trace logging with metadata - Terminal output logging - Data directory structure management

2. automindx_agent.py (7.3KB, 136 lines)

- Role-based persona generation - Agent behavior customization - Dynamic agent deployment support

3. guardian_agent.py (5.3KB, 125 lines)

- Challenge-response authentication - Private key access brokering - Security policy enforcement

4. simple_coder_agent.py (13KB, 232 lines)

V. ORCHESTRATION LAYER

System Orchestrators (orchestration/)

1. mastermind_agent.py (22KB, 409 lines)

- manage_mindx_evolution(): High-level evolution management - manage_agent_deployment(): Agent creation and deployment - command_augmentic_intelligence(): Primary command interface

2. coordinator_agent.py (22KB, 439 lines)

- Improvement backlog processing - Agent interaction management - Resource coordination - Task delegation to SelfImprovementAgent

VI. TOOL ECOSYSTEM

Executable Capabilities (tools/)

System Analysis & Intelligence

Infrastructure & Operations

Information & Communication

Development & Analysis

VII. LLM INTEGRATION LAYER

Language Model Infrastructure (llm/)

Core LLM Framework

Provider Implementations

VIII. MONITORING & INFRASTRUCTURE

System Monitoring (monitoring/)

Core Utilities (utils/)

IX. OPERATIONAL SCRIPTS

System Entry Points (scripts/)

1. run_mindx.py (29KB, 478 lines)

- evolve <directive>: Initiate evolution campaigns - deploy <directive>: Agent deployment - mastermind_status: System status reporting - analyze_codebase <path>: Codebase analysis - id_create/id_list/id_deprecate: Identity management

2. dmindx.py (19KB, 288 lines)

3. audit_gemini.py (11KB, 206 lines)

4. run_mindx_coordinator.py (12KB, 206 lines)

X. DATA & CONFIGURATION ARCHITECTURE

Configuration Management (data/config/)

Model Capabilities (models/)

Persistent Data Architecture (data/)

data/
├── config/                 # System configuration files
├── logs/                   # Runtime and process logs
├── memory/                 # Agent workspaces and process traces
│   ├── action/            # Action execution logs
│   └── agent_workspaces/  # Individual agent working directories
├── mastermind_work/       # Strategic campaign data
├── id_manager_work/       # Identity management data
├── gemini/               # LLM audit reports
└── improvement_backlog.json  # System improvement queue

XI. SYSTEM INTERACTION FLOWS

Primary User Interaction Flow

  1. User Command → run_mindx.py CLI
  2. Command Parsing → MastermindAgent method selection
  3. Strategy Formation → AGInt P-O-D-A loop
  4. Tactical Planning → BDI agent goal decomposition
  5. Execution Coordination → CoordinatorAgent task management
  6. Tool Execution → Specialized tool activation
  7. Result Integration → BeliefSystem knowledge update

Evolution Campaign Flow

  1. Directive Input → MastermindAgent.manage_mindx_evolution()
  2. System Analysis → SystemAnalyzerTool execution
  3. Blueprint Generation → BlueprintAgent strategic planning
  4. Campaign Creation → StrategicEvolutionAgent coordination
  5. Backlog Population → CoordinatorAgent task queuing
  6. Code Modification → SelfImprovementAgent execution
  7. Validation & Integration → Safety checks and belief updates

Autonomous Operation Flow

  1. Autonomous Loop Triggers → ConfigurationDriven intervals
  2. System Health Assessment → Monitor integration
  3. Improvement Identification → Analysis tool execution
  4. Task Prioritization → Backlog management
  5. Safe Execution → Iterative improvement with rollback
  6. Learning Integration → Q-learning and lessons learned

XII. KEY INTEGRATION PATTERNS

Agent Communication Patterns

Data Flow Patterns

Safety & Governance Patterns

XIII. DEPLOYMENT & PRODUCTION CONSIDERATIONS

Production Deployment Structure (mindx_deployment/)

Security Architecture

Scalability Considerations

XIV. CODEBASE METRICS & COMPLEXITY

Scale Analysis

Architectural Complexity

XV. DEVELOPMENT & EVOLUTION ROADMAP ALIGNMENT

Current Capabilities (Phase I Foundation)

Active Development (Phase II-III)

Future Evolution (Phase IV-VI)

This comprehensive map represents the current state of the MindX Augmentic Intelligence codebase as a sophisticated, self-improving AI system with clear architectural separation, robust safety mechanisms, and a path toward digital sovereignty. The system demonstrates significant engineering complexity while maintaining modularity and extensibility for future evolution.

All DocumentsDocument IndexThe Book of mindXImprovement JournalAPI Reference