minecraft-ai-god-paper-fork/SESSION.md

# SESSION.md — Minecraft AI God (Paper Fork)

Persistent AI session memory for this project. See `/root/bin/SESSION.md` for the global template and guide.

## Context Files

- `/root/bin/core_homelab.md` — cluster topology, SSH aliases
- `/root/bin/services_directory.md` — active service IPs and domains
- `/root/bin/SESSION.md` — global session memory and patterns
- `./CONTEXT.md` — Minecraft infrastructure, server config, RCON helper
- `./README.md` — Paper fork overview (plugins, build templates, LangGraph gateway)
- Sister repo session memory: `/root/bin/Sethpc-Minecraft/SESSION.md`

---

This document links the two Minecraft AI God projects together, describes their Gitea repos, and serves as the AI session memory for both.

---

## Memory Discipline

- Update `SESSION.md` immediately when a durable fact, decision, or fix is discovered.
- Before every final reply, run a memory check and append any missing durable notes.
- End every reply with one line: `Session memory: updated` or `Session memory: no new durable facts.`

---

## The Two Projects

### Sister repo — minecraft-ai-god (Vanilla)

- **Local path:** `/root/bin/Sethpc-Minecraft`
- **Gitea:** `https://git.sethpc.xyz/Seth/minecraft-ai-god`
- **Purpose:** Vanilla Minecraft 1.21.x, no plugins or mods. All automation via log watching + RCON. Targets the mc1 server (port 25565) and shrink-world server (port 25566) on CT 644.
- **Key services:** `mc-godmode.service`, `mc-shrink-kit.service`, `mc-aigod.service`
- **AI features:** `pray` chat trigger → Ollama LLM → structured JSON → RCON execution; divine intervention timer; shrink-world kit/stats watcher

### This repo — minecraft-ai-god-paper-fork (Paper Advanced Fork)

- **Local path:** `/root/bin/Sethpc-Minecraft-PaperFork`
- **Gitea:** `https://git.sethpc.xyz/Seth/minecraft-ai-god-paper-fork`
- **Purpose:** Dedicated Paper server on port 25567 with plugins (FastAsyncWorldEdit, LuckPerms). Extends the vanilla branch with build templates, expanded command set, sudo translator mode, and LangGraph-style session gateway.
- **Key services:** `mc-paper-ai.service`, `mc-aigod-paper.service`, `mc-langgraph-gateway.service`
- **AI features:** All vanilla features + `sudo build/make/create` deterministic templates, `sudo lookup/wiki/search`, LangGraph gateway sidecar (FastAPI on 127.0.0.1:8091), SQLite session persistence

---

## Relationship Between the Two

This Paper fork is a **direct evolution** of the vanilla repo. They share:

- Same `pray`/`bible`/`sudo` trigger style and chat patterns
- Same two-call LLM split (message + commands JSON schema)
- Same RCON helper (raw socket, no library)
- Same command validation + syntax repair pipeline
- Same intervention timer design (Poisson process, presence guard)

This fork **adds on top of** the vanilla base:

- Plugin-enabled command families (`fill`, `setblock`, `clone`)
- Deterministic build templates before LLM translation
- LangGraph gateway with session memory and tool loop
- `server_type` gating so paper commands don't leak to vanilla targets

Both can run simultaneously — they use separate ports, services, and config files.

---

## Gitea Backup Workflow

Both repos push every committed change to Gitea. This is the standard workflow:

```bash
# From either local repo dir:
git add -A
git commit -m "<description of change>"
git push origin main
```

Both remotes are pre-configured with token auth:

- Vanilla: `https://Seth:<token>@git.sethpc.xyz/Seth/minecraft-ai-god.git`
- Paper fork: `https://Seth:<token>@git.sethpc.xyz/Seth/minecraft-ai-god-paper-fork.git`

The Gitea instance lives at `git.sethpc.xyz` (CT 146, node-173, 192.168.0.125).  
API key: see `GITEA_API.md` in this repo.

**Convention:** commit every meaningful change immediately. Commits are the changelog — no squashing, no batching unrelated changes.

---

## Keeping This File Current

Run `/update-context` in OpenCode at the end of any session to automatically:
1. Review the conversation for new decisions, fixes, and discoveries
2. Append them to `SESSION.md` in both repos
3. Commit and push both repos to Gitea

The command is defined globally at `~/.config/opencode/commands/update-context.md`.

---

## AI Conversation Notes

This section captures decisions and context accumulated across conversations with the AI assistant (OpenCode/Claude). Update it as significant choices are made.

### Architecture decisions

- **No plugins on vanilla servers.** All mc1 and shrink-world automation is pure log-tail + RCON. This keeps the vanilla experience intact and requires no server restarts for updates.
- **Paper fork is separate, not a branch.** Running both as separate services on separate ports was chosen over a single multi-mode script to keep failure domains isolated.
- **LLM backend:** Ollama at `192.168.0.179:11434` for the vanilla service. This fork uses `192.168.0.141:11434` (steel141, local GPU) for better throughput on heavier models (gemma3:12b message model, qwen3-coder:30b command model).
- **Session gateway (this fork only):** The LangGraph-style FastAPI sidecar adds multi-turn memory without requiring a full LangGraph install. Safety enforcement stays in `mc_aigod_paper.py`, not the gateway.
- **Build templates:** Deterministic templates are tried first for `sudo build/make/create` requests. LLM translation is the fallback. This reduces surprises for structure generation tasks.
- **Localized retrieval for sudo reasoning (2026-03-17):** `langgraph_gateway.py` now supports a local knowledge corpus (`/var/lib/mc-langgraph-gateway/knowledge`) with index/search/read tools (`local.search`, `local.read`), optional startup bootstrap from Minecraft/Paper docs URLs, and automatic search->read retrieval hop in sudo tool mode before command generation.
- **Post-deploy behavior check (2026-03-17):** retrieval is active (`tool_trace` shows `local.search` + `local.read`) for `sudo destroy my surroundings`, but generated command remained `execute as <player> run fill ~-5 ~-5 ~-5 ~5 ~5 ~5 air` and produced no useful visible outcome in gameplay (empty/weak RCON feedback). Retrieval alone did not guarantee effective action selection.
- **Sudo execution hardening follow-up (2026-03-17):** added command-shape normalization for sudo (`execute as <player> run ...` -> `execute at <player> run ...`), blocked execute-wrapper bypass in validator (unsafe inner tails like `gameMode` inside `execute ... run`), and added adaptive destructive fallback for failed `destroy/nuke` intents (absolute `fill ... air` around player + TNT summons / TNT kit fallback when position unavailable).
- **Sudo effectiveness feedback loop (2026-03-17):** sudo now scores execution effectiveness from RCON results for all intents, reports translated commands + outcomes + ineffective flag back to gateway session memory (`mode=sudo_feedback`, `feedback_only=true`), and gateway stores this feedback without running extra LLM/tool calls.
- **Lookup contextual memory fix (2026-03-17):** `sudo lookup/search/wiki` now resolves pronoun references (e.g., "that command", "do it again") against the player's most recent executed sudo command, includes that command in lookup context payloads, and passes sudo history into gateway lookup context to improve follow-up reasoning.
- **Gamemode/effect sudo fix (2026-03-17):** Added `gamemode` to safe prefixes/whitelist and command palette, added syntax normalizer for malformed variants (`gameMode s`, short aliases, missing target) and execute-wrapped gamemode forms; confirmed valid RCON forms are `gamemode <mode> <player>` and `effect give <player> <effect> <duration> <amplifier> [hideParticles]`.
- **AI-driven build/template flow (2026-03-17):** `process_sudo` now defaults to non-deterministic build planning (legacy deterministic builder templates disabled unless `sudo_deterministic_build_templates=true`), supports AI-emitted `template ...` meta-commands in sudo execution loop, and includes an AI template planner override for build/make/create prompts when initial translation does not emit template workflow steps.
- **Failed-execution retry pipeline upgrade (2026-03-17):** sudo now runs a generic retry-repair pass on ineffective results before intent fallback. Added TNT-specific repair for malformed `summon tnt ... <count>` outputs (expands into bounded multiple summon commands) and invulnerability-effect repair to valid protection effects. Added `tnt` to destructive-intent keywords so TNT requests can trigger destructive fallback when needed.
- **God voice update (2026-03-17):** Increased default God persona emphasis on irony, dark humor, and sarcastic one-liners in both command and message system prompts (vanilla + Paper variants) while keeping command strictness unchanged.

### Infrastructure decisions

- **mc1 autoStart:** Set to `true` in MCSManager instance config (`/opt/mcsmanager/daemon/data/InstanceConfig/d39f55861cb34204a92a18a9e1c78ca6.json`) so the server starts on CT 644 boot. `mc-godmode.service` uses `tail -F` and handles the log appearing late gracefully.
- **mc-godmode.service startup:** Already enabled (`systemctl is-enabled` = enabled), `WantedBy=multi-user.target`, `After=mcsm-daemon.service`. The service was not failing — the MC server itself wasn't auto-starting (fixed by enabling autoStart in MCSManager config).
- **Paper server location:** `/opt/paper-ai-25567/` on CT 644. Separate from MCSManager-managed instances.

### Open threads / next ideas

- Prayer history log (JSON) for review and tuning
- God mood / divine disposition score persisted across restarts
- Redis backend for gateway sessions (currently SQLite only)
- MCP-based tool adapters in the gateway tool loop
- Richer LangGraph state machine planner node (currently lightweight heuristic router)
- Optional tool trace exposure in-game debug mode
- Web dashboard for recent prayers + God responses (n8n or simple Flask)
- Stricter command schema output at the model/gateway side