# cletus

Cletus is a Java Edition Minecraft bot built with AI and Mineflayer.  The goal is to have Cletus become somewhat autonomous.

# Cletus Bot – A Learning Minecraft AI

Cletus is a modular Mineflayer-based Minecraft bot designed to observe, learn, adapt, and evolve through tasks, memory, and AI interaction. It reads signs, listens to players, remembers context, and uses a local AI model to improve over time.

---

## Features
- **State-driven AI**: Uses a dynamic state machine (`/states`) to handle tasks like `Observe`, `ReadFromSign`, `Idle`, `HandleChat`, etc.
- **Memory system**: Persists events, chats, locations, and signs in SQLite via `/memory`
- **Safe zones**: Prevents accidental destruction near homes, beds, bases, and more
- **AI integration**: Uses [Ollama](https://ollama.ai) with `gemma3` or any LLM to chat and rewrite failed scripts
- **Self-growing**: Failed task scripts are auto-sent to AI for improvement and saved

---

## Folder Structure
```txt
├── bot.js                # Bot entrypoint
├── config.json           # Centralized bot and AI config
├── core/
│   ├── state-machine.js  # Loads and manages dynamic states
│   └── context.js        # Shared bot context for state/tasks
├── states/               # Modular AI states (Observe, Idle, etc.)
├── bot-tasks/            # AI or manually written task modules
├── memory/               # Memory modules (chat, signs, events, etc.)
├── lib/
│   ├── ai-helper.js      # AI chat integration
│   └── utils.js          # (Optional helper utils)
├── db/
│   └── memory.db         # SQLite database (auto-created)
```

---

## Config (`config.json`)
```json
{
  "bot": {
    "name": "Cletus",
    "host": "192.168.1.90",
    "port": 25565,
    "auth": "offline",
    "version": "1.20.4"
  },
  "ai": {
    "model": "gemma3",
    "ollamaUrl": "http://localhost:11434/api/generate",
    "persona": "a curious minecraft explorer who learns from the world around them",
    "responseLength": 30
  },
  "safeZone": {
    "xBound": 50,
    "yBound": 30,
    "zBound": 50,
    "keywords": ["home", "bed", "base", "village", "farm"]
  }
}
```

---

## 🛠 Prerequisites
- [Node.js](https://nodejs.org/) (v16+)
- [Ollama](https://ollama.ai) running locally with `gemma3` or compatible model
- Minecraft server (1.20.4) with bot permissions

---

## Running the Bot
```bash
npm install
node bot.js
```

Then in Minecraft:
```
Say: Cletus, go find a flower
```

---

## Extending Cletus
- Add new tasks to `/bot-tasks/`
- Add new states to `/states/`
- Memory system will auto-track chat, signs, events
- AI auto-rewrites broken tasks using `chatWithAI()`

---

## AI Improvement Loop
1. You run a task
2. If it fails → AI rewrites the file
3. File is overwritten and reused on next run

---

## Example Tasks
- `find-flower`
- `observe`
- `read-from-sign`
- `idle`

> Want Cletus to do more? Just ask him in chat.