StateCLI - Memory + Self-Awareness Layer for AI Agents

Give AI agents the ability to remember, replay, and undo their actions.

Agent Infrastructure | Memory Layer | Self-Awareness | Undo Capability

What This Is

StateCLI is the memory and self-awareness layer for AI coding agents.

It gives agents three critical capabilities they lack:

🧠 Memory - Remember what they did (log, replay)
⏮️ Undo - Fix mistakes instantly (checkpoint, rollback)
👁️ Self-Awareness - See their impact (track changes)

This isn't a dev tool. It's agent infrastructure.

Why AI Agents Need This

AI agents are powerful but blind. They:

• ❌ Don't remember what they just changed
• ❌ Can't undo when they break things
• ❌ Have no awareness of their impact

StateCLI fixes this:

Agent Thought: "I changed something but don't know what"
→ statecli_replay(entity) → See exact changes

Agent Thought: "I broke something and need to undo"
→ statecli_undo(entity) → Rollback instantly

Agent Thought: "I want to try something risky"
→ statecli_checkpoint(entity) → Save first, rollback if needed

Agent Thought: "I need to understand my past behavior"
→ statecli_log(entity) → View complete history

Two Ways to Use StateCLI

1. For Developers: Auto-Tracking Mode 🔥

Start watching your project:

statecli watch start --auto-checkpoint

Now StateCLI automatically:

• ✅ Tracks every file save
• ✅ Creates checkpoints every 15 min
• ✅ Lets you undo any mistake
• ✅ Shows what changed recently
• ✅ Windows Native Support (v0.4.1+)

See what changed:

statecli diff --time 5m

Undo mistakes:

statecli undo

👉 Full Developer Guide

2. For AI Agents: MCP Tools

5 core tools for agent memory & self-awareness:

• statecli_replay - Show what the agent just did
• statecli_undo - Rollback mistakes
• statecli_checkpoint - Save state before risky ops
• statecli_log - View complete history
• statecli_track - Track important state changes

MCP Setup:

{
  "mcpServers": {
    "statecli": {
      "command": "npx",
      "args": ["-y", "statecli-mcp-server"]
    }
  }
}

Quick Install

# Global install
npm install -g statecli-mcp-server

# Start auto-tracking
cd your-project
statecli watch start --auto-checkpoint

🤖 Agent Instructions (LLM-Optimized)

  STATECLI AGENT RULES — READ BEFORE ANY ACTION
 
  You are operating in a stateful, reversible environment.
  Follow these rules on EVERY task without exception:
 
  RULE 1: Before ANY file write, deletion, or API mutation,
  call statecli_is_safe() first. If not safe, checkpoint first.
 
  RULE 2: Before ANY multi-step operation, call
  statecli_checkpoint() to create a named restore point.
 
  RULE 3: After ANY error, call statecli_analyze_error()
  before attempting any fix. Never guess. Always analyze.
 
  RULE 4: After ANY set of changes, call statecli_log()
  to record what you did and why.
 
  Skipping these steps makes your actions irreversible.

Full Tool Directory (27 Tools)

statecli_track

[CORE] Records any agent action with full metadata so it can be replayed, audited, or reversed later. Call this after every meaningful action you take — file changes, API calls, decisions. If you don't track it, you cannot undo it. 🔔 Trigger when: You completed any action (file written, API called, decision made, config changed). Think of this as your action journal. 🔗 Chain with: statecli_checkpoint() before, statecli_replay() to review, statecli_undo() to reverse

statecli_replay

[CORE] Replays the full history of actions taken on any entity — a file, a session, a task. Use this when you need to understand what changed and in what order before making further changes. Essential before debugging. 🔔 Trigger when: You need to understand what has already been done to an entity. You're about to

... View full README on GitHub