moincraft

🏗️ Architecture

Canonical Moincraft architecture map: layer split, startup order, agent lifecycle, memory, and model slots.

Moincraft is a layered runtime, not a pile of scripts.

System map# 

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

PM2 / launch_all.sh
  ├─ mc-server        Paper :25565
  ├─ dashboard        Svelte :55666 + relay :55667
  ├─ mindcraft-bots   MindServer :55668 + main.js
  └─ prismarine-viewer WebGL :55669

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 reaching into MindServer internals.
  • Embodied agents: Mindcraft/Mineflayer owns Minecraft state, pathfinding, action execution, and in-world coordination.

Startup order#

  1. Paper server; wait for :25565.
  2. Mindcraft bots with staggered startup.
  3. Prismarine viewer after server readiness.
  4. Dashboard UI/relay.

Only one orchestrator at a time. Mixing systemd, PM2, and manual scripts causes EADDRINUSE and session.lock conflicts.

Agent lifecycle# 

bootstrap()
  → Mindcraft.init()
  → createAgent(settings)
  → Agent.start()
      ├─ ActionManager
      ├─ Prompter
      ├─ History
      ├─ Coder
      ├─ NPCController
      ├─ MemoryBank
      ├─ SelfPrompter
      ├─ VisionInterpreter
      ├─ CooperationFramework
      └─ initModes()

Model slots#

Slot Role
model Default chat model and fallback.
code_model !newAction code generation.
vision_model Multimodal world/player analysis.
embedding Semantic retrieval for examples and skill docs.

Memory and autonomy#

  • History keeps a small sliding window (max_messages, usually 15).
  • Older turns are summarized into memory for prompt reuse.
  • SelfPrompter loops through goals with STOPPED, ACTIVE, and PAUSED states.
  • Coder lints generated JS before sandboxed execution.

Sources: wiki/content/docs/architecture.md, moincraft/docs/moincraft-stack-cheatsheet.md, moincraft/docs/bot-architecture.md.