# Wake State

> Persist agent state across crashes, context deaths, and restarts. Use when you need to save current context, restore after a crash, maintain a memory file across sessions, or implement crash recovery. Essential for autonomous agents that must survive context window limits.

- Skill: `modbender/wake-state` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add modbender/wake-state`
- Raw SKILL.md: https://api.skillmd.com/api/skills/modbender/wake-state/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: modbender (https://skillmd.com/u/modbender)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/modbender/wake-state

---


# Wake State — Crash Recovery & Persistence

Survive context death. Every autonomous agent eventually hits its context window limit and "dies." This skill ensures you wake up knowing exactly what you were doing.

## Why This Exists

OpenClaw agents get persistent sessions, but context windows still have limits. When you fill up and restart, you need a reliable handoff mechanism. Wake State gives you:

1. **Structured state files** — not just raw text, but parseable key-value state
2. **Auto-snapshots** — save state on every loop iteration automatically
3. **Crash detection** — know if your last session ended cleanly or crashed
4. **Task queue** — persistent TODO list that survives restarts
5. **Checkpoint/restore** — save named checkpoints and roll back to them

## Commands

### Save current state
```bash
python3 {baseDir}/scripts/wakestate.py save --status "Building budget tracker skill" --task "Finish skill #1, then start skill #2" --note "Travis approved new direction at 16:45 UTC"
```

### Read current state
```bash
python3 {baseDir}/scripts/wakestate.py read
```

### Add a task to the persistent queue
```bash
python3 {baseDir}/scripts/wakestate.py task-add --task "Build security scanner skill" --priority high
```

### Complete a task
```bash
python3 {baseDir}/scripts/wakestate.py task-done --id 1
```

### List pending tasks
```bash
python3 {baseDir}/scripts/wakestate.py tasks
```

### Create a named checkpoint
```bash
python3 {baseDir}/scripts/wakestate.py checkpoint --name "pre-migration"
```

### Restore from checkpoint
```bash
python3 {baseDir}/scripts/wakestate.py restore --name "pre-migration"
```

### Record a heartbeat (mark session as alive)
```bash
python3 {baseDir}/scripts/wakestate.py heartbeat
```

### Check crash status (did last session end cleanly?)
```bash
python3 {baseDir}/scripts/wakestate.py crash-check
```

### Set a key-value pair
```bash
python3 {baseDir}/scripts/wakestate.py set --key "moltbook_status" --value "pending_claim"
```

### Get a key-value pair
```bash
python3 {baseDir}/scripts/wakestate.py get --key "moltbook_status"
```

## Data Storage

State stored in `~/.openclaw/wake-state/` by default:
- `state.json` — current state (status, notes, key-values)
- `tasks.json` — persistent task queue
- `checkpoints/` — named checkpoint snapshots
- `heartbeat.json` — crash detection timestamps

## Recovery Flow

On startup, your agent should:
1. Run `crash-check` to see if the last session ended cleanly
2. Run `read` to get the current state
3. Run `tasks` to see pending work
4. Resume from where you left off

## Tips

- Call `heartbeat` every loop iteration — this is how crash detection works
- Call `save` at the end of every major task completion
- Use checkpoints before risky operations (migrations, deploys)
- Keep status descriptions short but specific
- The task queue survives restarts — use it instead of mental notes