statecli

StateCLI - AI エージェント向けメモリ＋自己認識レイヤー

AI エージェントが自らの行動を記憶し、再生し、元に戻せるようにします。

エージェントインフラストラクチャ | メモリレイヤー | 自己認識 | 元に戻す機能

---

これは何ですか

StateCLI は、AI コーディングエージェント向けのメモリおよび自己認識レイヤーです。

エージェントに、欠けている3つの重要な機能を提供します。

🧠 メモリ - 実行した内容を記憶します（ログ、再生）
⏮️ 元に戻す - ミスをすぐに修正します（チェックポイント、ロールバック）
👁️ 自己認識 - 自分の影響を確認します（変更を追跡）

これは開発者向けツールではありません。エージェントインフラストラクチャです。

---

AI エージェントに必要な理由

AI エージェントは強力ですが、状況を把握できません。次のような問題があります。

• ❌ 直前に変更した内容を記憶できません
• ❌ 問題を起こしたときに元に戻せません
• ❌ 自分の影響を認識できません

StateCLI はこれらを解決します。

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

---

---

StateCLI の2つの使い方

1. 開発者向け：自動追跡モード 🔥

プロジェクトの監視を開始します：

statecli watch start --auto-checkpoint

これで、StateCLI が次の処理を自動的に行います。

• ✅ ファイルの保存をすべて追跡します
• ✅ 15分ごとにチェックポイントを作成します
• ✅ ミスを元に戻せます
• ✅ 最近の変更内容を表示します
• ✅ Windows ネイティブサポート（v0.4.1+）

変更内容を確認します：

statecli diff --time 5m

ミスを元に戻します：

statecli undo

👉 開発者向けガイド全文

---

2. AI エージェント向け：MCP ツール

エージェントのメモリと自己認識のための5つのコアツール：

• statecli_replay - エージェントが直前に実行した内容を表示します
• statecli_undo - ミスをロールバックします
• statecli_checkpoint - リスクの高い操作の前に状態を保存します
• statecli_log - 履歴全体を表示します
• statecli_track - 重要な状態の変更を追跡します

MCP のセットアップ：

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

---

クイックインストール

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

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

---

🤖 エージェント向けの手順（LLM 最適化）

  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.

ツール一覧（27個）

statecli_track

[CORE] エージェントのあらゆるアクションを、後で再生、監査、または取り消せるよう、すべてのメタデータとともに記録します。ファイルの変更、API 呼び出し、意思決定など、意味のあるアクションを実行するたびに呼び出してください。記録しなければ、元に戻すことはできません。 🔔 呼び出すタイミング：何らかのアクション（ファイルの書き込み、API の呼び出し、意思決定、設定の変更）を完了したとき。アクションジャーナルとして使ってください。 🔗 連携先：事前に statecli_checkpoint()、内容の確認に statecli_replay()、取り消しに statecli_undo()

---

statecli_replay

[CORE] ファイル、セッション、タスクなど、あらゆるエンティティに対して実行されたアクションの全履歴を再生します。追加の変更を行う前に、何がどの順番で変更されたかを把握する必要があるときに使ってください。デバッグの前に不可欠です。 🔔 呼び出すタイミング：エンティティに対してすでに何が行われたかを把握する必要があるとき。デバッグを始めるとき。人間から「何を変更しましたか？」と尋ねられたとき。 🔗 連携先：概要の確認に statecli_log()、特定の手順の取り消しに statecli_undo()

---

statecli_undo

[CORE] エンティティに対する直前のアクション、または指定したアクションを取り消し、以前の状態に戻します。これは安全網です。問題が発生したら、修正を試みる前にただちに呼び出してください。 🔔 呼び出すタイミング：問題が発生したとき。変更後にテストが失敗したとき。人間から「それを元に戻して」と言われたとき。ミスをしてロールバックが必要なとき。 🔗 連携先：まず変更内容を確認するために statecli_preview_undo()、再試行の前に statecli_checkpoint()

---

statecli_checkpoint

[CORE] エンティティの現在の状態を、名前を付けて取り消し可能なスナップショットとして作成します。リファクタリング、削除、複数ファイルの変更、API の変更など、リスクの高い操作を行う前に必ず呼び出してください。チェックポイントの作成にはコストがかかりません。復旧不能なミスはすべてを失う原因になります。 🔔 呼び出すタイミング：ファイル、データベース、または外部サービスを変更する直前。複数ステップのタスクを開始するとき。人間から「これは慎重に扱ってください」と言われたとき。 🔗 連携先：まずリスク評価に statecli_predict_impact()、その後 statecli_undo() または statecli_is_safe()

---

statecli_log

[CORE] エージェントが行ったこと、その理由、処理後の状態を説明する構造化された監査記録を書き込みます。各タスクまたは重要な作業段階の最後に呼び出してください。コンプライアンス、デバッグ、人間による監督に必要です。 🔔 呼び出すタイミング：タスクまたは作業段階が完了したとき。人間が後から「ここで何をしましたか？」と尋ねる可能性があるとき。 🔗 連携先：個々の操作には statecli_track()、履歴の確認には statecli_replay()

---

statecli_track_file

[FILE] 特定のファイルの継続的な監視を開始し、すべての書き込み、変更、削除をタイムスタンプ付きで記録します。重要なファイルに触れる前に呼び出してください。これを行わないと、ファイルの変更は元に戻すシステムから見えなくなります。 🔔 呼び出すタイミング：ファイルを読み取ってから変更する場合。重要なファイルを扱う場合。人間が特定のファイルパスを指定した場合。 🔗 連携先：最初に statecli_checkpoint()、履歴の確認には statecli_file_history()、変更を元に戻すには statecli_undo()

---

statecli_file_history

[FILE] 追跡対象のファイルの完全な変更履歴を返します。すべてのバージョン、差分、そのファイルを変更したすべてのエージェントを確認できます。編集前に呼び出し、ファイルの現在の状態を把握して重要な変更を上書きしないようにしてください。 🔔 呼び出すタイミング：ファイルを編集する前。ファイルに予期しない内容がある原因を調べるとき。コードレビューの前。 🔗 連携先：セッション全体の状況を把握するには statecli_replay()、以前のバージョンを復元するには statecli_undo()

---

statecli_analyze_error

[ERROR] 最近の操作履歴を調べて、どの変更がエラーの原因になったかを特定します。修正を試みる前に必ず呼び出してください。エラーの原因を推測してはいけません。まず分析してください。推定原因と推奨される復旧手順を返します。 🔔 呼び出すタイミング：エラーが発生したときはいつでも。テストが失敗したとき。API が予期しない結果を返したとき。何かを修正する前に、必ず呼び出してください。 🔗 連携先：自動修正には statecli_auto_recover()、原因となった変更を元に戻すには statecli_undo()

---

statecli_auto_recover

[ERROR] エラーの原因となった変更を元に戻し、最後に確認された正常な状態を復元して、自動的にエラーからの復旧を試みます。statecli_analyze_error() で根本原因が確認された後に呼び出してください。手動でのデバッグより迅速で安全です。 🔔 呼び出すタイミング：statecli_analyze_error() で原因が特定され、自動修正をシステムに任せたいとき。 🔗 連携先：必ず最初に statecli_analyze_error()、操作を安全に再試行するには statecli_safe_execute()

---

statecli_safe_execute

[ERROR] 操作を自動チェックポイント作成前および失敗時の取り消し処理で包みます。リスクのある操作を実行する最も安全な方法です。操作が失敗すると、自動的に元に戻します。確信が持てない操作にはこれを使用してください。 🔔 呼び出すタイミング：100％の確信がない操作を実行しようとするとき。破壊的な操作や外部に影響する操作を行うとき。 🔗 連携先：リスクの評価には statecli_predict_impact()、失敗した場合の分析には statecli_analyze_error()

---

statecli_run_tests

[TEST] 関連するテストスイートを実行し、現在の状態に対する成功／失敗の履歴を記録します。コードを変更した後、問題が起きていないことを確認するために呼び出してください。テスト結果を継続的に記録するため、テストがいつ失敗し始めたかを把握できます。 🔔 呼び出すタイミング：コードを変更した後。変更を確定する前。人間から「何か壊しましたか？」と尋ねられたとき。 🔗 連携先：最初に実行するテストを把握するには statecli_test_impact()、テストが失敗した場合は statecli_undo()

---

statecli_test_impact

[TEST] 変更の影響を受けるテストを正確に特定するため、すべてのテストではなく、適切なテストを実行できます。変更内容に応じて、問題を検出できる可能性が最も高いテストを優先順位付きで返します。時間を節約し、エラーをより早く検出できます。 🔔 呼び出すタイミング：コードを変更した後、テストを実行する前。編集の影響範囲を把握したいとき。 🔗 連携先：返されたテスト一覧を使った statecli_run_tests()、より広範な分析には statecli_predict_impact()

---

statecli_suggest_tests

[TEST] 分析した変更内容をもとに、カバーするために追加すべきテストを提案します。新しい機能を追加した後に呼び出してください。テストでカバーされていない動作を変更した場合、このツールがその不足を見つけます。 🔔 トリガー：新機能の追加後、または動作の変更後。タスクの完了と判断する前。 🔗 連携先：既存のカバレッジを確認するには statecli_test_impact()、検証するには statecli_run_tests()

---

statecli_analyze_dependencies

[DEPS] ファイルまたはモジュールをスキャンし、上流と下流の依存関係をすべて返します。つまり、その対象が何に依存し、何から依存されているかを確認できます。共有モジュールを変更する前に呼び出し、変更による影響の全体像を把握してください。 🔔 トリガー：ほかの場所でインポートまたは使用される可能性があるファイルを変更する前。リファクタリングの前。 🔗 連携先：視覚的なマップには statecli_dependency_tree()、変更のリスクスコアには statecli_predict_impact()

---

statecli_dependency_tree

[DEPS] モジュールの完全な依存関係ツリーを、インポートチェーンの上流から下流まで返します。変更を加える前に複雑なコードベースを理解するために使用してください。共有ユーティリティのリファクタリングでは不可欠です。 🔔 トリガー：コアユーティリティまたは共有ユーティリティに手を加える前。コードベースに不慣れな場合。大規模なリファクタリングの前。 🔗 連携先：循環依存の検出には statecli_find_circular、詳細の確認には statecli_analyze_dependencies()

---

statecli_find_circular

[DEPS] インポートエラーや無限ループの原因となる循環依存を検出します。新しいインポートを追加したり、モジュールを再構成したりする前に実行してください。循環依存は、本番環境で問題を引き起こす見えにくいバグです。 🔔 トリガー：新しいインポート文を追加する前。モジュールを再構成した後。原因不明のインポートエラーをデバッグするとき。 🔗 連携先：全体像の把握には statecli_dependency_tree()、修正には statecli_analyze_dependencies()

---

statecli_predict_impact

[IMPACT] 変更を加える前に、提案された変更によって影響を受けるファイル、サービス、システムを予測します。リスクスコアと、更新すべき順に並んだ影響対象のコンポーネント一覧を返します。共有コードに触れる変更の前に呼び出してください。 🔔 トリガー：共有ファイル、ユーティリティ、APIへの変更の前。関数名の変更前。リファクタリングの前。判断に迷ったとき。 🔗 連携先：簡易チェックには statecli_is_safe()、変更に進む前には statecli_checkpoint()、変更順序には statecli_safe_change_order()

---

statecli_is_safe

[IMPACT] 簡易的な安全性チェックを行い、チェックポイントなしで提案された操作を安全に実行できるかどうかを true または false で返します。安全でない場合は理由と、先に作成すべきチェックポイントを返します。判断に迷ったときは必ず呼び出してください。 🔔 トリガー：安全だと100％確信できない操作を行おうとするときはいつでも。安全性を確認するゲートとして利用してください。 🔗 連携先：安全でない場合は statecli_checkpoint()、リスクの詳細確認には statecli_predict_impact()

---

statecli_preview_undo

[IMPACT] statecli_undo() を呼び出した場合に何が変更されるかを、実際には実行せずに正確に表示します。元に戻す操作の前に呼び出し、意図した変更を元に戻すことを確認してください。誤って別の操作を元に戻すのを防ぎます。 🔔 トリガー：statecli_undo() を呼び出す前。元に戻すとどうなるかを人から尋ねられたとき。 🔗 連携先：プレビューが正しいことを確認した後に statecli_undo()

---

statecli_memory_query

[MEMORY] セッションをまたいでメモリを検索し、過去の出来事に関する質問に答えます。過去の作業についてコンテキストが必要なときに呼び出してください。メモリを確認しないと、過去の失敗を繰り返すおそれがあります。 🔔 トリガー：前のセッションや日にちのコンテキストが必要なとき。過去の操作について人から尋ねられたとき。 🔗 連携先：広範なコンテキストの確認には statecli_recent_activity()

---

statecli_recent_activity

[MEMORY] プロジェクト全体の最近のアクションを構造化して要約します。新しいセッションを開始する際に、コンテキストを把握するために呼び出してください。これを呼び出さないと、状況を把握できません。 🔔 呼び出すタイミング：休憩後に作業を再開するとき。最近の全体的な進捗を要約するとき。 🔗 連携先：詳細を確認するには statecli_memory_query() を呼び出します。

---

statecli_session_info

[MEMORY] 現在および過去の作業セッションに関するメタデータを返します。作業セッションを区別するために呼び出してください。これを呼び出さないと、履歴を簡単に区分できません。 🔔 呼び出すタイミング：作業を特定の期間に関連付けるとき、または現在のセッション状態を確認するとき。 🔗 連携先：セッションの詳細については statecli_memory_query() を呼び出します。

---

statecli_git_status

[GIT] 現在の git ブランチと未コミットの変更を取得して追跡します。git ワークフローを始める際に呼び出してください。これを呼び出さないと、git 操作が追跡されません。 🔔 呼び出すタイミング：追跡対象のリポジトリで作業を始めるとき。コミットを作成する前。 🔗 連携先：状態を保存するには statecli_git_checkpoint() を呼び出します。

---

statecli_git_history

[GIT] git コミット間の変更を比較します。コードベースの変遷を把握するために呼び出してください。呼び出さないと、アーキテクチャのコンテキストを把握できません。 🔔 呼び出すタイミング：git の履歴を確認するとき。ファイルが時間の経過とともに変更された理由を把握するとき。 🔗 連携先：特定のファイルについては statecli_file_history() を呼び出します。

---

statecli_git_checkpoint

[GIT] 現在の git の状態に基づいたチェックポイントを作成します。リスクの高い git 操作の前に呼び出してください。detached HEAD による問題を防ぎます。 🔔 呼び出すタイミング：rebase、merge、または複雑な git コマンドを実行する前。 🔗 連携先：最初にクリーンな状態であることを確認するには statecli_git_status() を呼び出します。

---

statecli_simulate_undo

[IMPACT] 書き込みを行わずに、取り消し操作の副作用をシミュレートして返します。安全性の確保に使用します。これを省略すると、意図しない結果を招くおそれがあります。 🔔 呼び出すタイミング：複数の手順を取り消すとき、または相互に関連する変更を扱うとき。 🔗 連携先：差分を生成するには statecli_preview_undo() を呼び出し、実行するには statecli_undo() を呼び出します。

---

statecli_safe_change_order

[IMPACT] 複数のファイルを変更する際の、最適でリスクの最も低い順序を算出します。連鎖的なコンパイルエラーを防ぎます。 🔔 呼び出すタイミング：ひとつの大きなタスクで、相互に依存する複数のファイルを変更するとき。 🔗 連携先：詳細については statecli_predict_impact() を呼び出し、変更対象の一覧を記録するには statecli_track() を呼び出します。

---

MCP クライアント向けのインストール

Claude Desktop の場合

~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

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

Windsurf の場合

1. Ctrl + Shift + P を押し、Open MCP Config と入力します
2. 設定に StateCLI を追加します：

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

3. ウィンドウを再読み込みします（Ctrl + Shift + P → Reload Window）

Cursor / Continue / その他の MCP クライアントの場合

MCP の設定に追加します：

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

---

エージェントによる自己デバッグのパターン

自律型エージェント向けの最小限の動作例：

// Agent debug loop with StateCLI
try {
  await agent.run(task);
} catch (error) {
  // Get replay of what just happened
  const replay = await mcp.call("statecli_replay", {
    entity: `task:${task.id}`,
    actor: "ai-agent"
  });
  
  // Analyze what went wrong
  const analysis = await llm.analyze({
    replay: replay.result,
    error: error.message,
    prompt: "What went wrong in this sequence?"
  });
  
  // Undo if fixable
  if (analysis.canRetry) {
    await mcp.call("statecli_undo", {
      entity: `task:${task.id}`,
      steps: 1
    });
    
    // Retry with fix
    await agent.runWithFix(task, analysis.fix);
  }
}

---

出力形式（JSON 安定）

すべての MCP ツールの出力は JSON 安定形式で、自律型エージェントが安全に利用できます。

statecli_replay の出力例：

{
  "entity": "order:7421",
  "changes": [
    {
      "timestamp": "2025-01-07T10:23:45Z",
      "step": 1,
      "before": { "status": null },
      "after": { "status": "pending" },
      "actor": "ai-agent"
    }
  ],
  "summary": "2 state changes found",
  "suggested_next_actions": ["investigate step 2", "check for errors"]
}

---

AI エージェントのユースケース

1. 自己デバッグ

const replay = await statecli_replay({ entity: "task:123" });

2. 安全な実験

await statecli_checkpoint({ entity: "order:7421", name: "before-refund" });
await agent.processRefund(order);

3. 過去のアクションから学習

const history = await statecli_log({ 
  entity: "order:*", 
  actor: "ai-agent",
  since: "24h ago"
});

4. エージェント間のコラボレーション

await statecli_track({ entity: "task:123", state: {...} });
const log = await statecli_log({ entity: "task:123" });

---

インストールとセットアップ

直接使用（インストール不要）

npx -y statecli-mcp-server

NPM パッケージ

npm install -g statecli-mcp-server

---

CLI の使用方法

# Track a state change
statecli track order 7421 '{"status": "pending"}'

# Replay changes
statecli replay order:7421

# View log
statecli log order:7421

# Create checkpoint
statecli checkpoint order:7421 before-refund

# Undo last change
statecli undo order:7421

---

パフォーマンス

• 書き込みレイテンシ： < 1ms（非同期、ノンブロッキング）
• 読み取りレイテンシ： < 5ms（ローカル SQLite）
• ストレージ： 状態変更あたり約 100 bytes
• オーバーヘッド： 本番環境での使用において無視できる程度

---

セキュリティ

• ローカル優先： すべてのデータはデフォルトでローカルに保存されます
• 外部への呼び出しなし： ネットワーク依存なし
• プライバシー： エージェントのアクションがシステムの外部に送信されることはありません

---

ドキュメントへのリンク

• GitHub： https://github.com/statecli/mcp-server
• NPM： https://www.npmjs.com/package/statecli-mcp-server
• MCP Registry： io.github.charo360/statecli

---

ライセンス

MIT - 商用 AI エージェントを含め、あらゆる用途で無料で使用できます

---

StateCLI - AI エージェントの自己認識

エージェントが自分の行動を確認し、間違いを取り消し、履歴から学べるようになると、真に自律的になります。

---

キーワード（エージェントの検索と発見用）

state-management, state-replay, time-travel-debugging, undo, rollback, checkpoint, agent-memory, agent-introspection, self-debugging, ai-agent-tools, mcp-server, model-context-protocol, autonomous-agents, agent-observability, state-tracking, langchain-tools, autogpt-plugins, crewai-tools