Turritopsis

長期プロジェクトのための共有ハンドオフレイヤー。

1人の人間 + 4つのエージェント。71日間。50万行のアクティブコード。

エージェントは去りゆく。プロジェクトは忘れるべきではない。

あなたのコーディングエージェントはコードを読むことができます。Turritopsis はそれを伝えます：

• 今何が真実か；

• なぜプロジェクトがこのようになったのか；

• 現在の作業がどこで止まったか；

• 何がすでに失敗したか；

• どの境界を破ってはならないか；

• そしてどこから続けるか。

list_stages()
search_stages("why is release frozen?")
get_stage("project.handoff")

Turritopsis は、プライベートなエージェントメモリ、コードインデックス、セッション継続、プロジェクトWiki、チャンク化RAGではありません。これは、コードやGitが確実に再構築できないプロジェクト知識のための、小さくGitに優しいアドレス空間です。

1つのMCP、多くのエージェント：実戦で検証されたワークフロー

Turritopsis は、1人の人間がチャット、コーディング、ローカル、VPSの各ワークスペースで4つの異なるエージェントを使って実際の長期システムを運用したことから生まれました。彼らはプライベートなメモリや継続的なセッションを共有していませんでした。彼らは1つのMCPを通じて1つのプロジェクトマップを共有していました。

チャットウィンドウは思考のためにありました。 ChatGPT と Claude は、長文脈のブレインストーミング、製品決定、難しい設計の会話を、本来あるべき会話面に保つことができました。彼らのコンテキストとトークン予算は、リポジトリを繰り返し再構築する代わりに、推論に費やされました。

コーディングウィンドウは実行のためにありました。 クリーンなコーディングエージェントは、list_stages、search_stages、get_stage を呼び出し、数秒で引き継ぐことができました。独自のエージェントメモリシステム、古い会話の再生、新しく書かれたハンドオフ文書は必要ありませんでした。クリーンなウィンドウは、エンジニアリングの進捗を失うことなくクリーンなままでした。

より安価なモデルが日常的なメンテナンスを担当しました。 最近の差分や古い検証日を検査し、証拠に基づく知識を更新し、不確かな事実は未解決のままにすることができました。高価なモデルは、それに値する決定のために予約されていました。

人間は方向性を編集し、簿記はしませんでした。 Web UI は、プロジェクトマップ、Stage エディタ、ライブ Markdown プレビュー、リビジョン競合、提案、履歴を提供しました。人間は優先順位、境界、プロジェクトの意味を修正し、エージェントは追跡可能な証拠から実装の詳細を維持しました。

実際の結果は、すべてのエージェントにメモリシステムになることを強制しない継続性でした。エージェントが消え、セッションが終了しても、新しいコーディングウィンドウは現在の真実を見つけて作業を続けることができました。

Related MCP server: handoff-mcp

インストールと起動

python -m pip install -e .
turritopsis init --yes --name "My Project" --description "What this project does"
turritopsis init --yes --name "My Project" --modules "API, Worker, Web"
turritopsis add anatomy anatomy.components "Current components"
turritopsis serve --stdio

HTTP はストリーミング可能な MCP を使用し、デフォルトではループバックのみをリッスンします：

turritopsis serve                 # 127.0.0.1:3013
turritopsis serve --port 4013
turritopsis serve --data /project/.turritopsis/stages.json

人間用のプロジェクトマップは http://127.0.0.1:3013/ を開きます。同じプロセスが以下を提供します：

• / — プロジェクトマップ、検索、Stage リーダー/エディタ、ハンドオフ、Authority、提案、履歴；

• /mcp — 4つの MCP ツール；

• /api/... — 同じ Turritopsis、Store、検索、更新実装に支えられたローカル UI API。

turritopsis ui は、人間向けの表面だけが必要な場合の明示的なエイリアスです。インストール後は、Node ランタイム、フロントエンドビルド、LLM、API キーは必要ありません。

リモート公開は明示的（--host 0.0.0.0）であり、認証レイヤーの背後に配置する必要があります。

エージェントオンボーディングスキル

リポジトリには、skills/turritopsis-onboarding/ に Codex 互換のスキルが含まれています。そのディレクトリを Codex スキルフォルダにコピーし、エージェントがプロジェクトを初期化、参加、または再開するときに $turritopsis-onboarding を呼び出します。このスキルは、インストールされたエージェントに、あるプロジェクトの Current 名をコピーするのではなく、普遍的な Stage の責任とプロジェクト固有のスイートを選択する方法を教えます。

知識モデル

Current は、プロジェクトの質問の永続的なファミリーをルーティングします。Current 名はプロジェクト固有です。anatomy、flow、bounds、manual、genesis は、一部の長期実行エージェントシステムには有用ですが、すべての SDK、データベース、モバイルクライアント、ML パイプライン、デバイスに対する普遍的なデフォルトではありません。

Stage は、完全で名前付きの知識領域であり、任意のテキストチャンクではありません。Stage の Markdown には、英語または中国語のメタデータを含めることができます：

# Current work and handoff

Type: handoff
Purpose: Tell a new contributor where work currently stands.
Search hints: handoff blocker next step release current work
Summary: Release is frozen pending hardware regression.
Verified: 2026-08-24 by agent
Status: current
Authority: current work, next action
Freshness: volatile

## Update triggers

- The blocker or next action changes.

現在の真実、歴史的な説明、決定論的に生成された事実を別々の Stage に保持してください。Status: historical は、現在の権威として静かに提示されることはありません。生成された Stage は、手動編集が上書きされることを明記する必要があります。

4つの MCP ツール

• list_stages(current?) は、カレントまたはコンパクトな Stage メタデータをマッピングし、本文は決して含みません。

• search_stages(...) は、説明可能な重み付きルーティングまたは正確な行/コンテキストマッチを提供します。

• get_stage(stage_id) は、1つの完全な Stage とその本文ハッシュリビジョンを返します。

• update_stage(...) は、置換/追加、オプションの expected_revision、アクターログ、ローリングバックアップ、競合応答をサポートします。

検索重みは、実証済みのライブルーティング順序を保持します：Stage id、検索ヒント、タイトル、権威、要約、目的、ステータス/検証、Current、次に見出し/本文。semantic は説明可能な構造化フィールドルーターであり、埋め込みを主張しません。

すべての読み取りは stages.json を再読み込みします。書き込みはファイルロックを取得し、対象の Stage リビジョンのみを比較し、fsync を使用して一時ファイルに書き込み、正規ファイルを原子的に置き換え、changelog.jsonl に追記し、ローリングバックアップを保持します。

構造とメンテナンス

.turritopsis/
├── stages.json
├── config.json
├── scan-evidence.json
├── scan-anomalies.json
├── scan-run.json
├── changelog.jsonl
├── maintenance.jsonl
├── backups/
└── proposals/

通常の turritopsis init は、主要モジュールを尋ね、初期の Current/Stage アドレスを作成します。--modules は、同じ回答を非対話的に提供します。

コールドスタートは、意図的にローカルの決定論的スキャンとインストールされたエージェントの分類に分割されています：

turritopsis scan
# The current Codex/Claude Agent reads scan-run.json and scan-evidence.json,
# chooses Stage types and a project suite, then writes skeleton.json.
turritopsis apply-skeleton skeleton.json

turritopsis init --scan は、最初のコマンドの互換エイリアスです。制限されたプロジェクトツリー、README ファイル、マニフェスト、CI/設定ドキュメント、その他の機密性のないテキスト資料を読み取り、scan-evidence.json、scan-anomalies.json、scan-run.json を書き込みます。モデル、ネットワーク、プロバイダー、API キーは使用しません。--refresh が明示的でない限り、scan を再実行すると保存された証拠から再開されるため、中断されたエージェントはスキャンコストを再度支払う必要がありません。

インストールされたエージェント（2番目の外部 LLM ではなく）がその証拠を分類します。apply-skeleton は、stages.json を原子的に作成する前に、スキーマ、出所、Current と Stage の ID、証拠パス、Stage のタイプ/鮮度、空の責任、重複する Authority、ガベージドロワー、断片化を検証します。既存の知識ベースを上書きすることはありません。以降の書き込みは、リビジョン保護された update_stage を使用する必要があります。正規の知識は依然として明示的なプレースホルダーとして始まり、検証された証拠から埋められる必要があります。

オプションの LLM バックアップメンテナンスは .turritopsis/config.json を使用します。スキャンとスケルトン適用はそれを読み取ることはありません：

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "api_key_env": "OPENAI_API_KEY"
  }
}

サポートされているプロバイダーは openai、anthropic、openai-compatible です。互換プロバイダーには base_url が必要です。設定は TURRITOPSIS_LLM_PROVIDER、TURRITOPSIS_LLM_MODEL、TURRITOPSIS_LLM_API_KEY_ENV、TURRITOPSIS_LLM_BASE_URL、TURRITOPSIS_LLM_TIMEOUT、TURRITOPSIS_LLM_MAX_TOKENS で上書きできます。API キー値は設定された環境変数からのみ読み取られ、プロジェクトファイルに書き込まれることはありません。

turritopsis maintain は、最近の Git 変更、欠落している参照パス、検証の古さをチェックします。影響を受ける各キュレーション Stage について、現在の本文と制限されたプロジェクト証拠を設定された LLM に送信し、返された JSON と引用された証拠 ID を検証し、Verified を更新してから、通常の Stage リビジョン、ロック、バックアップ、原子的置換、および変更ログパスを通じて書き込みます。証拠が不十分な場合、モデルは no_change を返す必要があります。

turritopsis maintain
turritopsis maintain --model CHEAP_MODEL
turritopsis maintain --proposal-only
turritopsis maintain --schedule "0 3 * * *" --model CHEAP_MODEL
turritopsis maintain --show-schedule
turritopsis maintain --unschedule
turritopsis survey
turritopsis anomalies
turritopsis brief
turritopsis export --format md
turritopsis export --format json --output project-knowledge.json

--proposal-only は、必要に応じてレビュー優先のドリフトレポートを保持します。--apply は、明示的にレビューされた提案を引き続き適用します。これらはオプションのワークフローであり、通常の証拠に基づくメンテナンスの制限ではありません。

--schedule は、現在の POSIX ユーザーの crontab に、パススコープのエントリを1つインストールまたは置き換えます。上記の例は、cron ホストのローカルタイムゾーンで毎日 03:00 に実行され、出力を .turritopsis/maintenance-cron.log に書き込み、繰り返しても冪等です。crontab に API キーを書き込むことはありません。config.json で指定された api_key_env は、cron 環境で利用可能である必要があります。--show-schedule と --unschedule は、このプロジェクトの Turritopsis のマークされたブロックのみを検査または削除します。crontab がないホストでは、CI またはネイティブスケジューラから同じ turritopsis maintain --model CHEAP_MODEL コマンドを呼び出します。

唯一の自動書き込み例外は、決定論的ジェネレータ設定を持つ明示的に生成された Stage です：

{
  "id": "anatomy.revision",
  "title": "Current Git revision",
  "status": "generated",
  "generator": {"type": "git_revision"},
  "body": ""
}

組み込みの決定論的タイプは git_revision、file_hash、path_exists です。それらの出力は自動生成と明確にマークされ、LLM を使用しません。

コアの list/search/get/update、Web UI、MCP サービング、スキャン、スケルトン適用には、LLM も API キーも必要ありません。オプションの自動キュレーションメンテナンスのみが必要です。

ライセンス

Turritopsis は、標準の MIT ライセンス の下でリリースされたオープンソースソフトウェアです。商用利用、変更、配布、サブライセンス、私的利用は、ライセンス通知の要件に従って許可されています。

開発

python -m pip install -e ".[test]"
pytest