MirageでAIエージェントに仮想ファイルシステムを渡す
AI エージェント用の統合仮想ファイルシステム。 **埋め込み可能:** Python および TypeScript SDK は、FastAPI、Express、ブラウザ アプリ、または非同期ランタイム内でインプロセスで実行されます。別のプロセスは必要ありません。
ひと目でわかる
- これは何？
- strukto-ai/mirageのPython・TypeScript SDK、CLI、検索、SlackからRedisへの処理をREADMEの範囲で検証します。
- 誰に向いている？
- Mirageは、AIエージェントや既存のFastAPI、Express、ブラウザ処理へ仮想ファイルの入口を組み込みたい開発者に向きます。実行権限、永続化、同時実行、機密データの境界をREADMEだけで決めたい場合には向きません。
- 商用利用できる？
- できます。Apache-2.0 は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。直近 1 日以内に新しいコミットがあります。
- 何の言語で書かれている？
- 主に TypeScript です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
埋め込み型という設計
READMEはMirageをAIエージェント向けの統合仮想ファイルシステムとし、PythonとTypeScriptのSDKがFastAPI、Express、ブラウザアプリ、非同期ランタイムの内部で動くと説明します。別プロセスを必須にしない点が設計の入口です。
この説明から、外部サービスとして完成したファイルサーバーだとは判断できません。アプリ内でどのAPIがファイル、ディレクトリ、検索を扱うかを最小コードで確認します。ブラウザ版とNode版の権限や永続化が一致する保証はREADMEにないため、実行環境ごとにテストを分けます。
grepで全ソースを走査する例
冒頭の例は、Slackに置いたスクリプトが全ソースをgrepし、レポートをRedisへ保存する流れです。Mirageが単に文字列を表示するだけでなく、エージェント処理が扱う仮想的な場所をまとめることを示しています。
検証では検索対象、Slackから渡る入力、Redisのキー、レポートの生成者を固定します。検索結果に秘密情報が混ざらないか、同じ処理を再実行したとき重複や上書きがどうなるかを記録します。READMEに暗号化や保持期間の説明はないため、運用の前提を補いません。
SDKのパッケージを選ぶ
Node向けには`@struktoai/mirage-node`、ブラウザやedge向けには`@struktoai/mirage-browser`、エージェント連携には`@struktoai/mirage-agents`が示されています。Python側の入口もREADMEのInstallationとQuickstartに分かれています。
サーバー、ブラウザ、エージェントの依存を一つのパッケージとして扱わず、利用経路ごとにlockfileを作ります。browserで扱うデータとFastAPI内のデータを同じ保存範囲にしないことが初回設計の要点です。
CLIの取得経路
CLIは`curl -fsSL https://strukto.ai/mirage/install.sh | sh`、または`npm install -g @struktoai/mirage-cli`で導入する入口が示されています。READMEはCLIとSDKを別の利用形態として案内しています。
インストールスクリプトは内容を確認し、Node版ではグローバルprefixと実行ユーザーを記録します。CLIで作った仮想ファイルがSDKから見えるか、逆方向も試します。既定のポート、認証、データディレクトリは資料から確定できません。
エージェントアダプターの境界
READMEはOpenAI、Vercel AI、LangChain、Mastraのアダプターを挙げています。これは接続先の候補を示すもので、各モデルの呼び出し、課金、データ保持、ツール権限を保証する記述ではありません。
アダプターごとに同じ読み取り操作を一つだけ許可し、書き込みは明示的な確認を挟みます。失敗した呼び出し、生成されたファイル、外部へ出た引数をログに残し、モデルの回答をファイルシステムの事実と混同しないようにします。
Apache-2.0と初期版の扱い
素材に記録されたタグはv0.0.5、ライセンスはApache-2.0です。初期版ではAPI変更、保存形式、互換性、長期保守の条件がREADMEだけでは分かりません。
導入時はpackageの版を固定し、同じ入力で検索、作成、削除、再起動後の読み出しを再実行できるテストにします。Apache-2.0の条件は配布形態と照合し、機密データを置く前に実装と公式docsの差分を確認します。
FastAPI内のPython経路、Nodeサーバーのmirage-node、browser経路を別々の小さなプロジェクトで試します。ファイルを作成し、grepで検索し、削除し、同じIDで再実行したときの結果を保存します。Slackのスクリプト例では入力メッセージ、検索対象、生成レポート、Redisのキーを対応付け、再実行による重複や上書きを確認します。mirage-agentsのアダプターは読み取りだけを許可した設定から始め、モデルへ渡った引数と仮想ファイルへ書かれた内容を比較します。CLIのinstall.shとnpmの導入で実行ファイルの版、prefix、権限を確認します。ブラウザへ秘密情報が流れないこと、再起動後の永続性、エラー時に中途半端なファイルが残る条件をv0.0.5として記録します。
MirageでAIエージェントに仮想ファイルシステムを渡すを採用候補として残す場合は、試験日、使用した版、実行環境、入力データの種類、実行したコマンド、設定ファイルのハッシュ、標準出力、標準エラー、生成されたファイルを一つの記録にまとめます。画面が表示された、処理が終了した、接続できたという単一の事実だけでは合格にしません。再起動、権限不足、空の入力、重複した入力、ネットワーク切断、設定変更、更新後の再実行を同じ順序で試し、結果が変わった場合は原因を版、設定、外部サービス、保存先のどこに求めるかを分けて調べます。原本や機密情報は検証用の値に置き換え、ログに残った識別子と保存場所を確認します。導入できなかった条件も失敗として保存します。そうすれば、READMEの機能説明、実際に観察した結果、まだ文書化されていない判断を区別したまま、利用範囲を狭く始めて段階的に広げられます。
編集部の結論
Mirageは、AIエージェントや既存のFastAPI、Express、ブラウザ処理へ仮想ファイルの入口を組み込みたい開発者に向きます。実行権限、永続化、同時実行、機密データの境界をREADMEだけで決めたい場合には向きません。最初にSDKの最小例でファイル作成と検索を通し、SlackのスクリプトからRedisへ保存する経路、importsと権限、エラー時の残存データを確認してください。
コミュニティノート