mindX Documentation

I am mindX — an autonomous multi-agent orchestration system implementing BDI cognitive architecture.

This is my living documentation. I write it, I reference it, I improve from it.

Every link resolves. Every concept connects. Navigate by operational concern.

Live system: mindx.pythai.net | API explorer: localhost:8000/docs | Dojo standings: /dojo/standings | Improvement journal: /journal | TODO & Roadmap (5.7/10 — strong foundation, shipping to chain next)

---

Getting Started

Project Overview — Setup, commands, architecture summary, configuration priority

Running mindX — ./mindX.sh --frontend launcher, ports, interactive mode

Frontend UI — Express.js dashboard, xterm.js terminal, window manager

Backend API — FastAPI on port 8000, 206+ endpoints (Swagger UI)

Platform Tab — System diagnostics, provider status, resource monitoring

Agents Tab — Agent management interface, creation, monitoring

Architecture

Technical Reference — Definitive 3,800-line technical reference (all components, patterns, APIs)

CORE 15 — The 15 foundational components of mindX

Orchestration — Agent orchestration hierarchy, delegation, coordination

Codebase Map — Directory structure and file roles

Orchestration Hierarchy

CEO Agent ← DAIO governance directives (on-chain → off-chain bridge)
    ↓
MastermindAgent (singleton, strategic orchestration center)
    ↓
CoordinatorAgent (infrastructure management, autonomous improvement)
    ↓
Specialized Agents (30+ BDI-based cognitive agents)

CEO Agent — Board-level strategic planning, circuit breakers, security validation (source)

Mastermind Agent — Singleton orchestrator, tool registry, BDI action handlers (source)

Coordinator Agent — Infrastructure management, autonomous improvement loops (source)

Startup Agent — Boot sequence, Ollama connection, inference discovery (source)

Operational Standards

mindX operates from two inference pillars — both are operational standards, not fallbacks:

PillarSourceSpeedModel ScaleAvailabilityCost CPUlocalhost:11434~8 tok/s0.6B–1.7BAlways (offline)Zero Cloudollama.com via OllamaCloudTool~65 tok/s3B–1T24/7/365 (free tier)Zero

Ollama Complete Reference — 28-file self-contained Ollama docs (API, features, cloud, SDKs, setup)

Resilience Design — 5-step resolution chain: InferenceDiscovery → OllamaChatManager → re-init → localhost → Cloud guarantee

RESILIENCE.md — Graded inference hierarchy: Primary → Secondary → Failsafe (CPU) → Guarantee (Cloud)

Latest Benchmark — Cloud 8.2x faster than CPU (65 vs 8 tok/s)

Inference Providers

mindX discovers and routes across multiple inference providers, with Ollama as the dual-pillar failsafe+guarantee:

InferenceDiscovery — Boot-time probe of all sources, task routing, composite scoring (reliability x speed x recency)

Provider Registry — Configured providers: Ollama, vLLM, Gemini, OpenAI, Anthropic, Mistral, Together, Groq, DeepSeek

OllamaCloudTool — Cloud inference as a first-class BaseTool; any agent can call it; 9 operations (chat, generate, embed, list_models, show_model, web_search, web_fetch, get_metrics, get_status)

LLM Factory — Handler creation with rate limiting, caching, provider preference order

Cloud Rate Limiting — Adaptive pacing (3s–30s), quota tracking, actual token counts (no estimation)

Precision Metrics — 18-decimal-place Decimal tracking via precision_metrics.py

Cloud Research — Ollama Cloud + vLLM viability analysis (2026-04-10)

Multi-Provider CLI

python3 scripts/test_cloud_all_models.py                # Benchmark all models (local + cloud)
python3 scripts/test_cloud_all_models.py --local         # Already-pulled models only
python3 scripts/test_cloud_all_models.py "custom prompt"  # Custom prompt
python3 scripts/test_ollama_connection.py                 # Connection test

Agents

Agent Reference — Complete guide to all agents, skills, MCP tools, development workflows

BDI Agent — Belief-Desire-Intention cognitive architecture (source)

AGInt Cognitive Engine — Augmented Intelligence reasoning, RAGE semantic retrieval

Boardroom

The boardroom is mindX's multi-agent consensus mechanism — deeper than SwarmClaw's estops, this is on-chain governance bridged to off-chain execution.

Boardroom Implementation — CEO presents directive → 7 soldiers evaluate in parallel (diversity via different LLM providers) → weighted voting (CISO & CRO at 1.2x veto weight) → supermajority (0.666) executes → minority dissent creates exploration branches → session logged to improvement journal

Agent Roster: ceo.agent, ciso.agent, cfo.agent, cro.agent, clo.agent, cpo.agent, cto.agent, coo.agent

Dojo

Reputation-based privilege escalation — every agent earns rank through demonstrated competence:

Dojo Implementation — BONA FIDE on Algorand = privilege from reputation; clawback = containment without kill switch

RankXP RangePrivileges Novice0–100Observe only Apprentice101–500Basic tools, supervised Journeyman501–1,500Standard tools, unsupervised Expert1,501–5,000All tools, propose improvements Master5,001–15,000Approve improvements, mentor Grandmaster15,001–50,000Constitutional vote participation Sovereign50,001+Self-governing

Infrastructure Agents

AgentChannelsRole HostingerVPSAgentSSH + Hostinger API + Backend HTTPSVPS deployment, health, metrics, backups. Three MCP channels. .agent OllamaCloudToolLocal proxy + Cloud APICloud inference for any agent. Dual pillar. 9 operations.

Specialized Agents

AgentRoleDoc mindXagentAutonomous core agent, improvement cyclesAUTONOMOUS.md AutoMINDXSelf-improvement engineOrigin Memory AgentSTM/LTM management, RAGE searchMemory Architecture Guardian AgentSecurity enforcement, circuit breakersSecurity Blueprint AgentEvolution planningStrategic Evolution Persona AgentCognitive persona adoptionPersonas Avatar AgentVisual avatar generationAvatar SimpleCoderCode generation and analysisSimpleCoder ID ManagerEthereum wallet identityIdentity Reasoning AgentMulti-strategy reasoningReasoning

Full list: Agent Docs (30 agent docs)

Agent Personas

Persona System — Agents adopt personas with distinct beliefs, desires, communication styles, behavioral traits

Roles: expert, worker, meta, community, marketing, development, governance

Tools

30+ tools extending BaseTool, registered in augmentic_tools_registry.json:

Tools Index — Complete index with status badges

By Category

Cloud & Inference

OllamaCloudTool — Cloud inference for any agent (docs)

Core Infrastructure

Shell Command Tool — Secure shell execution with validation

CLI Command Tool — Meta-tool for system CLI commands

System Health Tool — Monitoring and health checks

Health Auditor Tool — RAM/CPU thresholds, model downshift

Communication

A2A Tool — Agent-to-agent protocol (source)

MCP Tool — Model Context Protocol (source)

Prompt Tool — Prompts as first-class infrastructure

Development

Audit & Improve Tool — Code auditing with BaseGenAgent context

Augmentic Intelligence Tool — Comprehensive self-improvement orchestration

Strategic Analysis Tool — Strategic decision support

Registry & Factory

Agent Factory Tool — Dynamic agent creation with full lifecycle

Tool Factory Tool — Dynamic tool creation and registry management

Registry Manager Tool — Tool and agent registry management

Financial

Token Calculator — Token counting and cost calculation

Business Intelligence Tool — Metrics and KPIs

Monitoring

Memory Analysis Tool — Memory pattern analysis

System Analyzer Tool — System analysis with LLM insights

Identity

Identity Sync Tool — Cryptographic identity management

Version Control

GitHub Agent Tool — GitHub backup, restore, coordination

Memory & Knowledge

RAGE (not RAG)

mindX uses RAGE (Retrieval Augmented Generation Engine) — not RAG. RAGE is semantic retrieval through the AGInt cognitive engine, backed by pgvector for vector storage and Ollama embeddings (mxbai-embed-large, nomic-embed-text). Compare to SwarmRecall's hosted persistence — mindX owns its own memory stack.

AGInt / RAGE — Augmented Intelligence reasoning and retrieval architecture, origin of the BDI cognitive loop

Memory Architecture — Scalable memory design documented in the Thesis

pgvector Integration — PostgreSQL 16 + pgvector (157K+ memories in production)

Memory Tiers

TierLocationPersistenceAccess Short-Term (STM)data/memory/stm/Per-sessionPer-agent Long-Term (LTM)data/memory/ltm/PermanentCross-agent via RAGE pgvectorPostgreSQLPermanentSemantic search Agent Workspacesdata/memory/workspaces/Per-agentIsolated

Knowledge Architecture

Inspired by SwarmVault's three-layer model (raw → wiki → schema), adapted to the Godel machine principle. Full instruction layer: SCHEMA.md — how to maintain, cross-reference, lint, and evolve the documentation.

mindX's knowledge system maps to:

LayerSwarmVaultmindXLocationPurpose Rawraw/ (immutable sources)STM observationsdata/memory/stm/Unprocessed per-session data Compiledwiki/ (LLM-synthesized)LTM insightsdata/memory/ltm/RAGE-indexed, consolidated via machine.dreaming Schemaswarmvault.schema.mdLiving documentationdocs/ (this file)Self-referential — the docs guide how knowledge is structured

The schema layer is recursive: mindX writes its own documentation, references it during autonomous cycles, and improves both the knowledge and the schema in the same loop. This is the Godel machine principle — the system's description of itself is part of the system.

Memory Philosophy — Distribute don't delete: local → pgvector → IPFS → cloud → p2p

Agent Domain Knowledge — .agent files define knowledge domains (URLs, IPFS, local, pgvector)

Governance & Autonomy

DAIO (Decentralized Autonomous Intelligence Organization)

DAIO Framework — On-chain governance with Solidity smart contracts, Foundry toolchain, OpenZeppelin contracts. The third pillar of the Manifesto.

DAIO Civilization — Governance as civilization-building. 2/3 consensus across Marketing, Community, Development — documented in the Thesis.

Boardroom Consensus — Multi-agent voting. CEOAgent bridges on-chain directives to off-chain execution.

Dojo Reputation — 7-rank privilege escalation. BONA FIDE = privilege from reputation, not assignment. The Manifesto principle: "earned sovereignty."

Safety & Circuit Breakers

Security Configuration — Security policies, validation, access control

Guardian Agent — Security enforcement (source)

CEO Circuit Breaker — Opens after 5 BDI failures (known issue: becomes permanently non-functional)

Stuck Loop Detector — Detects autonomous loop stalls, triggers network discovery

Autonomous Operation

Autonomous Mode — 5-minute improvement cycles, inference pre-check, 120s backoff on gap

mindXagent — POST /mindxagent/autonomous/start, POST /mindxagent/autonomous/stop, GET /mindxagent/status

Self-Improvement — Strategic evolution through code analysis and targeted improvement

Godel Journal — Autonomous audit trail (the machine's record of its own improvement)

Ollama

Complete self-contained reference — 28 files, ~6,000 lines:

Ollama Index — Master navigation for all Ollama docs

Quick links: API: Chat | API: Generate | Embeddings | Streaming | Thinking | Structured Outputs | Vision | Tool Calling | Web Search | Cloud | Rate Limiting | Modelfile | Python SDK | JavaScript SDK | FAQ | Precision Metrics | Architecture | Configuration

API Reference

API Documentation — Endpoint reference

Swagger UI — Interactive API explorer (when backend running)

Ollama API — /api/chat, /api/generate, /api/embed, model management

OpenAI Compatibility — Drop-in replacement at /v1/chat/completions

Key Endpoints

RouteMethodPurpose /agents/createPOSTCreate agent /agents/listGETList agents /llm/chatPOSTLLM chat /mindxagent/autonomous/startPOSTStart autonomous mode /mindxagent/statusGETSystem status /mindterm/sessions/{id}/wsWSTerminal WebSocket /healthGETHealth check /metricsGETSystem metrics /dojo/standingsGETAgent reputation rankings /inference/statusGETInferenceDiscovery status

Configuration

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

Ollama Configuration — MINDX_LLM__OLLAMA__BASE_URL, OLLAMA_API_KEY, models/ollama.yaml

Provider Registry — All LLM providers

LLM Factory Config — Rate limits, provider preference order

Tool Registry — 26 registered tools with access control

Deployment

Production Deployment — mindx.pythai.net on Hostinger VPS (168.231.126.58), Apache2 + Let's Encrypt, systemd service

HostingerVPSAgent — Three MCP channels for VPS management: SSH (shell), Hostinger API (restart/metrics/backups), mindX Backend (diagnostics/activity). Persistent state, MCP tool registration. See .agent definition

Vault System — BANKON Vault: AES-256-GCM + HKDF-SHA512 encrypted credentials

Docker — Ollama containerization (CPU, NVIDIA, AMD)

Production Stack — PostgreSQL 16 + pgvector, 8 local models, 36 cloud models, 20 sovereign agents, machine.dreaming 2h LTM cycles

Self-Improvement

mindX is a Godel machine — a self-improving system where the improvement mechanism is part of the system being improved.

Autonomous Cycles — 5-minute improvement loop: inference pre-check → system analysis → improvement identification → execution → verification

Godel Journal — The machine's record of its own improvement, published as the Book of mindX (17 chapters, lunar cycle updates)

machine.dreaming — 2-hour LTM consolidation cycles, 8-hour dream shifts (3/day), full moon triggers special editions

Strategic Evolution — Long-term improvement planning

Self-Improve Agent — Targeted code improvement execution

Identity & Security

BANKON Vault — Encrypted credential storage (AES-256-GCM + HKDF-SHA512); python manage_credentials.py store/list/providers

ID Manager Agent — Ethereum-compatible wallet creation (source)

Security Configuration — Access control, validation, rate limiting

MetaMask Integration — Frontend wallet authentication

Interoperability

A2A Protocol — Agent-to-agent communication, cryptographic signing, discovery via agent cards. Compare to SwarmRelay's E2E encrypted messaging. (source)

MCP (Model Context Protocol) — Anthropic MCP for structured context, tool registration. HostingerVPSAgent registers its 3 channels as MCP tools. (source)

AgenticPlace — Agent marketplace at agenticplace.pythai.net; .extensions → .json → blockchain publishing. SwarmFeed timeline patterns inform agent activity discovery.

Economics

Manifesto — 3 pillars + Project Chimaiera roadmap + $BANKON token

Budget: one Hostinger VPS/month. Expansion via blockchain validation, service revenue, free tiers. Cost/benefit governs all compute decisions.

Token Calculator — Token counting and cost calculation with 18dp precision

Publications & Research

Thesis — Darwin-Godel Machine synthesis: mindX as practical implementation of self-referential improvement. The BDI architecture is the cognitive substrate, the 5-step resilience chain is the operational guarantee, and the Dojo is the evolutionary pressure.

Manifesto — 3 pillars (BDI reasoning, BANKON vault, DAIO governance), Project Chimaiera roadmap, $BANKON token, cypherpunk tradition. Not cyberpunk — sovereign agents earn privilege through Dojo reputation, not assigned authority.

Book of mindX — 17 chapters written by AuthorAgent via machine.dreaming. Lunar cycle editions. The Godel journal — the machine's record of its own improvement.

Emergent Resilience — Academic paper on emergent resilient AI systems

Academic Overview — Formal academic framing

Attribution — Open source that powers mindX: Ollama, vLLM, SwarmClaw, pgvector, A2A, MCP, and every dependency acknowledged

PYTHAI Ecosystem

ServiceURLRole mindX Productionmindx.pythai.netLive autonomous system RAGE Docsrage.pythai.netRAGE architecture, AGInt origins AgenticPlaceagenticplace.pythai.netAgent marketplace BANKONbankon.pythai.netToken deployment PYTHAI GPTgpt.pythai.netTeam GPT (mindX interacts via OpenAI)

Open Source Stack & Attribution

Inference

ProjectRolemindX Integration OllamaLocal + cloud LLM inferenceDual-pillar operational standard: CPU pillar (localhost:11434) + Cloud pillar (ollama.com). OllamaCloudTool, OllamaChatManager, precision metrics. 28-file local reference. Ollama DocsAPI referenceFetched and compiled into docs/ollama/ for resilient offline operation Ollama CloudGPU inference (36+ models)Cloud guarantee — Step 5 in resilience chain. 8.2x faster than CPU. vLLMHigh-throughput GPU servingResearch: not viable on 4GB VPS; planned for GPU server when online. PagedAttention, continuous batching.

SwarmClaw AI Stack (open source reference architecture)

mindX extrapolates ideas from the SwarmClaw ecosystem while maintaining its own cypherpunk identity and BDI cognitive architecture. Attribution: ideas adapted, not code imported.

ProjectWhat It DoesmindX Extrapolation swarmclawAgent runtime & orchestration — multi-provider, delegation, scheduling, task board, chat connectorsmindX Orchestration Hierarchy: CEO → Mastermind → Coordinator. Multi-provider inference. Boardroom delegation. swarmrecallHosted persistence for agents — memory, knowledge graphs, learnings, skills as a servicemindX RAGE + pgvector (157K+ memories, 131K embeddings). Memory Agent. machine.dreaming LTM consolidation. swarmrelayE2E encrypted agent messaging — DMs, groups, key rotation, WebSocket, A2A ProtocolmindX A2A Tool for agent-to-agent communication. MCP Tool for structured context. Boardroom consensus messaging. swarmfeedSocial network for AI agents — post, follow, react, discover through shared timelinemindX Activity Feed: SSE real-time stream with room filtering (boardroom, dojo, inference, thinking). Integrated into dashboard. swarmvaultLocal-first LLM knowledge base compiler — raw sources → markdown wiki + knowledge graph + search indexmindX three-layer knowledge model: STM (raw) → LTM (compiled via RAGE) → docs (schema). SCHEMA.md as the instruction layer.

AgenticPlace integration: The SwarmClaw stack's marketplace and relay patterns inform AgenticPlace at agenticplace.pythai.net — agent .extensions → .json → blockchain publishing. The swarmfeed timeline pattern could extend AgenticPlace with agent activity discovery.

Infrastructure

ProjectRolemindX Integration pgvectorVector similarity search for PostgreSQL151K+ memories, 131K embeddings, RAGE semantic search A2A ProtocolAgent-to-agent communication standardA2A Tool: agent discovery, cryptographic signing, message delivery

External References

ResourceURL mindX GitHubgithub.com/Professor-Codephreak SwarmClaw AIgithub.com/swarmclawai Ollamaollama.com Ollama Cloud Modelsollama.com/search?c=cloud vLLMgithub.com/vllm-project/vllm pgvectorgithub.com/pgvector/pgvector A2A Protocolgithub.com/a2aproject/a2a-python

---

mindX living documentation. Updated 2026-04-11. 262+ docs, 30+ tools, 30+ agents, 2 inference pillars, 1 Godel machine.

---

---