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

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

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):

Memory System

Located in data/memory/:

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

Interoperability Protocols

A2A (Agent-to-Agent)

MCP (Model Context Protocol)

Cognitive Extensions

PersonaAgent (agents/persona_agent.py)

AvatarAgent (agents/avatar_agent.py)

PromptTool (tools/prompt_tool.py)