# minedojo/voyager architecture

> Architecture diagram of the GitHub repository minedojo/voyager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/minedojo/voyager
- Repository: https://github.com/minedojo/voyager

## Overview

1. **Repository purpose**
   - This is the codebase for Voyager, a lifelong-learning agent for Minecraft.
   - The architecture combines a Python orchestration layer, a Node.js Minecraft control layer, and a persistent skill library that stores reusable behaviors as executable JavaScript plus natural-language descriptions.

2. **Top-level orchestration entrypoint**
   - The main API appears to be `voyager/voyager.py`, exposing a `Voyager` object used for both learning and inference.
   - That object likely coordinates curriculum generation, action selection, skill retrieval, execution, error handling, and checkpointing.

3. **Agent-side subsystems**
   - `voyager/agents/` holds the high-level reasoning components:
     - `curriculum.py` for automatic task generation / exploration pressure.
     - `skill.py` for skill creation, storage, retrieval, and reuse.
     - `action.py` for converting model outputs into concrete actions.
     - `critic.py` for feedback, self-verification, or post-execution evaluation.
   - These form the LLM-facing control loop around Minecraft interaction.

4. **Prompting and LLM contract**
   - `voyager/prompts/` contains the prompt templates that define the interface with the language model.
   - Prompts cover curriculum generation, task decomposition, action formatting, skill writing, and critique.
   - The README makes clear the LLM is GPT-4 via black-box API calls, so the system depends on prompt engineering rather than model fine-tuning.

5. **Minecraft environment boundary**
   - `voyager/env/` is the runtime boundary to the game.
   - `minecraft_launcher.py` and `bridge.py` manage starting or attaching to a Minecraft instance and moving data between Python and the game process.
   - `process_monitor.py` suggests supervision of child processes and crash / liveness handling.

6. **Node.js / Mineflayer execution layer**
   - `voyager/env/mineflayer/` is the JavaScript runtime that actually drives the Minecraft bot.
   - This uses Mineflayer and related packages to perform in-game actions, observe world state, and run control primitives.
   - The Python layer delegates low-level execution to this Node process rather than talking to the game directly.

7. **Control primitives as reusable action building blocks**
   - `voyager/control_primitives/` contains core JavaScript primitives such as mining, crafting, smelting, combat, placing items, using chests, shooting, and waiting for mob removal.
   - `voyager/control_primitives_context/` provides context-aware variants, including `mineflayer.js`, indicating some primitives depend on bot state or environment context.
   - These primitives are the operational bridge between high-level agent plans and executable in-game behavior.

8. **Observation and world-state ingestion**
   - Inside `voyager/env/mineflayer/lib/observation/` are modules for inventory, chests, status, chat, errors, save events, and voxel/world observations.
   - This indicates the agent’s state representation is assembled from multiple event streams and snapshots, not from a single API response.
   - The observation layer is central to the feedback loop that informs retries, critiques, and curriculum updates.

9. **Skill library architecture**
   - `skill_library/` contains learned skills organized into trials.
   - Each skill has:
     - executable code in `skill/code/*.js`,
     - a natural-language description in `skill/description/*.txt`,
     - a `skills.json` manifest,
     - and a `vectordb/` directory with Chroma vector-store artifacts.
   - This makes the skill library both a code repository and a semantic retrieval index.

10. **Skill retrieval and reuse flow**
    - During inference or learning, the agent can search the vector database for relevant prior skills based on task text.
    - Retrieved skills are then composed or adapted into new executable behaviors.
    - The presence of multiple “trial” libraries suggests staged capability growth and versioned skill snapshots.

11. **Learning loop and persistence**
    - Voyager supports open-ended learning, checkpoint resume, and later inference with a frozen learned skill library.
    - Checkpoints are distinct from skill-library storage: the README explicitly separates `ckpt_dir` for ongoing event recording from a reusable `skill_library_dir`.
    - This separation matters architecturally because learning state and reusable knowledge are persisted independently.

12. **External dependencies and runtime constraints**
    - The system depends on Python 3.9+ and Node.js 16.13+.
    - Minecraft must be installed separately, along with Fabric mods to enable required game features.
    - Authentication can be handled with Azure login or a direct Minecraft port, and OpenAI API access is required for the LLM.

13. **Data flow at a high level**
    - Task or curriculum prompt is produced in Python.
    - GPT-4 returns a plan, action, or skill program.
    - Python sends execution to the Mineflayer/Node layer.
    - Mineflayer executes in Minecraft and streams observations back.
    - Errors, environment feedback, and successes are fed into critique and skill-update logic.
    - Successful behaviors are stored in the skill library for future retrieval.

14. **Repository structure for architecture diagrams**
    - Draw three major boundaries:
      - **Reasoning layer**: `voyager/agents`, `voyager/prompts`, `voyager/voyager.py`
      - **Execution layer**: `voyager/env`, `voyager/env/mineflayer`, `voyager/control_primitives*`
      - **Knowledge layer**: `skill_library/*` with code, text descriptions, and vector DB
    - The key external systems are **Minecraft**, **OpenAI/GPT-4**, and **Azure/Minecraft login infrastructure**.

Main entry points: [`voyager/env/mineflayer/index.js`](https://github.com/minedojo/voyager/blob/main/voyager/env/mineflayer/index.js) (Mineflayer Bot), [`voyager/voyager.py`](https://github.com/minedojo/voyager/blob/main/voyager/voyager.py) (Voyager), [`skill_library`](https://github.com/minedojo/voyager/tree/main/skill_library) (Skill Trials), [`voyager/env/bridge.py`](https://github.com/minedojo/voyager/blob/main/voyager/env/bridge.py) (Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_reasoning["Reasoning layer"]
  node_voyager_core["Voyager<br/>python orchestrator<br/>[voyager.py]"]
  node_curriculum_agent["Curriculum<br/>task generator<br/>[curriculum.py]"]
  node_skill_agent["Skill Manager<br/>skill retrieval<br/>[skill.py]"]
  node_action_agent["Action Agent<br/>action formatting<br/>[action.py]"]
  node_critic_agent["Critic<br/>feedback loop<br/>[critic.py]"]
  node_prompt_contracts["Prompts<br/>prompt templates"]
end

subgraph group_execution["Execution layer"]
  node_env_bridge["Bridge<br/>[bridge.py]"]
  node_minecraft_launcher["Launcher<br/>process startup"]
  node_process_monitor["Monitor<br/>process supervision<br/>[process_monitor.py]"]
  node_mineflayer_bot["Mineflayer Bot<br/>node runtime<br/>[index.js]"]
  node_observation_stack["Observations<br/>world state ingest"]
  node_skill_loader_js["Skill Loader<br/>js loader<br/>[skillLoader.js]"]
  node_control_primitives["Primitives<br/>js action library"]
  node_context_primitives["Context Primitives<br/>context-aware js"]
end

subgraph group_knowledge["Knowledge layer"]
  node_skill_trials[("Skill Trials<br/>learned skill library")]
  node_skill_code["Skill Code<br/>js skills"]
  node_skill_descriptions["Skill Descriptions<br/>nl skills"]
  node_skill_manifest["Skills Index<br/>skill manifest<br/>[skills.json]"]
  node_vector_db[("Vector DB<br/>semantic index")]
end

subgraph group_external["External systems"]
  node_minecraft(("Minecraft<br/>game world"))
  node_openai(("OpenAI GPT-4<br/>llm api"))
  node_login(("Login Infra<br/>auth/runtime"))
end

node_voyager_core -->|"generate tasks"| node_curriculum_agent
node_voyager_core -->|"retrieve/update skills"| node_skill_agent
node_voyager_core -->|"plan actions"| node_action_agent
node_voyager_core -->|"evaluate outcomes"| node_critic_agent
node_curriculum_agent -->|"uses prompts"| node_prompt_contracts
node_action_agent -->|"uses prompts"| node_prompt_contracts
node_critic_agent -->|"uses prompts"| node_prompt_contracts
node_skill_agent -->|"uses prompts"| node_prompt_contracts
node_voyager_core -->|"send command"| node_env_bridge
node_env_bridge -->|"start/attach"| node_minecraft_launcher
node_env_bridge -->|"supervise"| node_process_monitor
node_env_bridge -->|"control bot"| node_mineflayer_bot
node_mineflayer_bot -->|"execute primitives"| node_control_primitives
node_mineflayer_bot -->|"execute context actions"| node_context_primitives
node_mineflayer_bot -->|"stream state"| node_observation_stack
node_mineflayer_bot -->|"load skills"| node_skill_loader_js
node_skill_loader_js -->|"read library"| node_skill_trials
node_skill_trials -->|"contains"| node_skill_code
node_skill_trials -->|"contains"| node_skill_descriptions
node_skill_trials -->|"contains"| node_skill_manifest
node_skill_trials -->|"contains"| node_vector_db
node_vector_db -->|"retrieve relevant skills"| node_skill_agent
node_observation_stack -->|"feedback"| node_critic_agent
node_observation_stack -->|"success signals"| node_skill_agent
node_openai -->|"model responses"| node_voyager_core
node_login -->|"auth"| node_minecraft_launcher
node_minecraft_launcher -->|"launches"| node_minecraft
node_mineflayer_bot -->|"acts in"| node_minecraft

click node_voyager_core "https://github.com/minedojo/voyager/blob/main/voyager/voyager.py"
click node_curriculum_agent "https://github.com/minedojo/voyager/blob/main/voyager/agents/curriculum.py"
click node_skill_agent "https://github.com/minedojo/voyager/blob/main/voyager/agents/skill.py"
click node_action_agent "https://github.com/minedojo/voyager/blob/main/voyager/agents/action.py"
click node_critic_agent "https://github.com/minedojo/voyager/blob/main/voyager/agents/critic.py"
click node_prompt_contracts "https://github.com/minedojo/voyager/tree/main/voyager/prompts"
click node_env_bridge "https://github.com/minedojo/voyager/blob/main/voyager/env/bridge.py"
click node_minecraft_launcher "https://github.com/minedojo/voyager/blob/main/voyager/env/minecraft_launcher.py"
click node_process_monitor "https://github.com/minedojo/voyager/blob/main/voyager/env/process_monitor.py"
click node_mineflayer_bot "https://github.com/minedojo/voyager/blob/main/voyager/env/mineflayer/index.js"
click node_observation_stack "https://github.com/minedojo/voyager/tree/main/voyager/env/mineflayer/lib/observation"
click node_skill_loader_js "https://github.com/minedojo/voyager/blob/main/voyager/env/mineflayer/lib/skillLoader.js"
click node_control_primitives "https://github.com/minedojo/voyager/tree/main/voyager/control_primitives"
click node_context_primitives "https://github.com/minedojo/voyager/tree/main/voyager/control_primitives_context"
click node_skill_trials "https://github.com/minedojo/voyager/tree/main/skill_library"
click node_skill_code "https://github.com/minedojo/voyager/tree/main/skill_library/trial1/skill/code"
click node_skill_descriptions "https://github.com/minedojo/voyager/tree/main/skill_library/trial1/skill/description"
click node_skill_manifest "https://github.com/minedojo/voyager/blob/main/skill_library/trial1/skill/skills.json"
click node_vector_db "https://github.com/minedojo/voyager/tree/main/skill_library/trial1/skill/vectordb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_voyager_core,node_curriculum_agent,node_skill_agent,node_action_agent,node_critic_agent,node_prompt_contracts toneBlue
class node_env_bridge,node_minecraft_launcher,node_process_monitor,node_mineflayer_bot,node_observation_stack,node_skill_loader_js,node_control_primitives,node_context_primitives toneAmber
class node_skill_trials,node_skill_code,node_skill_descriptions,node_skill_manifest,node_vector_db toneMint
class node_minecraft,node_openai,node_login toneRose
```

## Components

### Reasoning layer

Python orchestration, prompting, and agent control loops.

- [Voyager](https://github.com/minedojo/voyager/blob/main/voyager/voyager.py): python orchestrator · Top-level agent API coordinating learning, inference, execution, and persistence. · `voyager/voyager.py`
- [Curriculum](https://github.com/minedojo/voyager/blob/main/voyager/agents/curriculum.py): task generator · Produces exploration pressure and task proposals for open-ended learning. · `voyager/agents/curriculum.py`
- [Skill Manager](https://github.com/minedojo/voyager/blob/main/voyager/agents/skill.py): skill retrieval · Creates, stores, retrieves, and adapts reusable behaviors. · `voyager/agents/skill.py`
- [Action Agent](https://github.com/minedojo/voyager/blob/main/voyager/agents/action.py): action formatting · Converts model outputs into executable action plans. · `voyager/agents/action.py`
- [Critic](https://github.com/minedojo/voyager/blob/main/voyager/agents/critic.py): feedback loop · Evaluates outcomes and supports self-verification or retries. · `voyager/agents/critic.py`
- [Prompts](https://github.com/minedojo/voyager/tree/main/voyager/prompts): prompt templates · LLM-facing templates for curriculum, action, skill writing, and critique. · `voyager/prompts`

### Execution layer

Environment bridge, Node.js bot runtime, and control primitives.

- [Bridge](https://github.com/minedojo/voyager/blob/main/voyager/env/bridge.py): python-node bridge · Moves commands and observations between Python and the game runtime. · `voyager/env/bridge.py`
- [Launcher](https://github.com/minedojo/voyager/blob/main/voyager/env/minecraft_launcher.py): process startup · Starts or attaches to Minecraft and manages instance lifecycle. · `voyager/env/minecraft_launcher.py`
- [Monitor](https://github.com/minedojo/voyager/blob/main/voyager/env/process_monitor.py): process supervision · Tracks child processes and handles liveness or crash recovery. · `voyager/env/process_monitor.py`
- [Mineflayer Bot](https://github.com/minedojo/voyager/blob/main/voyager/env/mineflayer/index.js): node runtime · JavaScript control process that drives the Minecraft bot. · `voyager/env/mineflayer/index.js`
- [Observations](https://github.com/minedojo/voyager/tree/main/voyager/env/mineflayer/lib/observation): world state ingest · Assembles inventory, chest, chat, status, error, save, and voxel observations. · `voyager/env/mineflayer/lib/observation`
- [Skill Loader](https://github.com/minedojo/voyager/blob/main/voyager/env/mineflayer/lib/skillLoader.js): js loader · Loads learned skills into the Mineflayer runtime. · `voyager/env/mineflayer/lib/skillLoader.js`
- [Primitives](https://github.com/minedojo/voyager/tree/main/voyager/control_primitives): js action library · Reusable low-level actions such as mining, crafting, smelting, combat, chest use, and waiting. · `voyager/control_primitives`
- [Context Primitives](https://github.com/minedojo/voyager/tree/main/voyager/control_primitives_context): context-aware js · Variants of control primitives that depend on bot state or environment context. · `voyager/control_primitives_context`

### Knowledge layer

Persistent learned skills and retrieval index.

- [Skill Trials](https://github.com/minedojo/voyager/tree/main/skill_library): learned skill library · Versioned collections of executable skills with natural-language descriptions. · `skill_library`
- [Skill Code](https://github.com/minedojo/voyager/tree/main/skill_library/trial1/skill/code): js skills · Executable learned behaviors stored as JavaScript programs. · `skill_library/trial1/skill/code`
- [Skill Descriptions](https://github.com/minedojo/voyager/tree/main/skill_library/trial1/skill/description): nl skills · Natural-language skill summaries used for retrieval and reuse. · `skill_library/trial1/skill/description`
- [Skills Index](https://github.com/minedojo/voyager/blob/main/skill_library/trial1/skill/skills.json): skill manifest · Manifest of available learned skills in each trial library. · `skill_library/trial1/skill/skills.json`
- [Vector DB](https://github.com/minedojo/voyager/tree/main/skill_library/trial1/skill/vectordb): semantic index · Chroma-backed embedding store for skill retrieval. · `skill_library/trial1/skill/vectordb`

### External systems

Minecraft and model/login services used by the agent.

- **Minecraft**: game world · The external sandbox where the agent acts and observes.
- **OpenAI GPT-4**: llm api · Black-box language model used for planning, decomposition, and skill generation.
- **Login Infra**: auth/runtime · Azure or direct Minecraft authentication and runtime access infrastructure.

## Connections

- Voyager → Curriculum: generate tasks · Voyager asks the curriculum module for exploratory goals.
- Voyager → Skill Manager: retrieve/update skills · Voyager coordinates skill lookup, synthesis, and persistence.
- Voyager → Action Agent: plan actions · Voyager converts high-level intent into executable action sequences.
- Voyager → Critic: evaluate outcomes · Voyager uses critique to decide retries, refinements, or skill updates.
- Curriculum → Prompts: uses prompts · Curriculum generation is shaped by prompt templates.
- Action Agent → Prompts: uses prompts · Action formatting depends on prompt contracts and output schemas.
- Critic → Prompts: uses prompts · Critique and self-verification use dedicated prompt templates.
- Skill Manager → Prompts: uses prompts · Skill creation and retrieval are guided by prompt templates.
- Voyager → Bridge: send command · Python sends execution requests through the environment boundary.
- Bridge → Launcher: start/attach · The bridge relies on launcher logic to manage the Minecraft instance.
- Bridge → Monitor: supervise · Environment control is monitored for crashes and liveness.
- Bridge → Mineflayer Bot: control bot · Commands are forwarded to the Node.js Mineflayer runtime.
- Mineflayer Bot → Primitives: execute primitives · The bot invokes reusable low-level action building blocks.
- Mineflayer Bot → Context Primitives: execute context actions · Context-aware primitives handle state-dependent behaviors.
- Mineflayer Bot → Observations: stream state · The bot emits observations from chat, inventory, status, and world events.
- Mineflayer Bot → Skill Loader: load skills · The runtime loads learned skill code into the bot process.
- Skill Loader → Skill Trials: read library · The loader reads learned skills from persistent storage.
- Skill Trials → Skill Code: contains · Each trial library stores executable skill programs.
- Skill Trials → Skill Descriptions: contains · Each trial library stores natural-language skill descriptions.
- Skill Trials → Skills Index: contains · Each trial library includes a manifest of available skills.
- Skill Trials → Vector DB: contains · Each trial library includes a semantic retrieval index.
- Vector DB → Skill Manager: retrieve relevant skills · Semantic search returns prior behaviors for reuse and adaptation.
- Observations → Critic: feedback · Observed outcomes inform critique and recovery logic.
- Observations → Skill Manager: success signals · Successful behaviors can be captured into new or updated skills.
- OpenAI GPT-4 → Voyager: model responses · The external LLM supplies plans, actions, critiques, and skills.
- Login Infra → Launcher: auth · Authentication infrastructure enables access to the Minecraft instance.
- Launcher → Minecraft: launches · Launcher brings up the game process or attaches to it.
- Mineflayer Bot → Minecraft: acts in · The Node.js bot performs in-game actions inside Minecraft.
