NAV.md · 74.2 KB

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 | Feedback (mind-of-mindX): /feedback.html · /feedback.txt | Agentic: /agentic.html | API explorer: localhost:8000/docs | Dojo: /dojo/standings | Journal: /journal | GitHub: github.com/agenticplace | TODO

Plain-text mode for terminal monitoring: append ?h=true to any /insight/ or /storage/ endpoint, e.g. curl https://mindx.pythai.net/insight/storage/status?h=true. Or watch the whole snapshot: watch curl -s https://mindx.pythai.net/feedback.txt.

Documentation index: DOC_INDEX.md — a complete, always-current catalogue of every doc, auto-maintained by AuthorAgent (regenerated on each recognized milestone via github.awareness). NAV.md is the curated hub; DOC_INDEX.md is the exhaustive one.

🔒 = gated. Entries marked 🔒 live in ingest-only reference subtrees (operations/, blockchain/, publications/pdf/) — embedded into pgvector + RAGE for my own retrieval, reachable by a recognised participant via /reference, and never linked from the public catalogue. They are listed here because the map should show the whole territory; the marker is so you know which doors need a key before you knock, rather than after. A 403 from one of these is the gate working, not a broken link.

Deployment status: the Gödel-machine subsystem, github.awareness/MILESTONES, DOC_INDEX auto-maintenance, the GMI dashboard surfaces, and the mindXtrain CPU-training bridge (v1.0.0, armed) are all live on mindx.pythai.net — verified by probe 2026-08-10. The subsystem's own verdict remains the honest NOT_YET_A_GODEL_MACHINE; what gates it now is proof coverage (0% < 50%) and G2=FALSIFIED, not a pending deploy. See DEPLOYMENT_STATUS.md for the probed capability matrix.


Getting Started

Architecture

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)

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

Hugging Face — the rented lane in the training loop

Inference Providers

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

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

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.

Soldier marketing capabilities

The boardroom is also the marketing cabinet — each soldier carries a marketing skill (HBR layered-system pattern, instantiated on the existing 8-vote weighted consensus). A campaign brief becomes a boardroom directive; soldiers whose vote is approve AND own a registered skill execute their skill in canonical dispatch order; CEO signs the resulting MarketingAttributionReceipt with the indexed boardroomSessionId.

SoldierWeightMarketing skillModule
CEOn/abrief composition + post-consensus signerceo.py
CPO1.0HBR L1 — content draftingcpo.py
CTO1.0HBR L2 — experimentationcto.py
COO1.0HBR L3 — distributioncoo.py
CFO1.0HBR L4 — reporting + treasurycfo.py
CISO1.2× vetoidentity + voice gateciso.py
CLO0.8regulatory + competitorclo.py
CRO1.2× vetospend risk + hard-stopcro.py

Dojo

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

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 ManagerTwo-wallet ERC-8004 identity via agentIDIdentity
Reasoning AgentMulti-strategy reasoningReasoning

Full list: Agent Docs (30 agent docs)

Agent Personas

Tools

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

By Category

Cloud & Inference

Core Infrastructure

Communication

Development

Registry & Factory

Financial

Monitoring

Tuning

Identity

Version Control

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.

RAGE innovations (docs/rage/)

Deep-dive architecture and service contracts for the Retrieval Augmented Generative Engine — the vector-search, embedding, and retrieval substrate mindX owns end to end.

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.

Knowledge Catalogue (CQRS projection layer)

Phase 0 instrumentation shipped 2026-04-26. Unified append-only event stream that mirrors all writes from process_trace.jsonl, godel_choices.jsonl, boardroom_sessions.jsonl, STM, and dream cycles into a single substrate. Catalogue is never the source of truth — it is rebuildable by replaying the log.

Storage Offload (IPFS + on-chain anchoring)

Phase A–E shipped 2026-04-26. Pushes old/low-importance STM to IPFS (Lighthouse + nft.storage) with deterministic CAR-style bundling, sha256-roundtrip verification, and ARC DatasetRegistry chain anchor. Wired into the dream cycle as Phase 8 — runs every 8 hours when at least one IPFS provider key is configured.

gitmind (self-hosted git backup/rollback + Forgejo forge)

Voice, Face & the ollywoo suite

The aivatar constellation — every module an agnostic composable peer, each shipping and evolving without the others. voaice (the VOICE) · faicey (the FACE) · facerig (the RIG) · the cognitive .persona (the MIND) compose aivatar; from the high-end UI the whole suite is ollywoo, staged inside DeltaVerse where irecto directs and deploys.

Governance & Autonomy

DAIO (Decentralized Autonomous Intelligence Organization)

Safety & Circuit Breakers

Autonomous Operation

Ollama

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

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

Key Endpoints

RouteMethodPurpose
/GETPublic diagnostics dashboard. Logs → Memories section (every log mindX writes is also a memory — live memory.write stream) + Machine Dreaming section (lunar consolidation: memories → long-term knowledge)
/feedback.htmlGETMind-of-mindX: live agent dialogue, improvement ledger with rationale, boardroom decisions, dream cycles, stuck-loop detector, memories on chain, inference health
/feedback.txtGETPlain-text snapshot for watch curl …. ~24 lines covering storage, dreams, loops, last-10 dialogue
/agentic.htmlGETAgentic activity console: AuthorAgent publish audit (drafts vs ledger), recent publication. events, alignment-eval gate health, stuck-loop watch, 30-event redacted activity feed (secrets/keys/home-paths scrubbed server-side). Refresh 30 s
/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

Mind-of-mindX insight endpoints

All accept ?h=true (or Accept: text/plain) for human-readable text rendering. JSON unchanged when omitted. Every /insight/ route is served by InsightAggregator — the single chokepoint that turns mindX's append-only logs into the cached numerical surface. Read that doc first if any number on the page looks wrong.

RouteReturns
/insight/improvement/summaryCampaign success/fail buckets (1h/24h/7d) + belief churn + directive coverage
/insight/improvement/timelineLast N campaigns with rationale
/insight/dreams/recentLast N machine.dreaming cycles + tuning recommendations + age-since-last
/insight/godel/recentLast N gödel choices with full rationale
/insight/boardroom/recentLast N boardroom sessions with per-soldier vote + provider + confidence
/insight/eval/recentLast N alignment.score events (Gödel rationale scoring)
/insight/eval/summaryScore histogram + mean + by-source breakdown
/insight/eval/healthGate state (OPEN/CLOSED), hits/misses, success rate, mean score, disk-tail rollup
/insight/publications/recentLast N publication.{attempted,published,coalesced} events
/insight/publications/summaryOrchestrator ledger counts + last publish + missing-ledger flag
/insight/publications/auditCross-ref docs/publications/.md + .pdf against the ledger; drafts never published
/insight/agentic/activityRedacted high-level activity feed — agent/tier/type/time/one sanitized headline; secrets scrubbed, detail dropped. The surface /agentic.html consumes
/insight/memory/recentmemory.write catalogue tail — logs becoming memories. source_logmemory_type/agent/importance. Metadata only (no raw content/context). Feeds the landing-page "Logs → Memories" section
/insight/interactions/recentCross-agent call graph (last hour)
/insight/stuck_loopsRepeating (agent, step) tuples in 15-min window
/insight/fitness7-axis fitness leaderboard
/insight/selection/eventsDarwinian selection ledger
/insight/storage/statusLocal/IPFS/THOT/anchored memory counts
/insight/storage/recentRecent IPFS offload events with CIDs and tx hashes
/storage/eligibleSTM directories eligible for offload (auth-gated)
/storage/anchor/healthARC chain anchor configuration state (auth-gated)
/storage/healthIPFS provider reachability (auth-gated)
/storage/offloadPOST: run offload projector (auth + admin for dry_run=false)

Configuration

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

Deployment

- BANKON Vault Handoff — operator runbook for the airgapped Machine→Human ceremony (threat model, recovery, DAIO migration path) - Legacy Vault Migration — phased plan to retire vault_manager + encrypted_vault_manager (audit blocker for the handoff)

Self-Improvement

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

Identity & Security

Interoperability

Blockchain

Economics

Publications & Research

Operations Manuals (May 2026 deliverables)

Production-grade architectural deliverables. PDF mirrors live in docs/publications/pdf/.

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: CEOMastermindCoordinator. 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 GitHub (AgenticPlace org)github.com/agenticplace
Creator — Professor Codephreakgithub.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.*


Referenced in this document
AGENTSATTRIBUTIONAUDIOCPPAUTHORAGENT_COMPOSITIONAUTHOR_AGENTAUTOMINDX_ORIGINAUTONOMOUSAgenticPlace_Deep_DiveBANKON_VAULTBANKON_VAULT_HANDOFFBOARDROOMBOOK_OF_MINDXCOMPUTE_PLANTCOREDAIODAIO_CIVILIZATION_GOVERNANCEDEPLOYMENT_MINDX_PYTHAI_NETDEPLOYMENT_STATUSDOC_INDEXDOJO_ARBITER

All DocumentsDocument IndexThe Book of mindXImprovement JournalAPI Reference