# 아키텍처

> Agent NAS는 네 개의 계층과 선택 사항인 동기화 계층으로 이루어집니다. Interface는 기능을 기존 인터페이스로 내보내고, Trust는 유일한 인가 지점이며, Memory는 노트를 검색할 수 있는 지식으로 바꾸고, Store는 이력이 있는 트리를 보관합니다. Memory 계층은 통째로 지웠다가 다시 만들 수 있으며, Store는 검증된 스토리지를 그대로 씁니다.

## 네 개의 계층과 선택 사항인 동기화

- **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는 메모리나 라벨의 의미를 이해하지 못합니다.** 메타데이터가 붙은 트리를 보관할 뿐입니다.
- **먼저 기록하고, 그다음에 실행합니다.** 중대한 작업은 먼저 의도 기록을 남겨야 합니다.

## 좁은 허리: 여섯 개의 명사

설계 전체가 여섯 개의 명사에 달려 있습니다. 라벨, 게이트, 메모리, 읽기 매니페스트는 그 위에 세운 규약입니다.

| 명사 | 의미 | 핵심 불변식 |
| --- | --- | --- |
| Tree | 이력이 있는 디렉터리 트리. | 어떤 커밋이든 재현할 수 있으며, 콘텐츠 해시 또는 그에 상응하는 변경 감지 수단이 있다. |
| Commit | 변경 불가능한 하나의 변경. | 출처 메타데이터를 담는다: `principal`, `on_behalf_of`, `run`, `lease`. |
| Principal | 인증할 수 있고 책임을 물을 수 있는 존재. | 유형은 `human`, `agent`, `service`, `node` 중 하나이며, `agent`는 하나의 실행이 아니라 역할에 속한다. |
| Run | 시작과 끝, 목적, 책임자가 있는 한 번의 실행. | 루트 리스 하나를 보유하고, 브랜치 하나를 소유한다. |
| Lease | 실행에 대한 인가. | 만료 시점이 있고, 좁히기만 할 수 있고, 취소할 수 있으며, 예산을 담는다. |
| Record | 추가만 가능한 기록. | 해시로 연결되며, 먼저 기록하고 나서 실행한다. |

## Store 계층: 계약과 선택 가능한 엔진

Store 계약은 엔진이 제공하거나 게이트웨이가 에뮬레이트합니다. 구현은 엔진을 섞어 쓸 수 있습니다. 예를 들어 텍스트에는 Git, 큰 파일에는 스냅샷을 쓸 수 있으며, 계약은 엔진, 해시 함수, 디스크 형식을 규정하지 않습니다.

1. 원자적 커밋.
2. 저렴한 포크: 이상적으로는 O(1)에 가깝게, 최악의 경우 복사로 저하되며, 이때는 쿼터와 TTL이 필수입니다.
3. 불변 스냅샷.
4. 변경 감지: 콘텐츠 해시 또는 그에 상응하는 수단.
5. 두 커밋 사이의 차이.
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. **요청.** 오케스트레이터(또는 소유자)가 한 번의 실행을 위해 리스를 요청합니다. 경로, 동작, 만료, 목적을 담습니다. **정책 범위** 안이면 자동으로 발급되고, 범위 밖이면 Human Gate로 갑니다.
2. **시작.** NAS가 `run`과 브랜치 `<role>/<run_id>`를 만들고 리스를 실행에 넘깁니다. 샌드박스는 브랜치를 마운트하거나 `git clone`을 합니다.
3. **작업.** 에이전트는 평범한 파일 도구로 읽고 씁니다. 읽기는 **읽기 매니페스트**에 쌓이고 세션 오염도 함께 갱신됩니다. 범위를 벗어난 접근은 거부되고 기록됩니다.
4. **커밋.** 변경은 자동으로(디바운스) 또는 명시적으로 커밋되며, 모든 커밋은 출처 메타데이터를 담습니다.
5. **제안.** `propose`가 **Agent PR**을 만듭니다. diff, 의도, 읽기 매니페스트 요약, 검사 결과, 라벨 요약이 들어갑니다.
6. **결정.** 정책 엔진이 결정합니다. 검사를 통과하고 위험이 낮으면 자동 병합하고, 보호된 데이터나 외부로 나가는 동작, Rule of Two 위반이 걸려 있으면 Human Gate로 보내고, 명백히 금지된 것이면 거부합니다.
7. **병합과 기록.** 병합은 출처가 담긴 커밋을 만들고 Record를 남깁니다.
8. **마무리.** 리스가 만료되고, 브랜치는 TTL이 지난 뒤 회수되며, 읽기 매니페스트와 Record는 보존 정책에 따라 유지됩니다.

**읽기 경로:** 요청, 리스 확인, 라벨 확인(현재 세션 오염이 이 읽기를 허용하는가?), 예산 계산, Store에서 읽기, 읽기 매니페스트에 기록, 콘텐츠와 증거 포인터 반환.

> **먼저 기록하고, 그다음에 실행한다.** 중대한 작업(병합, 삭제, 공유, 외부 전송, 리스 변경)은 먼저 의도 기록을 남겨야 합니다. 기록할 수 없으면 작업은 실패합니다(fail closed). 읽기는 읽기 매니페스트에 들어가며, 이 매니페스트는 묶음으로 반영하므로 읽기마다 동기적일 필요는 없습니다.

## 배포 형태

| 형태 | 설명 | 적합한 대상 |
| --- | --- | --- |
| Lite | 단일 기계, 단일 사용자: 게이트웨이 프로세스 하나와 로컬 스토리지(Git 또는 파일 시스템 스냅샷). L0~L1. | 써 보려는 개인과 개발자. |
| Overlay | 기존 NAS나 오브젝트 스토어는 그대로 두고, 앞에 게이트웨이를 놓아 디렉터리나 버킷 하나만 관리합니다. 마운트와 S3 뷰는 게이트웨이를 거칩니다. | **가장 현실적인 출발점:** 이미 장비가 있는 사람. |
| Team | 여러 사용자와 에이전트, 서버 한 대 또는 작은 클러스터. 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/ko/spec/)를 참고하세요.

## 운영

- **백업:** 3-2-1. 스냅샷과 백업은 소유자 주체의 것이며 어떤 리스도 건드릴 수 없습니다. 분기마다 복원 훈련을 하고 그 기록을 남깁니다.
- **업그레이드:** 게이트웨이는 상태가 없으므로 롤링 업그레이드가 가능합니다. Store 형식을 바꿀 때는 반드시 마이그레이션과 롤백 계획이 따라야 하며, Memory 계층은 통째로 다시 만들 수 있습니다.
- **모니터링:** 리스 발급률과 거부율, 게이트 대기열 길이와 승인율(승인율이 계속 95%를 넘으면 게이트가 너무 잦다는 뜻이므로 합치거나 정책을 조여야 합니다), 브랜치 수와 나이, 인덱스 최신성, 기록 체인 검증, 쿼터.
- **용량:** 브랜치에는 TTL과 쿼터가 있고, 회수 영역에는 보존 기간이 있으며, 파생 데이터에는 예산이 있습니다.

## 컨트롤 룸

사람을 위한 인터페이스는 웹 페이지, CLI, 챗봇 어느 것이어도 됩니다. 필수는 아닙니다. L0~L1은 CLI와 기존 Git 플랫폼만으로 완전히 운영할 수 있습니다.

- **활동 타임라인:** 실행 단위로 모아서 보여 줍니다. 누가 무엇을 했고 무엇을 읽었는가.
- **게이트 받은편지함:** 승인을 기다리는 동작을 Gate Card로 보여 줍니다.
- **역할 디렉터리:** 역할별 홈, 리스, 예산, 최근 실행.
- **메모리 브라우저:** 노트와 출처, 검토되지 않은 노트의 격리 영역, 유지 관리 제안.
- **브랜치와 PR:** 병합되지 않은 브랜치와 회수 영역.
- **망각 콘솔:** 요청, 계보 미리 보기, 보고서.

사람은 SMB나 WebDAV로 직접 볼 수도 있습니다. `/humans/<user>/Agent Activity/`는 평범한 파일로 만든 읽기 전용 활동 뷰입니다.

---

표준 URL: https://agentnas.com/ko/architecture/
최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0