# アーキテクチャ

> Agent NAS は 4 つの層と、任意の同期層でできています。Interface は機能を既存のインターフェースに投影し、Trust は認可の唯一の地点で、Memory はノートを検索できる知識に変え、Store は履歴を持つツリーを保管します。Memory 層はまるごと削除して再構築でき、Store は成熟したストレージをそのまま使います。

## 4 つの層と、任意の同期

- **Interface（インターフェース）**: エージェント、人間、ツールがすでに使っているインターフェースに、機能を投影します。ゲートウェイは状態を持たず、誰が何をしてよいかを決めることはありません。 (マウント（FUSE、NFS、SMB）, Git, S3 互換, WebDAV, MCP, HTTP API, CLI, A2A（任意）)
- **Trust（信頼）**: 認可の唯一の地点。決定的なポリシーエンジンで、判断にモデルは関わりません。先に記録し、それから実行します。 (プリンシパルと実行, Capability Lease, ポリシーエンジン, Human Gate, Trust Labels, Credential Broker, Flight Recorder)
- **Memory（記憶）**: ノートを、検索でき、予算つきで読める知識に変えます。すべて、下の層から再構築できます。 (ノートの規約, 索引（全文、ベクトル、グラフ）, Budgeted Reads, 保守ジョブ, 系譜, Cascade Forget)
- **Store（ストア）**: 履歴を持つツリー。成熟したファイルシステムのスナップショット、Git、またはバージョン管理されたオブジェクトストレージの上に作ります。記憶やラベルの意味は理解しません。 (Tree, Commit, Agent Branch, ファイルシステムのスナップショット, Git, オブジェクトストレージ)
- **Sync（同期、任意）**: ノード間のレプリケーションと共有。あえて最後にしています。まず単一のノードを正しく作ります。 (Git リモート, スナップショット転送, リースリンク, ハンドオフバンドル)

- **Memory 層は再構築できます。** 索引をすべて削除して作り直しても、Store のノートは完全に読めます。
- **ゲートウェイは状態を持ちません。** 永続的な状態はすべて Store と Trust の記録の中にあり、ゲートウェイは自由に再起動でき、水平にスケールできます。
- **Trust は認可の唯一の地点です。** NAS 自身のバックグラウンドジョブ（索引づけ、保守）も含みます。それらも `svc:*` プリンシパルとしてリースを持って動きます。
- **Store は、記憶やラベルの意味を理解しません。** メタデータつきのツリーを保管するだけです。
- **先に記録し、それから実行します。** 影響の大きい操作は、まず意図の記録を書かなければなりません。

## 細い腰：6 つの名詞

設計全体が 6 つの名詞だけに依存しています。ラベル、ゲート、記憶、読み取りマニフェストは、その上に作られた規約です。

| 名詞 | 意味 | 重要な不変条件 |
| --- | --- | --- |
| Tree | 履歴を持つディレクトリツリー。 | どのコミットも再現できる。内容ハッシュ、または同等の変更検出がある。 |
| Commit | 1 回の不変の変更。 | 出どころのメタデータを持つ：`principal`、`on_behalf_of`、`run`、`lease`。 |
| Principal | 認証でき、責任を問える主体。 | 種別は `human`、`agent`、`service`、`node`。`agent` は 1 回の実行ではなく、ロールに属する。 |
| Run | 開始、終了、目的、責任者を持つ 1 回の実行。 | ルートリースを 1 つ持ち、ブランチを 1 つ所有する。 |
| Lease | 実行の認可。 | 期限がある。狭めることしかできない。失効できる。予算を持つ。 |
| Record | 追記のみの記録。 | ハッシュでつながれている。先に記録し、それから実行する。 |

## Store 層：契約と、選べるエンジン

Store の契約は、エンジンが提供するか、ゲートウェイがエミュレートします。実装は複数のエンジンを組み合わせてもかまいません。たとえばテキストは Git、大きなファイルはスナップショットです。契約は、エンジン、ハッシュ関数、ディスク上の形式を定めません。

1. アトミックなコミット。
2. 安価なフォーク。理想的には O(1) に近く、最悪でもコピーに退化する程度。その場合はクォータと TTL が必須。
3. 不変のスナップショット。
4. 変更検出：内容ハッシュか、同等の手段。
5. 2 つのコミットの間の差分。
6. 標準的な形式での完全なエクスポート：ディレクトリ、Git の履歴、プレーンテキストの `.nas/` メタデータ。

| エンジン | 向いているもの | フォークのコスト | 注意 |
| --- | --- | --- | --- |
| Git（worktree を含む） | テキスト、記憶、スキル、小さなコードベース | 低い | 大きなファイルには LFS か外部ストレージが必要。バイナリのマージは苦手。 |
| ファイルシステムのスナップショットとクローン（ZFS、btrfs、APFS） | 大きなディレクトリ、混在するファイル | ほぼ O(1) | ファイルシステム次第。マシン間のコピーには send/receive が必要。 |
| バージョン管理されたオブジェクトストレージ（Tigris のフォーク、lakeFS、S3 とマニフェスト） | データセット、大きなファイル | ほぼ O(1) | ゲートウェイがファイルのビューを提供する必要がある。 |
| 普通のディレクトリとコピー | Lite の出発点 | O(n) | 小さなデータ向けのみ。クォータと TTL が必須。 |

> **復旧の経路は、被害の範囲の外に置く.** スナップショットとバックアップは所有者のプリンシパルが持ち、どのリースにも「スナップショットの削除」や「バックアップの削除」を含めることはできません。これは 2026 年 4 月の事故から得られる最も直接的な教訓です。復旧の経路は、それが守るものの被害の範囲の外になければなりません。

- 保存時の暗号化は下の層が提供します。`sensitive` の保持クラスは独自の鍵ドメインを使うので、鍵を破棄すれば粉砕できます。
- 重複排除と粉砕は両立しません。`sensitive` クラスは、鍵ドメインをまたいで重複排除しません。

## 1 回の実行の旅

1. **申請する。** オーケストレーター（または所有者）が、実行のためのリースを申請します。パス、操作、期限、目的。**ポリシーの範囲** の中なら自動で発行され、外なら Human Gate に回ります。
2. **開始する。** NAS が `run` とブランチ `<role>/<run_id>` を作り、リースを実行に渡します。サンドボックスはそのブランチをマウントします（または `git clone` します）。
3. **作業する。** エージェントは、普通のファイルツールで読み書きします。読み取りは **読み取りマニフェスト** にたまり、セッション汚染もそれに合わせて更新されます。範囲外のアクセスは拒否され、記録されます。
4. **コミットする。** 変更は自動（デバウンス）または明示的にコミットされ、すべてのコミットが出どころのメタデータを持ちます。
5. **提案する。** `propose` が **Agent PR** を作ります。差分、意図、読み取りマニフェストの要約、チェック結果、ラベルの要約です。
6. **裁定する。** ポリシーエンジンが判断します。チェックに通り、リスクが低ければ自動でマージ。保護されたデータ、外向きの操作、Rule of Two 違反が関わるなら Human Gate へ。明らかに禁じられていれば拒否します。
7. **マージして記録する。** マージは、出どころつきのコミットを作り、Record を書きます。
8. **締めくくる。** リースは期限切れになり、ブランチは TTL のあとに回収され、読み取りマニフェストと Record は保持ポリシーに従って残ります。

**読み取りの経路：** リクエスト、リースの確認、ラベルの確認（現在のセッション汚染がこの読み取りを許すか）、予算の計上、Store からの読み取り、読み取りマニフェストへの記録、内容と証拠ポインタの返却。

> **先に記録し、それから実行する.** 影響の大きい操作（マージ、削除、共有、外向きの送出、リースの変更）は、まず意図の記録を書かなければなりません。書けなければ、その操作は失敗します（fail closed）。読み取りは読み取りマニフェストに入り、まとめて書き出されるため、読み取りごとに同期する必要はありません。

## デプロイの形

| 形 | 説明 | 向いている人 |
| --- | --- | --- |
| Lite | 単一のマシン、単一のユーザー：ゲートウェイのプロセスが 1 つと、ローカルのストレージ（Git またはファイルシステムのスナップショット）。L0 から L1。 | 個人と、試してみたい開発者。 |
| Overlay | 既存の NAS やオブジェクトストアには手を付けず、前にゲートウェイを置いて、その中の 1 つのディレクトリやバケットだけを管理します。マウントと S3 のビューはゲートウェイを経由します。 | **もっとも現実的な出発点：** すでに筐体を持っている人。 |
| Team | 複数のユーザーとエージェント、1 台のサーバーか小さなクラスター。L0 から L3。ゲートの通知とコントロールルーム。 | 小さなチーム。 |
| Cloud | ホスト型のマルチテナントサービス、強い隔離。L0 から L3。 | 自前のハードウェアを持たない人。 |

原則：専用のハードウェアは要りません。常時稼働するマシンならどれでも構いません。アクセラレーターは任意です。埋め込みと要約には小さなモデルで足りますし、外部のサービスを呼んでも構いません。

## 既存の部品で v0 を作る

| 機能 | 今日使える部品 |
| --- | --- |
| Store とブランチ | Git と worktree、btrfs や ZFS のスナップショット、または Tigris と lakeFS（オブジェクトストレージ）。 |
| 保護されたメインライン | Forgejo、Gitea、GitHub のブランチ保護、または lakeFS の保護ブランチ。 |
| リース | トークン交換を備えた OAuth 認可サーバー（たとえば Keycloak）と、パスのプレフィックスと操作を検査するリソースサーバー。または数百行の署名サービス。 |
| 記録 | 追記のみの SQLite テーブルと日次のハッシュ、コミットの Git トレーラー、OpenTelemetry のエクスポート。 |
| ゲート | PR レビューとプッシュ通知、`nas gate approve` の CLI。 |
| 記憶 | `memory/` の下の Markdown と SQLite FTS5。ベクトルストアはあとから。 |
| ラベル | 取り込みディレクトリに `external` を付け、実行単位のセッション汚染はゲートウェイで保持する。 |
| インターフェース | NFS、SMB、FUSE のマウント、SSH または HTTPS 経由の Git、S3 ゲートウェイ、小さな MCP サーバー。 |

この表が言っているのは、**L0 と L1 には新しい発明は要らない** ということです。新しいのは、それらを組み合わせる契約と、それを検証するテストです。[仕様](https://agentnas.com/ja/spec/) を参照してください。

## 運用

- **バックアップ：** 3-2-1。スナップショットとバックアップは所有者のプリンシパルのもので、どのリースも触れられません。四半期ごとに復元訓練を行い、記録を残します。
- **アップグレード：** ゲートウェイは状態を持たないので、ローリングでアップグレードできます。Store の形式を変えるときは、必ず移行とロールバックの計画を添えます。Memory 層は丸ごと再構築できます。
- **監視：** リースの発行率と拒否率、ゲートのキューの長さと承認率（承認率が 95% を超え続けるなら、ゲートが多すぎるので、まとめるかポリシーを締めます）、ブランチの数と年齢、索引の鮮度、記録チェーンの検証、クォータ。
- **容量：** ブランチには TTL とクォータがあり、回収エリアには保持期間があり、導出データには予算があります。

## コントロールルーム

人間向けのインターフェースは、ウェブページでも、CLI でも、チャットボットでも構いません。必須ではありません。L0 から L1 は、CLI と既存の Git プラットフォームだけで動かせます。

- **アクティビティのタイムライン：** 実行ごとにまとめ、誰が何をし、何を読んだか。
- **ゲートの受信箱：** 承認待ちの操作を、Gate Card で表示します。
- **ロールのディレクトリ：** ロールごとの Home、リース、予算、最近の実行。
- **記憶ブラウザー：** ノートと出典、未レビューの隔離エリア、保守の提案。
- **ブランチと PR：** 未マージのブランチと回収エリア。
- **忘却コンソール：** 要求、系譜のプレビュー、レポート。

人間は SMB や WebDAV から直接見ることもできます。`/humans/<user>/Agent Activity/` は、普通のファイルでできた読み取り専用のアクティビティビューです。

---

正規 URL: https://agentnas.com/ja/architecture/
更新日: 2026-11-11 · 仕様ドラフト v0.2 · CC BY 4.0