Experimental, early-stage research project. No intelligent agent has been implemented or demonstrated yet. This repository currently defines the research programme, interfaces, constraints, and staged engineering work needed to test feasibility.
Minecraft Native Intelligence investigates persistent, autonomous intelligence whose perceived world is Minecraft itself. The intended agent learns and acts through native game state and legal game actions, develops an individual history and behavioural tendencies, communicates with other players, and pursues activities without existing only as a command-following assistant.
This is not an LLM wrapper, a screenshot-to-keyboard agent, a prompted Mineflayer bot, a scripted NPC, or “ChatGPT inside Minecraft.” Language models may be studied as components, but they are neither the project definition nor a substitute for grounded perception, action, memory, learning, and evaluation.
The agent-facing ontology should be grounded in blocks, entities, items, terrain, motion, health, hunger, danger, time, places, communication, relationships, and remembered experience. It should not require concepts such as operating systems, model APIs, or a human “user.” Developers and server operators, however, must retain transparent oversight and must identify AI players where policy requires it.
- An easy-to-install Java Edition mod runs on the logical server (integrated single-player/LAN or dedicated server), exposes bounded native state, and validates ordinary in-game actions—without hidden information, teleportation, inventory editing, or other cheats.
- An authorized operator creates a persistent AI player with
/spawn ai-agent <username>. It is represented through the normal player-facing systems—entity tracking, nameplate, chat, locator maps, player lists, scoreboards, death/respawn, and compatible integrations wherever technically possible. - New agents start in Survival with ordinary health, hunger, inventory, crafting, equipment/armour, effects, damage, death, pickup/drop, movement, reach, cooldown, and world-interaction rules. The integration drives player actions; it does not mutate outcomes directly.
- On first creation, the mod assigns a random skin from a curated, distributable catalog and stores its immutable skin reference with that agent. The same skin returns after unload, restart, or respawn unless an authorized operator deliberately changes it.
- A shared foundation model provides reusable world and behavioural competence without loading a full independent model per agent.
- Each agent owns separate persistent identity, episodic/semantic/procedural/spatial memory, relationships, goals, preferences, and—only if evidence supports it—small personal learning modules.
- Learning begins with durable state and memory, not continuous retraining. Later work may test replay, consolidation, adapters, and other continual-learning techniques against catastrophic forgetting.
- Human and AI players use the same grounded communication pathway and appear to the agent as other intelligent beings in its world.
- Multi-agent behaviour should emerge from learned policies and interaction, not hardcoded friendships, rivalries, professions, or stories.
See the authoritative goal and architecture for scope and uncertainty.
The v0.1 — Project Foundation baseline is complete. Current work moves into v0.2 — Minecraft Native Interface: validating the proposed Fabric/Minecraft baseline through player-compatible embodiment, then implementing and testing the native observation/action, information-access, Survival-parity, packaging, and compatibility boundaries. Later milestones progress through runtime and memory prototypes, behavioural and language grounding, autonomy, lifelong learning, multi-agent scaling, and an integrated research platform. They are research stages—not promises of human-level intelligence.
See ROADMAP.md for dependencies and success gates.
| Start here | Purpose |
|---|---|
| Goal | Ultimate goal, near-term objective, and non-goals |
| Vision and Principles | Product direction and invariants |
| Architecture | Proposed system boundaries and timescales |
| Java mod integration | Installation, spawning, player embodiment, skins, and lifecycle |
| Research programme | Questions, experimental method, and evidence standards |
| Evaluation and experiments | Scenario/result evidence contracts and reproducible execution |
| Testing and CI | Test tiers, local checks, and stack-aware remote verification |
| Data governance | Licensing, consent, privacy, retention, and deletion gates |
| Runtime boundary | Java ↔ research-runtime process and protocol boundary |
| Roadmap | Milestones, dependencies, and exit criteria |
| Safety and Security | Minecraft-specific operational safeguards |
| Decision log | Accepted decisions and unresolved ADRs |
| Glossary | Canonical terminology |
Focused design notes live under docs/.
For a first contribution:
- Read the authoritative goal and current roadmap.
- Pick an issue in the current milestone with
status:ready; do not silently work around a listed blocker. - Read the issue discussion, decision log, and the focused subsystem document linked by the issue.
- Follow testing, local/CI checks, and—when relevant—evaluation, experiment, and data-governance rules.
- Keep one coherent change/PR and record what was actually validated.
CONTRIBUTING.md contains the issue-template and first-task workflow.
Contributions are welcome at the design, research, tooling, and documentation stages. Read CONTRIBUTING.md and AGENTS.md before substantial work. Claims of capability require reproducible evidence; experiments must remain distinguishable from proposed production architecture.
Code and documentation are licensed under Apache License 2.0. Datasets, Minecraft assets, model weights, and third-party artifacts require separate provenance and license review; inclusion in this repository does not automatically place them under Apache-2.0.