Ephemeral-AI-Lab/layerfs

LayerFS – AI エージェントワークスペース向けの SQLite バックエンド、コンテンツアドレスの「タイムマシン」

概要

• AI エージェント（またはファイルシステムに触れる任意のツール）が一時的なワークスペース内で作業できるようにするライブラリ、CLI、および FUSE ベースのファイルシステム。
• エージェントがステップを完了すると、ワークスペースをコミットでき、ファイルシステムスナップショット全体が不変のコミットに変わります。
• コミットは LayerStack に保存されます。これは、3 つの古典的な技術を使用して互いに積み重ねられたレイヤーの履歴です。
  1. コンテンツアドレスストレージ (CAS) – オブジェクトはバイトのハッシュで名前が付けられるため、同一データは一度だけ保存されます。
  2. コンテンツ定義チャンキング (CDC) – ファイルは安定したチャンクに分割されます。小さな編集では新しいチャンクのみが作成され、ファイル全体の新しいコピーは作成されません。
  3. コピーオンライト (COW) – 新しいレイヤーが公開されると、変更されたディレクトリとファイルのみが書き換えられます。
• 履歴全体は単一の SQLite データベース（Store）に保存されます。データベースはエージェントにとって読み取り専用です。コミットが公開されるときにのみ LayerFS ランタイムが書き込みます。

AI にとっての重要性

• 最新の自律エージェント（LLM 駆動のプランナー、人間のフィードバックからの強化学習ループ、マルチエージェントシミュレーション）は、コード、データ、または設定の多くの仮説バリエーションを試す必要があります。
• 各試行のために大規模なワークスペースの完全なコピーを再作成することは無駄です。LayerFS により、エージェントは以前のレイヤーを即座に（ゼロコピーで）フォークし、多くの並列ロールアウトを実行してから、最良のブランチをプロモートできます。
• 履歴は不変でコンテンツアドレスであるため、システムは数千の試行にわたって大量のデータを重複排除でき、ストレージと I/O を大幅に削減できます。

主要コンポーネント（v0.1.6 開発者プレビュー時点）

コンポーネント	役割
ストレージエンジン	CAS、CDC、COW、オブジェクト検証、SQLite Store を管理します。
SDK	Client、LayerStack、Branch、Workspace などの型と、それらを作成/コミット/クエリする関数を公開する Rust ライブラリ。
CLI (layerfs-cli)	Store の作成、LayerStack の初期化、ワークスペースの生成、コミット、履歴の検査のためのコマンドラインインターフェース。
ファイルシステムプロジェクション	エージェントに通常のディレクトリとして表示されるマウントポイント（ホストマテリアライゼーションまたは FUSE コンテナ経由）を提供します。
コンテナランタイム	FUSE を使用して軽量 Linux コンテナを起動し、可変ワークスペースをコンテナ内に保持し、永続 Store をホスト上に保持します。

典型的なワークフロー

1. Store を作成 – layerfs db create store.sqlite。
2. LayerStack を初期化 – layerfs layerstack init --name demo --empty はジェネシスレイヤーを作成します。
3. ワークスペースを開始 – layerfs workspace exec <branch> は、ファイルシステムのプライベートビューを持つプロセス（またはコンテナ）を起動します。
4. 作業を実行 – エージェントはツールを実行し、ファイルを書き込むなどします。
5. コミット – layerfs commit <workspace> は可変状態を不変のコミットに変換し、現在のブランチにアタッチします。
6. ブランチ / フォーク – データをコピーせずに代替案を探索するために、以前の任意のコミットから新しいブランチを作成します。

パフォーマンスのハイライト (v0.1.6)

• 32 MiB ファイルに 10 バイト追加しても、論理ストアサイズは 約 0.026 MiB しか増加しませんでした（CDC のおかげ）。
• ワークスペース全体での 6 回の決定的な編集により、論理ストアは 約 0.225 MiB 増加しました。
• すべての測定は実際の FUSE ベンチマークスイートからのものです。基盤となる SQLite ページはより多く増加する可能性がありますが、論理コンテンツは小さなままです。

制限事項（重要）

• 開発者プレビューのみ – クラッシュや停電に対する耐久性の保証はありません。重要なデータのバックアップを保持してください。
• クライアントごとに 1 つの Store。クロスホスト同期はまだありません。
• コミットは自動的に fsync されません。サンドボックスの可変状態は、コミットが公開されるまでメモリ内にのみ存在します。
• 不変オブジェクトを構築する単一の構築ワーカーのみが存在するため、大規模なバッチインポートは以前のバージョンより遅くなります。
• 明示的な圧縮はありません。古いストアは読み取り可能ですが、システムはスペースを自動的に回収しません。
• CLI JSON 出力は暫定フォーマットであり、安定した API ではありません。

はじめに

# v0.1.6 タグをクローン（プレビューコードは `crates/` の下にあります）
git clone https://github.com/Ephemeral-AI-Lab/layerfs.git
cd layerfs && git checkout v0.1.6

# CLI をビルド（Rust 1.85+、macOS/Linux が必要）
cargo build --release -p layerfs-cli
export LAYERFS_BIN=$PWD/target/release/layerfs
export LAYERFS_CONTEXT=$PWD/.layerfs/context
mkdir -p $PWD/.layerfs

# SQLite ストアとデモ LayerStack を作成
$LAYERFS_BIN db create $PWD/.layerfs/store.sqlite
$LAYERFS_BIN context use --store $PWD/.layerfs/store.sqlite
$LAYERFS_BIN layerstack init --name demo --empty
$LAYERFS_BIN query layerstacks

ブランチ作成、ワークスペース実行、オプションの FUSE コンテナ使用については、バージョン固有のクイックスタートガイドを続けて参照してください。

ロードマップスナップショット

• 0.2.0（計画中） – ポータブルプロジェクションレイヤー（reflink/clonefile、将来の OverlayFS サポート）。
• 後で – クロスホストストアのエクスポート/インポート、同期、よりリッチなランタイム統合。

コミュニティとサポート

• Discord: https://discord.gg/DrgJ4DX9E
• WeChat グループ（リポジトリに QR コード）– 招待は定期的に期限切れになります。
• X でプロジェクトリーダーをフォロー: @yifanxu_ephai

ライセンス – MIT。

---

LayerFS は、安価でバージョン管理されたファイルシステム状態を必要とする自律 AI エージェントを構築する開発者向けの研究グレードのツールです。まだ本番グレードのストレージシステムではありませんが、「一時的なワークスペース + 永続的な共有履歴」パターンを実験するための具体的なプラットフォームを提供します。