> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baimoqilin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing sessions

> Advanced session workflow, history review, storage layout, and recovery playbook.

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

| Goal                          | Command                                | GUI alternative                            |
| ----------------------------- | -------------------------------------- | ------------------------------------------ |
| Start a clean context         | `/mineclawd sessions new`              | Click **New Session** in the Sessions view |
| See all saved sessions        | `/mineclawd sessions list`             | Open **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 history`                   | Scroll 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`.

<Tip>
  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.
</Tip>

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

```bash theme={null}
/mineclawd sessions repair
```

Or target a specific session:

```bash theme={null}
/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:

```text theme={null}
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.

## Related pages

* [Using the GUI](/tutorials/using-the-gui)
* [/commands/sessions-list](/commands/sessions-list)
* [/commands/sessions-resume](/commands/sessions-resume)
* [/commands/sessions-repair](/commands/sessions-repair)
* [/commands/history](/commands/history)