henryqin1997/statem

What it solves

StateM addresses the instability of long-running AI agents by preventing the "collapse" of complex workflows into a single, oversized prompt. It solves the problem of agents losing track of their goals, failing to verify progress, or being unable to resume a session because the procedural state was stored only in the model's volatile chat history.

How it works

StateM implements a command-line state machine that moves the agent's workflow into a versioned "runbook" (a YAML file). This runbook defines a graph of states (nodes) and legal transitions (edges).

• State Management: Instead of relying on memory, the agent queries the CLI to find its current state, available transitions, and required actions.
• Executable Gates: Transitions are protected by "before_transfer" checks—such as shell commands, checklists, or LLM reviews—that must pass before the agent can move to the next state.
• Durable History: All transitions, evidence, and timestamps are persisted to disk, allowing agents to resume work after a context refresh or session clear.
• Dynamic Checks: Agents can register task-specific verification steps during runtime that aren't predefined in the static runbook.

Who it’s for

It is designed for developers building autonomous AI agents that perform complex, multi-step tasks (like coding or system deployment) where reliability, auditability, and strict verification are required.

Highlights

• Explicit Phase Boundaries: Separates planning, execution, review, and recovery into distinct, manageable states.
• Executable Transition Gates: Uses real-world checks (e.g., pytest exit codes) to block invalid state transitions.
• Durable Runtime History: Persists state and results locally, ensuring the agent survives context window limits or crashes.
• Host-Agnostic: Works with any agent capable of running shell commands, with existing integrations for Claude Code and Codex.
• Context Lifecycle Support: Provides tools to generate resume and compaction prompts for long-running cyclic workflows.