Mitos

Mitos

🔧 アーリーリリース — 開発を積極的に進めています

AI アシスタントと数か月にわたってソフトウェアを開発していると、意思決定の背後にある 理由 が失われていきます。アシスタントは、あるアプローチを選んだ理由を忘れ、すでに却下した選択肢を再び提案し、設計メモは実際に決定した内容とずれていきます。Mitos は、そうした意思決定のためのメモリーレイヤーです。各決定、却下した代替案、そして後の決定によって以前の決定がどう置き換えられたかを記録し、その履歴を簡潔で信頼できる形で AI アシスタントに提供します。

その結果、AI コラボレーターは実際に下した判断と一貫性を保てます。過去の決定と矛盾したり、決着済みの問題を蒸し返したりすることがなくなり、意思決定の記録が気づかないうちに古くなることもありません。

内部では、人間向けの Markdown（decisions.md と decisions/archive/ 配下の四半期ごとのアーカイブが信頼できる唯一の情報源で、いつでも読み取って grep できます）、エージェント向けの型付きグラフ（SQLite と意味検索用のローカル Qdrant）、そして意思決定の前に先例を確認し、決定時に記録する MCP サーバーを使用しています。

PyPI と MCP Registry で利用できます。

---

最速のインストール方法：エージェントに任せる

AI コーディングエージェント（Claude Code、Cursor、Gemini CLI、…）を使っている場合は、セットアップを任せるのが最も簡単です。Mitos を導入したいプロジェクトで、エージェントに次の内容を渡してください。

Read https://github.com/dovahkiin-v/mitos/blob/main/SETUP.md and set up mitos
for this project. When done, run `mitos status .` from the project directory
and report the result.

エージェントが行う作業は次のとおりです。人間が行う場合と同じ手順で、すべて SETUP.md に記載されています。事前に内容を確認できます。

• pipx を使って mitos CLI をインストールします（PyPI またはこのリポジトリから）。
• ローカルの Qdrant コンテナー（ポート 7333 の qdrant/qdrant）を起動します。すでに実行している Qdrant とは分離されています。
• MCP サーバーがまだ登録されていない場合、マシン全体に対して一度だけ登録します。
• プロジェクトのワークスペースを初期化します。これにより、プロジェクトが名前で登録されます。
• API キーは自分で設定するよう求められます（mitos set-key）。Gemini キーは必須で、競合監査レイヤー用の Anthropic キーも強く推奨されます。セットアップガイドでは、エージェントがキーの値を扱わないよう指示しています。

作業中にエージェントがどれだけ質問するかは、このプロンプトではなく、使用しているエージェントの設定によって決まります。

手動セットアップ

手順を手動で行う場合の詳細は、SETUP.md をご覧ください。

1. インストール（マシンごとに一度）：pipx install mitos-adr
2. Qdrant を起動（マシンごとに一度。すべてのプロジェクトで共有）：このリポジトリから docker compose up -d を実行します。mitos は :7333 で独自のインスタンスを実行するため、他の作業で使用している Qdrant には一切触れません。
3. MCP サーバーを登録（マシンごとに一度。エージェント向けに推奨）：claude mcp add --scope user mitos -- mitos serve を実行します。登録は 1 回で、すべてのプロジェクトに対応します。費用、他のハーネスでの設定、残っているプロジェクトごとの .mcp.json エントリを削除する必要がある理由については、SETUP.md をご覧ください。
4. プロジェクトごと：プロジェクトのルートから mitos init を実行し、続けて mitos set-key --global <your-Gemini-key> を実行します（1 つのキーですべてに対応します。https://aistudio.google.com/app/apikey で取得してください）。現在、テスト済みの埋め込みプロバイダーは Gemini です。複数プロバイダーに対応する抽象化はロードマップに含まれています。
5. 確認：mitos status . → READY ✓。

mitos status . は、作業中ずっと頼りになる道しるべです。そのプロジェクトで完了したこと、不足していること、次に行うことを正確に示します。プロジェクト名を指定せずに mitos status を実行すると、別の疑問に答えます。このマシンに何があるかを示し、登録済みのすべてのプロジェクトを一覧表示して、Qdrant を確認します。

すべてのコマンドでプロジェクトを指定します。 デフォルトの対象はありません。mitos init でプロジェクトを名前付きで登録し、その後は各動詞に -p <name>、-p <absolute path>、またはプロジェクトのルートから -p . を指定します（エージェントには同じ値を project 引数として渡します）。mitos projects で登録済みのプロジェクトを一覧表示し、mitos unregister <name> で登録を解除します（ワークスペースはそのまま残ります）。これにより、インストール 1 回、MCP サーバー 1 つでマシン上のすべてのプロジェクトに対応でき、誤ったコーパスに処理が送られることもありません。

実行の仕組み

Mitos はプロジェクトごとに動作します。各プロジェクトには、それぞれ独自の意思決定グラフと Qdrant コレクションがあります。日々の作業では、3 つの動詞で一連の流れを進めます（エージェント向けの MCP ツールと、それに対応する CLI コマンドがあります）。

動詞	使用するタイミング
surface_decisions（mitos surface）	決定する前：前例はありますか？各検索結果には、すでに却下された選択肢とその理由が含まれます。
record_decision（mitos record）	決定が確定した時点：決定内容、却下した選択肢、以前の決定との関係（置き換え、修正など）を記録します。
query_decisions（mitos query）	意味で検索する場合（MCP ツールでは正確なハンドルでも検索できます）、または却下された選択肢だけを検索する場合に使います。

知っておくと便利な特徴をいくつか紹介します。

• 信頼できる唯一の情報源は Markdown です。 すべての決定は decisions.md に記録され、ローテーションによって確定済みのエントリが decisions/archive/ に移動します。どちらも人が読めて grep で検索でき、グラフと検索インデックスはこれらから生成されるため、いつでも再構築できます（mitos rebuild）。
• 決定の公理は編集せず、置き換えます。 公理とその仕組みは、後続の決定によって置き換え、修正、または補足される場合にのみ変更されます。また、状態（active / superseded / amended）は、それらの型付き関係から算出されるため、常に「なぜそうなったか」の履歴が残ります。コメント（却下した選択肢、コンテキスト、範囲）は mitos amend-commentary でその場で修正できます。
• 安全側に動作します。 検索インデックスまたは埋め込み API が停止していても、記録は引き続き機能し、検索は Markdown に対する誠実なテキスト一致に切り替わります。処理がブロックされることも、データが失われることもなく、機能が縮退している場合はその旨が出力に示されます。
• 自己監査します。 コーパスの一括チェック（mitos check -p .）で、互いに矛盾していることが見過ごされている決定を検出します。コミットゲート（mitos hook-install -p .）は git commit 時に実行され、決定の記録後に作成されたコミットを、チェックが試行されるまで保留します。また、--staged を指定すると、decisions.md でまだ保留中の手動作成エントリをチェックします。コミットゲート、ステージ済みゲート、CI と cron のレシピについては、SETUP.md をご覧ください。

mitos --help でほかの機能を確認できます。ヘルプテキストは API リファレンスも兼ねています。

存在理由

LLM による集中的な設計レビューを通じたソフトウェア開発では、人が追跡できる速度を上回る速さでアーキテクチャ上の決定が生み出されます。この方法で1か月作業した結果、1つの Markdown ファイルに約900件の決定記録が蓄積され、もはや手作業では検索も閲覧も管理もできなくなりました。既存の ADR ツールは、ときどき決定を記録する人間のチーム向けに作られています。一方 mitos は、AI アシスタントが継続的に決定を生成し、利用する個人開発者向けに作られています。

このような開発スタイルであれば、プロジェクトの規模はあまり関係ありません。決定の量が多いほど、mitos は早く「あれば便利」から「なくてはならない」ものになります。

開発

pip install -e '.[test]'
MITOS_NO_LIVE_TESTS=1 pytest -m "not packaging" -n auto   # offline suite, parallel (~50s)
pytest -m "not packaging"                                 # adds the live tier — serial only
pytest -m packaging                                       # real-install check: fresh venv + pip install

-n auto はオフラインのテストスイートでは安全ですが、ライブのテスト層では使用しないでください。テスト収集のスイープはセッションスコープで行われるため、並列ワーカーが互いの Qdrant コレクションを削除し、影響を受けたテストは失敗ではなくスキップになります。

*_live.py スイートとゴールデン Layer B は、実際に Gemini と Anthropic の API を呼び出し、自身のキーを使用します。また、Qdrant が :7333 で稼働している必要があります。解決可能なキーがない場合はスキップされるため、新規クローンではデフォルトで高速パスが実行されます。

キーは、環境変数、リポジトリルートの .env、または ~/.config/mitos/.env から取得されます。そのため、すでに mitos を使用している場合、テストの実行時に個人のキーが読み込まれ、それを使って課金される可能性があります。明示的にオプトアウトするには、次のようにします。

MITOS_NO_LIVE_TESTS=1 PYTHONPATH=. pytest -m "not packaging"

標準となる決定形式は mitos/format-spec.md にあります。ライセンス：Apache 2.0。