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.

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:

# 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:

Review the conversation for new decisions, fixes, and discoveries
Append them to SESSION.md in both repos
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.

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

6.2 KiB Raw Blame History