CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

mindX is an autonomous multi-agent orchestration system implementing a Belief-Desire-Intention (BDI) cognitive architecture. It's a "Godel-machine" - a self-improving AI system with Ethereum-compatible wallet authentication and LLM integration (Mistral, Gemini, Groq, Ollama, OpenAI, Anthropic, Together AI).

Documentation: docs/NAV.md is the master navigation hub — 40+ sections covering all agents, tools, governance, inference, memory, deployment. docs/SCHEMA.md is the instruction layer — how to maintain, cross-reference, and evolve the docs. Start with NAV.

VPS Deployment: agents/hostinger_vps_agent.py manages mindx.pythai.net via three MCP channels: SSH, Hostinger API, and mindX Backend HTTPS. See agents/hostinger.vps.agent for full parameters.

Development Commands

Setup

cp .env.sample .env  # Add API keys (MISTRAL_API_KEY, GEMINI_API_KEY, etc.)
pip install -r requirements.txt

Running the Application

# Recommended: Full web interface (frontend + backend)
./mindX.sh --frontend

Custom ports
./mindX.sh --frontend --frontend-port 3001 --backend-port 8001

Interactive setup with API key configuration
./mindX.sh --frontend --interactive

Direct backend only
uvicorn mindx_backend_service.main_service:app --reload --port 8000

API interactions: When the backend is running, http://localhost:8000/docs (FastAPI Swagger UI) shows all API endpoints and lets you try requests and inspect schemas—very useful for auditing and integrating with the API.

Testing

# Run all tests
python -m pytest tests/

Run specific test file
python -m pytest tests/test_mistral_chat_completion_api.py -v

With coverage
python -m pytest tests/ --cov=mindx --cov-report=term-missing

Code Quality

ruff format .      # Format code
ruff check . --fix # Lint
mypy mindx/        # Type checking

Architecture

Orchestration Hierarchy

CEO Agent (board-level strategic planning)
    ↓
MastermindAgent (singleton, strategic orchestration center)
    ↓
CoordinatorAgent (infrastructure management, autonomous improvement)
    ↓
Specialized Agents (BDI-based cognitive agents)

Key Directories

• orchestration/ - MastermindAgent, CoordinatorAgent, CEOAgent
• core/ - BDI reasoning engine (bdi_agent.py), AGInt cognitive engine (agint.py), identity management (id_manager_agent.py)
• agents/ - Specialized agents (guardian, memory, automindx, simple_coder, persona, avatar)
• api/ - Multi-provider LLM API layer (llm_routes.py, provider-specific APIs)
• learning/ - Self-improvement (strategic_evolution_agent.py, self_improve_agent.py)
• llm/ - LLM factory pattern with provider-specific handlers
• tools/ - 29+ tools extending BaseTool (see docs/TOOLS_INDEX.md for full list)
• mindx_backend_service/ - FastAPI backend (main_service.py is ~95KB)
• mindx_frontend_ui/ - Express.js frontend with xterm.js terminal and window manager
• DAIO/contracts/ - Solidity smart contracts (Foundry-based)

Core Patterns

Singleton with async factory (used by most agents):

@classmethod
async def get_instance(cls, config_override=None, kwargs):
    async with cls._lock:
        if cls._instance is None:
            cls._instance = cls(...)
        return cls._instance

All operations are async - the system uses async/await throughout.

Tool pattern - All tools extend BaseTool with execute() and get_schema() methods.

LLM Integration

• Factory pattern in llm/llm_factory.py
• Provider handlers: mistral_handler.py, gemini_handler.py, groq_handler.py, ollama_handler.py
• Provider registry: data/config/provider_registry.json (Gemini, OpenAI, Anthropic, Mistral, Together, Ollama)
• Model configs in models/.yaml
• Rate limiting via rate_limiter.py

Identity System

python manage_credentials.py store gemini_api_key "KEY"    # Store
python manage_credentials.py list                          # List IDs
python manage_credentials.py providers                     # Show all provider IDs

Per-provider config templates: config/providers/.env (13 providers)

Vault routes: /vault/credentials/status, /vault/credentials/list, /vault/credentials/providers

Configuration

Priority: Environment variables (MINDX_ prefix) > BANKON Vault > JSON configs (data/config/) > YAML model files (models/) > .env file

Key environment variables (set via vault or .env):

• GEMINI_API_KEY, GROQ_API_KEY, MISTRAL_API_KEY - LLM providers
• OPENAI_API_KEY, ANTHROPIC_API_KEY, TOGETHER_API_KEY - Additional LLM providers
• DEEPSEEK_API_KEY, COHERE_API_KEY, PERPLEXITY_API_KEY - Extended providers
• REPLICATE_API_TOKEN, STABILITY_API_KEY, FIREWORKS_API_KEY - Media/inference
• MINDX_LOGGING_LEVEL - DEBUG/INFO/WARNING/ERROR
• MINDX_COORDINATOR_AUTONOMOUS_IMPROVEMENT_ENABLED - Enable autonomous loops

Memory System

Located in data/memory/:

• stm/ - Short-term memory (per-session)
• ltm/ - Long-term knowledge base
• workspaces/ - Agent working areas

Managed by agents/memory_agent.py with belief system integration.

Interoperability Protocols

A2A (Agent-to-Agent)

• tools/a2a_tool.py - Standardized agent-to-agent communication
• Agent discovery via agent cards (model cards)
• Cryptographic message signing and verification
• Protocol versions: 1.0, 2.0

MCP (Model Context Protocol)

• tools/mcp_tool.py - Structured context provision for agent actions
• Context types: tool definitions, action context, environment state, capability descriptions
• Enables rich, structured context for better agent decision-making

Cognitive Extensions

PersonaAgent (agents/persona_agent.py)

• Enables agents to adopt different personas with distinct cognitive patterns
• Personas include: beliefs, desires, communication styles, behavioral traits
• Roles: expert, worker, meta, community, marketing, development, governance

AvatarAgent (agents/avatar_agent.py)

• Generates visual avatars for agents/participants
• Integrates with PromptTool for avatar generation prompts
• Supports multiple providers: DALL-E, Stability AI, Replicate
• Styles: realistic, cartoon, anime, cyberpunk, etc.

PromptTool (tools/prompt_tool.py)

• Manages prompts as first-class infrastructure
• Prompts are versioned, stored in memory, and executable
• Types: system, agent, user, template, inception, instruction