Architecture

Architecture

🏗️ Moincraft Architecture#

System Map# 

Hermes/Hermit operator ──REST/ops──▶ Relay :55667
       │                              ▲
       └─ persona + memory + skills   │ optional DASHBOARD_API_TOKEN

┌─────────────────────────────────────────────────────────┐
│                      PM2 / launch_all.sh                │
├──────────────┬──────────────┬─────────────┬─────────────┤
│  mc-server   │  dashboard   │mindcraft-   │ prismarine- │
│Paper 1.21.11 │Svelte :55666 │bots :55668  │viewer :55669│
│   G1GC JVM   │relay  :55667 │main.js      │viewer.js    │
└──────┬───────┴──────┬───────┴──────┬──────┴──────┬──────┘
       │              │              │             │
    :25565         socket.io      MindServer    Three.js
    TCP/UDP        events         hub + WS      WebGL
       │              │              │             │
       └──────────────┴──────────────┴─────────────┘
                    Mineflayer Bots (per agent)

Port Map#

Port Service Notes
25565 Paper MC Server MOINCRAFT_SPIGOT_PORT
55666 Svelte Dashboard UI MOINCRAFT_NEW_DASHBOARD_PORT
55667 Dashboard relay backend DASHBOARD_PORT, Socket.IO
55668 MindServer MINDSERVER_PORT, agent hub
55669 Prismarine Viewer MOINCRAFT_VIEWER_PORT, WebGL
55661+ Per-agent viewer ports base + offset

AIRI-Inspired Layer Split#

  • Soul/Operator: Hermes owns durable persona, memory, skills, and remote messaging
  • Runtime Bridge: Relay :55667 is the stable API boundary — prefer extending relay contracts over calling MindServer internals
  • Embodied Agents: Mindcraft/Mineflayer owns Minecraft state, pathfinding, action execution, in-world coordination

Agent Lifecycle# 

bootstrap() → Mindcraft.init() → createAgent(settings)
  └→ Agent.start()
       ├─ ActionManager      — action queue + interrupts
       ├─ Prompter           — LLM abstraction (chat/code/vision/embed)
       ├─ History            — sliding window + LLM summarization
       ├─ Coder              — code gen + ESLint lint + SES sandbox exec
       ├─ NPCController      — item/build goals + constructions
       ├─ MemoryBank         — (stub, extend for vector DB)
       ├─ SelfPrompter       — autonomous goal loop (STOPPED/ACTIVE/PAUSED)
       ├─ VisionInterpreter  — screenshot → vision model
       ├─ CooperationFramework — multi-agent levels 1–5
       └─ initModes()        — tick-based reactive behaviors

Startup Order (Critical)# 

1. Paper MC server          (wait :25565 TCP)
2. mindcraft-bots           (AGENT_STARTUP_DELAY_MS=1500 between agents)
3. prismarine-viewer        (after server ready)
4. dashboard

⚠️ Only ONE orchestrator at a time — either moincraft.service (systemd) OR user-level moincraft-*.service — NEVER both (causes EADDRINUSE + session.lock conflicts).

Prompter — 4 Model Slots# 

{
  "model":        "chat model (default fallback for all)",
  "code_model":   "specialized for !newAction codegen",
  "vision_model": "multimodal for !lookAtPlayer etc",
  "embedding":    "semantic search for examples + skill docs"
}

Prompt templates use $VAR placeholders: $NAME $STATS $INVENTORY $MEMORY $COMMAND_DOCS $CODE_DOCS $EXAMPLES $SELF_PROMPT $LAST_GOALS $BLUEPRINTS $CONVO $ACTION $TO_SUMMARIZE

History — Memory System#

  • Sliding window: keeps last max_messages (default 15) turns
  • Summarization: when full → LLM compresses oldest 5 turns into memory (≤500 chars)
  • Persistence: bots/{name}/memory.json — survives restarts if load_memory: true
  • Full history: appended to bots/{name}/histories/{timestamp}.json
  • Prompt injection: $MEMORY injects summary; recent turns provide context

SelfPrompter — Autonomous Loop# 

start(goal) → loop {
  send "You are self-prompting with goal: '{goal}'. Use a !command."
  if no command used 3× in a row → stop
  await 2s cooldown
}

States: STOPPED(0) ACTIVE(1) PAUSED(2). Auto-restarts if idle ≥ cooldown and state is ACTIVE.

Coder — Safe Code Execution#

  • Generates JS code blocks via promptCoding()
  • ESLint lints before execution (catches hallucinations)
  • lockdown() + makeCompartment() via SES for sandboxing
  • Max 5 attempts, max 3 no-code failures before abort
  • Code has access to: bot, skills, world, Vec3 (no require/import)

RAG — Examples & Skill Library#

  • Embeds all conversation + coding examples via embedding_model
  • At prompt time: cosine similarity → top-N most relevant injected as $EXAMPLES
  • Skill docs for !newAction: embed task → cosine sim → top-N docs as $CODE_DOCS
  • Always includes: placeBlock, wait, breakBlockAt
  • relevant_docs_count: 5, EXAMPLES_INIT_TIMEOUT_MS=20000
  • Fallback without embedding model: word overlap scoring