stateark

StateArk

プロジェクトについて、AI に二度説明する必要はありません。

チャットは作業スペースであり、アーカイブではありません。StateArk は作業中のセッションをバージョン管理されたポータブルなプロジェクト状態に変換し、新しいチャットで引き継げるようにします。ターミナルを開いて、次を入力します。

npx stateark

その後、Claude Desktop を完全に終了（Cmd+Q）して、再起動します。インストールはこれだけです。

(ソースからインストールしたい場合は、npm install && npm run build && npm run setup を実行してください — INSTALL.md を参照してください。いつでも npx stateark remove で元に戻せます。)

StateArk の開発にあたって私たちが考えていたこと、つまり何百万人ものユーザーが抱える問題への取り組みについて……

You:  ...three hours of work...
You:  Savepoint
      -> my-project v0.3 written to ~/StateArk

      (next day, new chat, empty context)

You:  Resume my-project
      -> decisions, constraints, rejected approaches, open questions,
         and the actual files - all current, none of the detours

デフォルトでローカルに保存。 セーブポイントは、Markdown、JSON、実際のファイルを含む通常のフォルダーです。何もアップロードされません。明日 StateArk がなくなっても、すべてのデータは手元に残ります。

~/StateArk/projects/my-project/v0.3/
  state.md        <- the canonical state, readable in any editor
  state.json
  manifest.json   <- every artifact with its SHA-256
  artifacts/
    app.py
    schema.sql

コマンド

チャットでの入力	動作
Savepoint	セッションをまとめて新しいバージョンを作成します
Resume <project>	最新の状態を新しいチャットに読み込みます
History <project>	バージョンの一覧を表示します
Diff <project>	2 つのセーブポイント間で実際に変更された内容を表示します

ターミナルでの入力
npx stateark	Claude Desktop に登録します
npx stateark report	匿名化されたローカル使用状況の概要を、あなただけに表示します
npx stateark remove	登録を解除します。セーブポイントは保持されます

単なる要約にとどまらない理由

• 引き継ぎ。 再提出しなかったファイルは元のハッシュのまま新しいバージョンにコピーされるため、忘れっぽいモデルがスキーマをひそかに失うことはありません。
• 整合性チェック。 StateArk はチャットを見られないため、確認できる内容をチェックします。切り詰めを示すマーカー（// ... rest unchanged）、サイズが縮小したファイル、状態には記載されているのに一度も渡されていないファイル、直前のセーブポイントと同一のセーブポイントなどです。警告は出しますが、処理をブロックすることはありません。セーブポイントは必ず書き込まれます。
• ジャーナル。 セーブポイント間で、モデルが節目をひそかに記録します。そのため、長いセッションの最後に作成する Savepoint が、劣化したコンテキストに依存することはありません。一度でも保存したことのあるプロジェクトに限られます。試しに使う会話には一切触れません。

必要条件

Node 20 以上。Claude Desktop、または Claude Code（claude mcp add --transport http ...）。 ほかのローカル MCP ホストでも動作し、Codex と Hermes で同じストアを利用できることがユーザーによって確認されています。

ベンダーのクラウドからサーバーに接続するホスト型クライアント（Claude web、 ChatGPT web）は localhost に接続できません。INSTALL.md を参照してください。

複数のエージェントを同時に使う

サポートされています。最初に問題が発生した構成なので、はっきり説明しておく価値があります。 プロジェクトへの書き込みはプロセス間で直列化されるため、2 つのエージェントが同じバージョン番号を取得することはありません。セーブポイントの作成時に別のプロセスが使用中だと報告された場合は、少し待ってから再試行してください。データは失われません。書き込みの途中でプロセスが終了した場合、ロックは自動的に解除されます。

ストアが Dropbox、OneDrive、または iCloud Drive にある場合：1 台のマシン上で複数のエージェントを使うのは問題ありません。2 台のマシンから同じストアに同時に書き込むと同期競合が発生し、同期クライアントが解決します。StateArk では解決できません。

変数	デフォルト値
STATEARK_LOCK_WAIT_MS	60000	諦めるまで、ほかのプロセスを待つ時間
STATEARK_LOCK_STALE_MS	120000	ロックが終了済みプロセスのものと判断されるまでの時間
STATEARK_FS_RETRIES	6	同期クライアントがファイルを開いている場合の再試行回数

ライセンス

Elastic License 2.0。商用利用を含め、あらゆる用途に使用でき、ソースを読んで変更し、パッケージを共有できます。ホスト型サービスまたはマネージドサービスとして第三者に提供することはできません。セーブポイントはあなたのものであり、このライセンスの対象ではありません。

---

アーキテクチャ

ChatGPT / Claude / Gemini-capable MCP client
                 |
                 v
          StateArk Local Agent      <- 127.0.0.1 only, by default
                 |
                 v
        ~/StateArk/projects         <- SOURCE OF TRUTH
                 |
                 | optional
                 v
             Supabase               <- mirror / backup / transport

Savepoint は独自形式のデータベースではなく、通常のディレクトリです。

StateArk/projects/my-project/
  journal.ndjson      # entries recorded since the last savepoint
  project.json        # index (self-healing: rebuilt from disk if corrupt)
  v0.3/
    state.md          # human- and LLM-readable canonical state + integrity warnings
    state.json        # the same state, structured
    meta.json         # version, lineage, platform, sync status, warnings
    manifest.json     # artifacts with SHA-256, stored/pending, carried_forward_from
    journal.ndjson    # the entries this savepoint consolidated
    artifacts/
      app.py
      schema.sql
      prototype.zip

StateArk がなくなっても、これらのファイルは引き続き利用できます。

インストール

Node 20+ が必要です。

npm install
npm run typecheck
npm test          # 97 checks against a throwaway store — run this first
npm start

ローカルのみのモードでは、.env は必要ありません。ポートやストアの保存場所を変更する場合、または Supabase ミラーを有効にする場合に限り、.env.example を .env にコピーしてください。

初回起動時に StateArk はランダムなアクセスキーを生成し、~/StateArk/.access-key に保存します（モード 0600）。起動時のバナーにエンドポイントが表示されます。

MCP:         http://localhost:8787/mcp/<key>
Upload page: http://localhost:8787/upload/<key>
Health:      http://localhost:8787/health

セキュリティモデル

HTTP エントリーポイントは自分のマシン上で動作するローカルサーバーなので、StateArk はアクセスするすべてのウェブページを悪意のあるものと想定します。

制御	デフォルト
バインドアドレス	127.0.0.1（変更するには STATEARK_BIND）
アクセスキー	インストールごとにランダムに生成され、<root>/.access-key に保存されます。定時間比較を行います
Origin ヘッダー	ループバックのみ。STATEARK_ALLOWED_ORIGINS で追加可能
Host ヘッダー	ループバックのみ。STATEARK_ALLOWED_HOSTS で追加可能（DNS リバインディング対策）
CORS	検証済みのオリジンを返し、* は使用しません
アップロードフォーム	1 回限りの CSRF トークン、リクエストボディサイズの上限あり
ループバック以外へのバインド	アクセスキーが 24 文字以上でない限り、起動を拒否します

エージェントを HTTPS 経由で公開する前に、長い STATEARK_ACCESS_KEY を設定し、トンネルのホスト名を STATEARK_ALLOWED_HOSTS に設定して、前段に適切なリバースプロキシを配置してください。

プラットフォームの実情

ローカル優先の環境とホスト型 LLM では、ネットワーク環境が異なります。Claude Desktop/Code やその他のローカル MCP クライアントは、ローカルエージェントに直接接続できます。ホスト型の ChatGPT/Gemini クライアントは、通常、お使いのコンピューター上の localhost に接続できません。利用するには、実行中のローカルエージェントへの安全な HTTPS 経路が必要です。リモートアクセスはロードマップに含まれていますが、現時点ではまだ利用できません。

セットアップする場合は、次の順序で進めてください。

1. StateArk をローカルで実行します。
2. ローカル MCP クライアントから Savepoint と Resume をテストします。
3. 実際にミラーが必要な場合に限り、Supabase 同期を有効にします。
4. 上記の 3 つの手順が成功してから、エージェントを HTTPS 経由で公開します。

ローカルのみのモード — デフォルト

SUPABASE_URL、SUPABASE_SECRET_KEY、STATEARK_OWNER_ID は設定しないでください。クラウド同期は無効のままで、ファイルがマシンの外に送信されることはありません。デフォルトのストアは ~/StateArk です（STATEARK_LOCAL_ROOT で変更できます）。

初期状態ではこの設定です。以下の Supabase セクションはオプトイン方式です。

ローカル + Supabase 同期

Supabase SQL エディターで、次のマイグレーションを順番に実行します。

1. supabase/migrations/001_stateark.sql
2. supabase/migrations/002_artifacts.sql
3. supabase/migrations/003_hardening.sql

次に、SUPABASE_URL、SUPABASE_SECRET_KEY（サーバー側の Secret キー。publishable キーは使用しないでください）、STATEARK_OWNER_ID、STATEARK_STORAGE_BUCKET を設定します。

クラウドはミラーであり、マスターではありません。

• ローカルのセーブポイントが先にコミットされるため、クラウド側でエラーが発生しても無効にはなりません。
• クラウド上で削除しても、ローカルデータは削除されません。
• 同期ステータスは meta.json（disabled / pending / synced / failed）に保存されます。
• 失敗したプッシュは sync_savepoint ツールで再試行できます。

2 MB 以下のテキスト／コードのアーティファクトは Postgres にインラインでミラーされ、それ以外は非公開の Storage バケットに保存されます。ミラーはエンドツーエンド暗号化されていません。Supabase プロジェクトは保存したデータを読み取ることができます。まさにその理由から、同期はデフォルトで無効です。ホスト型データベースに保存しても問題ないプロジェクトに限り、有効にしてください。

Savepoint の動作

Savepoint と指示された場合、ホスト LLM は次のようにする必要があります。

• 時系列を要約するのではなく、最新の有効な状態を再構成します。
• 判断の基準となる決定事項、要件、制約を保持します。
• 却下されたアプローチは、その理由が重要な場合に限り残します。
• 正確なテキスト／コードは transfer=text として送信します。
• バイナリデータは、実際に利用可能な場合に限り、transfer=base64 として送信します。
• それ以外の場合は、アーティファクトを捏造せず、transfer=pending とします。
• 変更されていないファイルは 省略 します。これらは自動的に引き継がれます。
• ファイルを ... rest unchanged と省略することは 絶対にしません。

ローカルでの作成はアトミックです。StateArk は一時バンドルを書き込み、完了した場合にのみ名前を変更します。アーティファクト名はサニタイズされます。名前を変更する必要があった場合、manifest.json に元の名前が original_name として記録されます。

整合性チェック

各セーブポイントは、その直前のバージョンと比較されます。検出結果はツールの 結果に返され、state.md の先頭に表示されます。セーブポイントは常に書き込まれます。チェックによって作業が失われることはなく、モデルに正直な説明を促すだけです。

コード	意味
artifact_carried_forward	ファイルが再送信も削除宣言もされていないため、前のバージョンからコピーされました
artifact_became_pending	保存済みだったコンテンツが、保留中になりました
artifact_shrank	ファイルのサイズが以前の50％未満に縮小しました
truncation_marker	保存されたテキストに ... rest unchanged、[...]、… gekürzt などが含まれています
no_change	このセーブポイントは直前のものと同一です
journal_not_reflected	決定事項がジャーナルに記録されましたが、送信された状態には何も記載されていません
artifacts_mentioned_but_missing	状態テキストで、成果物として一度も渡されていないファイル（schema.sql、app.py、…）が言及されています

実際の運用で最も重要なのは最後のチェックです。StateArk はチャットを読めないため、文章中にファイル名が出てくることだけが、モデルがファイルを保持する代わりに説明したことを示す手がかりです。ファイルは計画中、または会話の外に存在する可能性もあるため、警告は質問形式になっています。

ジャーナル

note_event は、転換点ごとに短い行をひとつ、何も表示せずに記録します。対象は、すでに StateArk に登録されているプロジェクトのみです。未追跡のプロジェクトは tracked: false を返し、何も書き込まれません。これにより、作業用の一時的な会話が除外されます。

次のセーブポイントで、ジャーナルは新しいバージョンに統合され、クリアされます。セーブポイントがディスクに確実に書き込まれる前にクリアされることはありません。

保留中のエントリーは journal ツールで確認できます。通知は時間ではなく、エントリー数（STATEARK_JOURNAL_NUDGE_AT、デフォルトは20）に基づいて行われます。

差分

バージョン引数を指定せずに diff_savepoints を実行すると、最新のセーブポイントとその直前のものが比較されます。テキストフィールドには行単位の LCS 差分、リストには集合差分、成果物には SHA-256 の比較が適用され、気付かれないまま失われた可能性があるものは attention ブロックに表示されます。

成果物

保存されたすべての成果物には SHA-256 が付与されます。保留中のファイルは manifest.json と resume_project の出力に明示されるため、LLM がファイルの存在をこっそり装うことはできません。

バイナリを MCP 経由で送信できない場合は、起動時に表示されたローカルアップロードページを開き、既存のプロジェクト／バージョンに添付してください。これにより、保留中のマニフェスト項目が解決されます。

再開

Resume My Project は state.md と成果物マニフェストを返します。LLM は必要な場合にのみ、正確なテキストを取得するため get_artifact を呼び出します。バイナリの場合は、内容を捏造する代わりに、検証済みのローカルパスとハッシュを取得します。

MCP クライアント

• Claude Desktop — npx stateark が stdio エントリーポイントを登録します。
• Claude Code — ローカルの Streamable HTTP エンドポイントを指定します： claude mcp add --transport http ...
• Codex、Hermes、その他のローカル MCP ホスト — 同じストアルートを指定すると、セーブポイントを共有できます。クライアントはそれぞれ個別に設定する必要があり、共有設定はありません。StateArk はストアのレイアウトを説明する README.md をストアに書き込みます。ほとんどのコーディングエージェントは自分でこれを読み込みます。
• ChatGPT web/mobile、Gemini、その他のホスト型クライアント — ベンダーのクラウドからサーバーに接続するため、お使いのマシン上の localhost にはアクセスできません。これはネットワーク上の制約であり、機能の不足ではありません。ホスト型クライアントからセーブポイントにアクセスするには、お使いのマシンへの認証済み HTTPS ルートが必要です。これはロードマップに含まれていますが、まだ実装されていません。

ロードマップ

現時点では、まだ何も実装されていません。おおよそ次の順で進める予定です。

• オプションのクラウドストレージ — セーブポイントをミラーリングし、ノートパソコンが故障してもプロジェクトを失わないようにします。デフォルトではオフで、あくまでコピーのみです。ディスク上のデータが常にオリジナルです。
• リモートアクセス — デスクトップアプリがある1台のマシンだけでなく、ウェブやモバイルのクライアントから状態にアクセスできるようにします。
• ブランチ — 現在、同じプロジェクトで2つのチャットを使うと、バージョンが1本の直線的な履歴になります。課題として認識していますが、未解決です。
• 状態の整理 — セーブポイントを重ねるうちに、state.md は際限なく大きくなります。サイズ上限と、古い情報を整理するルールが必要です。

StateArk は、商用利用を含め、無料で使用できます。許可されていない唯一のことについては、上記のライセンスをご確認ください。