Agent NAS v0.2
한국어

아키텍처

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

v0.2 명세 초안 최종 수정

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

  1. Interface (인터페이스)

    에이전트, 사람, 도구가 이미 쓰는 인터페이스로 기능을 내보냅니다. 게이트웨이는 상태를 갖지 않으며, 누가 무엇을 할 수 있는지는 결코 결정하지 않습니다.

    • 마운트 (FUSE, NFS, SMB)
    • Git
    • S3 호환
    • WebDAV
    • MCP
    • HTTP API
    • CLI
    • A2A (선택)
  2. Trust (신뢰)

    유일한 인가 지점. 판단에 모델이 관여하지 않는 결정론적 정책 엔진이며, 먼저 기록하고 나서 실행합니다.

    • 주체와 실행
    • Capability Lease
    • 정책 엔진
    • Human Gate
    • Trust Labels
    • Credential Broker
    • Flight Recorder
  3. Memory (메모리)

    노트를 검색할 수 있고 예산 안에서 읽을 수 있는 지식으로 바꿉니다. 모두 아래 계층에서 다시 만들 수 있습니다.

    • 노트 규약
    • 인덱스 (전문, 벡터, 그래프)
    • Budgeted Reads
    • 유지 관리 작업
    • 계보
    • Cascade Forget
  4. 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에는 새로운 발명이 필요 없습니다. 새로운 것은 이들을 묶는 계약과 그것을 검증하는 테스트입니다. 명세를 참고하세요.

운영

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

컨트롤 룸

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

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

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

이 페이지 인용하기

사람, 검색 엔진, 에이전트를 위한 고정 주소와 권장 인용 형식입니다.

권장 인용 형식
Agent NAS project. “아키텍처.” agentnas.com, 2026-11-11. https://agentnas.com/ko/architecture/