Seth/minecraft-ai-god-paper-fork
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
main
minecraft-ai-god-paper-fork/SESSION.md
T

16 KiB
Raw Permalink Blame History

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:

# 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.
  • TNT retry syntax correction (2026-03-17): retry expansion for malformed TNT count commands initially emitted invalid relative coords with ~+1/~+2; corrected generator to use valid forms (~1, ~2) so repaired TNT summons no longer fail with Expected double.
  • User preference (2026-03-17): prioritize context/prompt refinement and better model grounding over adding more deterministic hardcoded action paths.
  • Context-first refinement pass (2026-03-17): added sudo failure memory (sudo_failures) and anti-repeat context block (RECENT FAILED SUDO PATTERNS) into paper sudo translator input and gateway sudo context payload; prompt rules now explicitly forbid repeated failed shapes, old enchant NBT syntax, and summon tnt ... <count> style outputs.
  • Prompt safety clarifications (2026-03-17): updated paper God/system prompts to enforce effect give ... syntax, weather clear|rain|thunder only, and avoid accidental high vertical teleports in benevolent outputs unless explicitly requested.
  • Sudo scope grounding (2026-03-17): paper sudo prompts now explicitly keep target scope narrow (me/my -> requesting player), discouraging broad @a outputs unless explicitly requested.
  • Unresolved post-update issues (2026-03-17): (1) AI template planner override can trigger on non-build sudo intents (example: make me invisible routed into template search/pick/build), and (2) sudo follow-up questions like did that command ...? may not return an informational answer unless phrased with explicit lookup prefixes.
  • Resolved sudo routing issues (2026-03-17): tightened build-intent detection so template planner override only triggers for actual structure/template intents (no longer on generic make me ... phrasing), and broadened sudo info-mode detection to treat natural question-style prompts (e.g., did that command ...?) as lookup queries even without explicit lookup/search/wiki prefix.
  • Remaining issues after routing fix deploy (2026-03-17): (1) sudo still outputs old bow enchant NBT (bow{Enchantments:[...]}) in some runs and fails with trailing-data parse error, and (2) God prayer outputs still occasionally include unnecessary teleport actions (tp ~ ~5 ~) that users report as unhelpful side effects.
  • Bugfix pass after in-game retest (2026-03-17): added command-repair normalizers for (a) old bow enchant NBT to 1.21 component syntax (minecraft:bow[enchantments={...}]), and (b) legacy fire fill syntax (... fire 0 replace air -> ... minecraft:fire replace air), plus dynamic sudo command budget scaling for TNT prompts based on requested quantity (capped by sudo_tnt_max_commands, default 80).
  • Lookup and benevolent TP context refinements (2026-03-17): lookup mode now has local fallback answering for contextual gameplay questions (e.g., invisibility vs mobs) when retrieval returns no hits, and prompts/gateway guidance now explicitly discourage teleport use in helpful responses unless movement is explicitly requested.
  • Post-retest fixes (2026-03-17): added execute-tail syntax repair so command fixers apply inside execute ... run ... payloads (fixes old bow NBT + fill fire variants emitted under execute wrappers), and added TNT quantity expansion from prompt count for summon-heavy intents (bounded by sudo_tnt_max_commands, default 80) when model output under-produces summons.
  • Retest outcome (2026-03-17 late): bow repair now works in live runs (give strongest bow successfully converted old NBT to minecraft:bow[enchantments={...}] and delivered item). Remaining issues: fire-spread requests still often execute as no-op/invalid hybrid fill chains (execute ... run fill ... fire ... with mixed legacy args), and TNT intent can still collapse into single-command failure then destructive fallback (large fill ... air + few TNT) instead of honoring requested count semantics.
  • Late-night retest results (2026-03-18): strongest-bow path is confirmed fixed; lookup follow-up (did that command do what I asked?) still intermittently returns no result; fire-spread prompt still no-ops/invalid despite syntax repair; TNT quantity prompts (spawn 80/20 tnt) still execute a single summon in some runs, indicating quantity expansion is not consistently applied before execution.
  • Follow-up fixes after late-night retest (2026-03-18): added per-player last_sudo_feedback memory and deterministic lookup fallback answer for did that command do what I asked?; expanded execute-tail repair coverage and fire fill metadata repair (... fire 0 replace <block>); disabled destructive air-fill fallback for TNT intents; added fire-intent fallback retry and robust TNT expansion by parsing summon tail from nested execute wrappers.
  • Project governance for bug intake (2026-03-17): bug_log reports from all players are useful advisory input, but direction/prioritization authority remains with project owner (slingshooter08); non-owner reports should be weighted accordingly.
  • 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.
  • Bug-log triage (2026-03-17): bug_log entry confirmed an unintended-feeling movement reward in prayer flow (execute as slingshooter08 run tp slingshooter08 ~ ~10 ~) during a build-oriented prayer; prioritize pray-path teleport safety guards and intent alignment.
  • Bug follow-up (2026-03-17): second bug_log entry reported God feeling "too nice" after greedy follow-up prayer; prompt context updated to bias repeated greedy demands toward corrective responses (rebuke/debuff/symbolic punishment) instead of extra rewards.
  • Teleport safety guard (2026-03-17): added execution-time TP safety wrapper in prayer/intervention path (execute_response) to auto-apply slow_falling + resistance before risky upward teleports, reducing accidental player death from unintended high drops.
  • Bug-log signal upgrade (2026-03-17): bug_log now writes filtered raw server log lines (RCON thread noise removed) and includes recent AI action lines from /var/log/mc_aigod_paper.log for better root-cause visibility.
  • Unaddressed bug triage (2026-03-17): third bug_log entry ("output not in correct format") maps to prayer execution using invalid command weather storm (RCON: Incorrect argument). Current validator allows weather prefix but lacks argument normalization (storm -> rain) and no retry/repair pass for pray-path commands.
  • Weather normalization fix (2026-03-17): added explicit prompt/context rule and code normalizer mapping weather storm|rainstorm|thunderstorm -> weather thunder before validation/execution (paper + vanilla), then redeployed both services.
  • New bug cluster observed (2026-03-17): additional paper bug_log entries report failed command outcomes around selector-based targets and legacy enchant syntax in sudo (minecraft:bow{Enchantments:...}), indicating retry/repair still needed for 1.21 enchantment conversion and selector reliability feedback.

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
Reference in New Issue View Git Blame Copy Permalink