Skip to main content

​
Why session discipline matters

Sessions are MineClawd’s long-term memory. A clean session workflow gives you better answers, fewer context mistakes, and faster recovery when something breaks.

​
How sessions are scoped

  • Sessions are isolated by owner key.
  • Player commands use the player UUID as owner key.
  • Console commands use the command source name as owner key.
  • Each owner has one active session pointer.
  • All session commands require OP permission level 2.

​
Daily command workflow

GoalCommandGUI alternative
Start a clean context/mineclawd sessions newClick New Session in the Sessions view
See all saved sessions/mineclawd sessions listOpen Sessions from the overlay menu
Switch active context/mineclawd sessions resume <session>Click a session row in the Sessions view
Remove stale context/mineclawd sessions remove <session>—
Read current chat history/mineclawd historyScroll through the overlay conversation
Repair malformed Vertex turns/mineclawd sessions repair [session]—
<session> accepts either a short id like 1a2b or a token like 1a2b-my-build-plan.
Prefer the short session id for notes, scripts, and runbooks. The id is stable. The token title part can change after MineClawd generates a better title.

​
Best practices for long tasks

  1. Use one session per objective, not one session for everything.
  2. Rename context by starting fresh sessions instead of dragging old history forever.
  3. Run /mineclawd sessions list before resume, remove, or repair.
  4. Avoid session mutations while a request is still running.
  5. Review context with /mineclawd history before destructive tasks.

​
Using /mineclawd history well

  • The history book shows session token, update time, and visible chat turns.
  • The command only works for players, not console.
  • The history book UI requires MineClawd on the client.
  • Very long history is truncated to Minecraft book page limits.
If your client does not have MineClawd installed, use sessions list plus recent chat logs as your fallback context check.

​
Recovery playbook

​
Request failed but context should stay

Use /mineclawd retry <token> from the latest failure message. Retry tokens expire after 30 minutes.

​
Vertex function-call mismatch errors

Run: 
/mineclawd sessions repair
Or target a specific session: 
/mineclawd sessions repair <session>
repair normalizes malformed Vertex function-call turns and saves the fixed session.

​
Session file locations

MineClawd stores sessions under your game directory: 
mineclawd/
  sessions/
    <owner>/
      active.json
      <id>.json
  • active.json stores the active session id.
  • <id>.json stores metadata and both provider histories (openAiHistory, vertexHistory).
  • If you remove the active session, MineClawd auto-selects the most recently updated remaining session. If none remain, active session is cleared.

​
Backup and cleanup strategy

  1. Back up mineclawd/sessions/ before mass cleanup.
  2. Remove stale sessions with /mineclawd sessions remove <session>.
  3. Keep one known-good session per operator for rapid rollback.
  4. Use /resources/technical-details when you need to inspect storage internals.