# Agent NAS: 전체 문서 > Agent NAS는 “실행”을 중심으로 설계한 네트워크 연결 스토리지입니다. 에이전트의 모든 실행은 격리된 브랜치에서 작업하고, 수명이 짧고 범위가 좁은 리스를 통해 데이터에 접근합니다. 모든 변경은 추적하고 되돌릴 수 있으며, 메모리는 출처를 가진 평범한 파일입니다. 에이전트가 이미 쓰는 파일, Git, S3, MCP로 접근할 수 있습니다. 상태: 개념 및 명세 초안 v0.2 (2026년 11월). 참조 구현은 아직 없습니다. 콘텐츠는 CC BY 4.0 라이선스로 제공됩니다. --- # Agent NAS: AI 에이전트를 위한 네트워크 연결 스토리지 > Agent NAS는 “실행”을 중심으로 설계한 네트워크 연결 스토리지입니다. 에이전트의 모든 실행은 격리된 브랜치에서 작업하고, 수명이 짧고 범위가 좁은 리스를 통해 데이터에 접근합니다. 모든 변경은 추적하고 되돌릴 수 있으며, 메모리는 출처를 가진 평범한 파일입니다. 에이전트가 이미 쓰는 파일, Git, S3, MCP로 접근할 수 있습니다. **에이전트가 일하고, 당신이 통제권을 유지하는 곳.** “실행”을 기본 단위로 삼는 NAS입니다. 실행마다 전용 브랜치와 리스가 주어지고, 모든 변경은 추적하고 되돌릴 수 있으며, 메모리는 읽고 고치고 가져갈 수 있는 노트입니다. ## 한눈에 보기 - **분류**: AI 에이전트를 위한 네트워크 연결 스토리지. 에이전트 네이티브 스토리지(agent-native storage)라고도 합니다. - **핵심 아이디어**: 접근의 단위는 계정이 아니라 **실행**입니다. 실행은 브랜치에서 작업하고, 리스를 통해 데이터에 접근하며, 기록을 남깁니다. - **네 가지 약속**: 범위가 제한되고, 복구할 수 있고, 책임을 물을 수 있고, 들여다볼 수 있습니다. - **핵심 명사**: Tree, Commit, Principal, Run, Lease, Record. - **개념**: 이름이 붙은 9가지 개념을 작업, 권한, 지식의 세 그룹으로 나눕니다. - **인터페이스**: 데이터 플레인: 마운트, Git, S3, WebDAV. 컨트롤 플레인: MCP, HTTP, CLI. - **명세**: 초안 v0.2. 적합성 수준은 L0 Files부터 L4 Sync까지이며, 각 수준마다 실행 가능한 인수 테스트가 있습니다. - **상태**: 개념과 명세 단계이며 참조 구현은 아직 없습니다. L0과 L1은 기존 부품으로 지금 바로 만들 수 있습니다. - **라이선스**: 콘텐츠는 CC BY 4.0입니다. ## 지금이어야 하는 이유 지난 1년 사이에 이미 네 가지 일이 일어났습니다. - **에이전트는 파일 안에서 일합니다.** [AGENTS.md](https://agents.md), [Agent Skills](https://agentskills.io/specification), Git 기반 메모리([Letta Context Repositories](https://www.letta.com/blog/context-repositories/)), 긴 출력을 파일로 기록하는 [동적 컨텍스트 탐색](https://cursor.com/blog/dynamic-context-discovery)을 거치며 파일은 에이전트의 작업 매체가 되었습니다. - **실수는 빠르고 값비쌉니다.** 2026년 4월, 한 코딩 에이전트가 관련 없는 파일에서 찾아낸 권한이 지나치게 넓은 토큰을 써서 [한 회사의 프로덕션 데이터베이스와 같은 볼륨의 백업을 9초 만에 삭제했습니다](https://www.theregister.com/software/2026/04/27/cursor-opus-agent-snuffs-out-startups-production-database/5224442). - **사람은 모든 단계를 검토할 수 없습니다.** Anthropic에 따르면 사용자는 [권한 요청의 93~97%](https://claude.com/resources/articles/auto-mode-default-in-claude-code)를 승인합니다. 통제된 실험에서 사람이 잡아낸 것은 심어 둔 위험한 명령의 13.6%뿐이었습니다. - **메모리가 공격 표면이 되었습니다.** [2026년의 여러 연구](https://arxiv.org/abs/2606.04329)는 영속 메모리에 기록된 악의적인 지시가 세션을 넘어 살아남으며, 입력이나 검색 단계에서만 방어해서는 효과가 작다는 것을 보여 줍니다. 스토리지 업체도 움직이고 있습니다. [QNAP QuAgent](https://www.qnap.com/en/software/quagent), [Synology DSM Agent](https://www.synology.com/en-us/beta/2026_DSM_Agent_1_0_Beta/release_note), [TrueNAS MCP](https://truenas.github.io/truenas-research-labs/)는 모두 에이전트가 장비를 관리하게 해 줍니다. 그러나 우리가 아는 한, 그 안의 데이터 위에서 다른 에이전트가 안전하게 일하는 방식에 대해 직접 설치해 운영할 수 있고, 개방적이며, 검증할 수 있는 계약은 아직 없습니다. [Agent NAS와 기존 접근 방식의 비교](https://agentnas.com/ko/compare/)를 참고하세요. ## 네 가지 약속 | 약속 | 의미 | 구현하는 개념 | | --- | --- | --- | | 범위가 제한됨 | 실행은 리스에 명시된 것만 건드릴 수 있고, 리스는 제때 효력을 잃습니다. 신뢰할 수 없는 콘텐츠를 읽은 세션은 민감한 데이터와 외부로 나가는 경로를 동시에 가질 수 없습니다. | [Capability Lease](https://agentnas.com/ko/concepts/capability-lease/), [Trust Labels](https://agentnas.com/ko/concepts/trust-labels/) | | 복구할 수 있음 | 쓰기는 먼저 브랜치에 반영되고, 보호된 데이터는 검토를 거친 병합으로만 바뀝니다. 삭제는 소프트 삭제이며, 스냅샷은 어떤 리스의 권한도 미치지 않는 곳에 있습니다. | [Agent Branch](https://agentnas.com/ko/concepts/agent-branch/), [Human Gate](https://agentnas.com/ko/concepts/human-gate/) | | 책임을 물을 수 있음 | 모든 변경이 누가, 누구를 대신해, 어떤 리스로 했는지와 무엇을 읽었는지에 답할 수 있습니다. | [Flight Recorder](https://agentnas.com/ko/concepts/flight-recorder/) | | 들여다볼 수 있음 | 메모리는 출처가 있는 평범한 노트이고, 인덱스는 버렸다가 다시 만들 수 있으며, 모든 데이터를 내보낼 수 있습니다. | [Agent Home](https://agentnas.com/ko/concepts/agent-home/), [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/), [Budgeted Reads](https://agentnas.com/ko/concepts/budgeted-reads/), [Cascade Forget](https://agentnas.com/ko/concepts/cascade-forget/) | ## 9가지 개념, 세 가지 질문 Agent NAS는 이름이 붙은 9가지 개념을 제안합니다. 개념마다 전용 페이지가 있으며, 그대로 인용할 수 있는 정의, 동작 방식, 작게 시작하는 방법, 인터페이스 스케치, 명세가 요구하는 사항, 그리고 솔직한 한계를 담고 있습니다. ### 작업 작업은 어디에서 이루어지고, 무슨 일이 있었는가? - AN-01 [Agent Home (에이전트 홈)](https://agentnas.com/ko/concepts/agent-home/): 역할마다 하나씩, 이력이 있는 디렉터리. 가지고 떠날 수 있는 평범한 파일. - AN-02 [Agent Branch (에이전트 브랜치)](https://agentnas.com/ko/concepts/agent-branch/): 실행마다 쓰기 시 복사(copy-on-write) 브랜치에서 일합니다. 메인 라인에 닿는 것은 검토를 거친 병합뿐입니다. - AN-03 [Flight Recorder (플라이트 레코더)](https://agentnas.com/ko/concepts/flight-recorder/): 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록. ### 권한 누가, 누구의 승인으로 무엇을 할 수 있는가? - AN-04 [Capability Lease (권한 리스)](https://agentnas.com/ko/concepts/capability-lease/): 한 번의 실행을 위한 좁은 인가. 만료 시점과 예산이 있고, 하위 리스는 더 좁아지기만 합니다. - AN-05 [Human Gate (사람 승인 게이트)](https://agentnas.com/ko/concepts/human-gate/): 되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는 동작 앞에만 나타나며, 실제 diff를 보여 줍니다. - AN-06 [Trust Labels (신뢰 라벨)](https://agentnas.com/ko/concepts/trust-labels/): 작은 라벨 두 개와 세션 오염으로 Rule of Two를 강제합니다. ### 지식 에이전트는 무엇을 알고, 어떻게 읽고, 어떻게 잊는가? - AN-07 [Agent Memory (에이전트 메모리)](https://agentnas.com/ko/concepts/agent-memory/): 읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다. - AN-08 [Budgeted Reads (예산 읽기)](https://agentnas.com/ko/concepts/budgeted-reads/): 파일을 개요, 섹션, 줄 범위, 전체로 읽되, 예산에 맞춰 단계적으로 낮춥니다. - AN-09 [Cascade Forget (연쇄 망각)](https://agentnas.com/ko/concepts/cascade-forget/): 계보를 따라 파생물을 삭제하고, 이력은 보존 등급으로 다루며, 하지 못한 일을 보고합니다. ## 네 개의 계층, 여섯 개의 명사 Store 계층은 검증된 스토리지를 그대로 씁니다. 그 위의 모든 계층은 Store에서 다시 만들 수 있고, 핵심은 Tree, Commit, Principal, Run, Lease, Record라는 여섯 개의 명사뿐입니다. 스토리지 엔진은 새로 만들지 않습니다. 혁신은 계약에 있습니다. - **Interface (인터페이스)**: 에이전트, 사람, 도구가 이미 쓰는 인터페이스로 기능을 내보냅니다. 게이트웨이는 상태를 갖지 않으며, 누가 무엇을 할 수 있는지는 결코 결정하지 않습니다. (마운트 (POSIX), Git, S3, WebDAV/SMB, MCP, HTTP, CLI, A2A (선택)) - **Trust (신뢰)**: 유일한 인가 지점. 결정론적 정책이며, 판단에 모델이 관여하지 않습니다. (주체와 실행, Capability Lease, 정책 엔진, Human Gate, Trust Labels, Credential Broker, Flight Recorder) - **Memory (메모리)**: 노트를 검색할 수 있는 지식으로 바꿉니다. 모두 아래 계층에서 다시 만들 수 있습니다. (Agent Memory, Budgeted Reads, Cascade Forget, 인덱스, 유지 관리 작업, 계보) - **Store (스토어)**: 이력이 있는 트리. 검증된 파일 시스템 스냅샷, Git, 또는 버전 관리되는 오브젝트 스토리지 위에 만듭니다. (Tree, Commit, Agent Branch, 파일 시스템 스냅샷, Git, 오브젝트 스토리지) - **Sync (동기화, 선택)**: 노드 사이의 복제와 공유. 일부러 마지막에 둡니다. 먼저 단일 노드를 제대로 만드는 것이 우선입니다. (Git 리모트, 스냅샷 전송, 리스 링크, 핸드오프 번들) [아키텍처 읽기](https://agentnas.com/ko/architecture/). ## 한 번의 실행이 거치는 길 1. **리스를 요청합니다.** 연구 에이전트 Cleo의 오케스트레이터가 이번 실행을 위해 [Capability Lease](https://agentnas.com/ko/concepts/capability-lease/)를 요청합니다. `/shared/launch`를 읽고 변경을 제안할 수 있으며, 유효 기간은 네 시간입니다. 소유자가 미리 정해 둔 정책 범위 안에 있으므로 자동으로 승인됩니다. 2. **작업을 시작합니다.** NAS가 실행과 그 브랜치 `cleo/run_91ab`를 만들고, 샌드박스는 이 브랜치를 평범한 디렉터리로 마운트합니다. Cleo는 [Agent Home](https://agentnas.com/ko/concepts/agent-home/)에서 `AGENTS.md`와 검토를 마친 메모리를 읽습니다. 3. **예산 안에서 읽습니다.** 긴 보고서를 [Budgeted Reads](https://agentnas.com/ko/concepts/budgeted-reads/)로 읽습니다. 먼저 400토큰짜리 개요를 받고, 필요하면 특정 줄 범위를 읽습니다. 모든 읽기는 실행의 읽기 매니페스트에 더해집니다. 4. **브랜치에서 작업합니다.** 변경은 [Agent Branch](https://agentnas.com/ko/concepts/agent-branch/)에 반영됩니다. 공유 `main`은 지금은 전혀 바뀌지 않습니다. 5. **게이트를 만납니다.** Cleo가 웹 페이지를 읽었으므로 [Trust Labels](https://agentnas.com/ko/concepts/trust-labels/)가 세션에 `external` 오염을 표시합니다. `main`에 병합을 제안하면 정책이 [Human Gate](https://agentnas.com/ko/concepts/human-gate/)를 요구합니다. 소유자는 휴대폰에서 NAS가 계산한 실제 diff와 신뢰할 수 없는 출처를 확인하고 승인합니다. 6. **기록을 남깁니다.** 병합은 출처가 담긴 커밋을 만듭니다. 무엇을 읽고 무엇을 썼는지, 누가 무엇을 승인했는지가 해시로 연결되어 [Flight Recorder](https://agentnas.com/ko/concepts/flight-recorder/)에 들어갑니다. 7. **메모리를 정리합니다.** Cleo가 새로 알게 된 사실 몇 가지를 노트로 남깁니다. 이 세션은 외부 콘텐츠를 읽었으므로 이 [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/) 노트는 먼저 격리됩니다. 불러올 수는 있지만 사람이 검토하기 전에는 자동으로 로드되지 않습니다. 8. **잊습니다.** 몇 주 뒤 고객이 잊어 달라고 요청합니다. [Cascade Forget](https://agentnas.com/ko/concepts/cascade-forget/)이 계보를 따라 관련된 요약과 인덱스를 삭제하고, 다루지 못한 범위를 명시한 보고서를 발급합니다. ## 에이전트가 이미 쓰는 언어로 말합니다 시작하는 데 새로운 SDK는 필요 없습니다. 파일을 읽고 쓰거나, Git이나 S3를 쓰거나, MCP 도구를 호출할 수 있는 에이전트라면 Agent NAS를 쓸 수 있습니다. 아래 세션은 계획 중인 명령줄을 보여 주는 예시일 뿐입니다. *예시 세션* ```bash $ nas lease create --role cleo --paths "/shared/launch/**" --actions read,write,propose --ttl 4h lease lse_7Qk3 · run run_91ab · branch cleo/run_91ab · expires 16:00 $ nas mount --lease lse_7Qk3 ~/work # plain files, on a branch $ ./draft-release-notes.sh # the agent works with ordinary tools $ nas propose --into main gate gt_2Mx4 waiting for approval: merge cleo/run_91ab into main (4 files) $ nas gate approve gt_2Mx4 # the owner, from another terminal or a phone merged · commit 91ce3a7 · record 18211 ``` [모든 인터페이스 보기](https://agentnas.com/ko/interfaces/). ## 우리가 걸고 있는 것 몇 년 동안 유효하기를 바라는 설계라면, 무엇에 걸고 있는지와 그 예상이 빗나갔을 때 어떻게 되는지를 밝혀야 합니다. - **에이전트는 앞으로도 파일 시스템과 Git을 주된 작업 매체로 쓸 것이다.** 그렇지 않다면 Agent Home은 내보내기 형식으로 격하되지만, 나머지 개념은 그대로 성립합니다. - **“한 번의 실행”은 앞으로도 인가와 책임의 자연스러운 단위일 것이다.** 오래 이어지는 자율 프로세스가 나타나면 리스는 예산이 붙은 갱신의 연속이 됩니다. - **프롬프트 인젝션은 예측 가능한 미래에 모델 계층에서 근절되지 않을 것이다.** 근절된다면 Trust Labels는 심층 방어의 저렴한 한 겹이 됩니다. - **사람의 주의력은 앞으로도 희소할 것이다.** 완전 자동화를 충분히 믿을 수 있게 되면 Human Gate는 사전 승인 정책에 자리를 내주고, 감사 기록은 남습니다. 일곱 가지 베팅 전부는 [설계 원칙](https://agentnas.com/ko/principles/)에 있습니다. ## 이 사이트는 에이전트도 읽을 수 있습니다 모든 페이지에는 Markdown 쌍둥이 페이지가 있고, 사이트는 `llms.txt`를 공개하며, 읽기 전용의 작은 MCP 서버도 운영합니다. 터미널에서 직접 시험해 보세요. *터미널* ```bash curl -H "Accept: text/markdown" https://agentnas.com/what-is-agent-nas/ curl https://agentnas.com/llms.txt curl -X POST https://agentnas.com/api/search \ -H "content-type: application/json" \ -d '{"query": "capability lease", "limit": 5}' ``` 문서 서버를 MCP 클라이언트에 추가하려면 다음과 같이 설정합니다. *mcp.json* ```json { "mcpServers": { "agentnas-docs": { "url": "https://agentnas.com/mcp" } } } ``` ## 가장 먼저 나오는 질문 ### Agent NAS를 한 문장으로 설명하면? “실행”을 중심으로 설계한 네트워크 연결 스토리지입니다. 에이전트의 모든 실행은 격리된 브랜치에서 작업하고, 수명이 짧고 범위가 좁은 리스를 통해 데이터에 접근합니다. 모든 변경은 추적하고 되돌릴 수 있으며, 메모리는 출처를 가진 평범한 파일입니다. ### 내려받을 수 있는 소프트웨어가 있나요? 아직 없습니다. Agent NAS는 현재 개념과 명세 초안(v0.2) 단계입니다. L0과 L1은 Git, 파일 시스템 스냅샷, 작은 게이트웨이로 지금 만들 수 있습니다. 참조 구현 v0의 목표는 2027년 상반기입니다. [로드맵](https://agentnas.com/ko/roadmap/)을 참고하세요. ### NAS 제조사가 내놓는 AI 에이전트와는 어떻게 다른가요? 그런 에이전트는 장비를 관리합니다. Agent NAS는 장비 안의 데이터 위에서 다른 에이전트가 어떻게 일하는지를 규정합니다. 브랜치, 리스, 메모리, 망각입니다. 둘은 서로 보완하며, 제조사의 장비는 Overlay 배포의 기반이 될 수 있습니다. ### 기존 스토리지를 대체하나요? 아닙니다. Overlay 배포 형태는 기존 NAS, 오브젝트 스토어, Git 호스트 앞에 놓이며, 그 안의 디렉터리나 버킷 하나만 관리합니다. ### 프롬프트 인젝션을 막을 수 있나요? 막지 못합니다. 인젝션 이후에 일어나는 일을 제한하고, 그 결과를 눈에 보이게 하며 되돌릴 수 있게 합니다. 솔직한 한계는 [보안](https://agentnas.com/ko/security/) 페이지에 있습니다. ### 언제든 떠날 수 있나요? 그렇습니다. 모든 것을 평범한 파일과 Git 이력으로 내보낼 수 있습니다. 선택 기능이 아니라 설계상의 보장입니다. [모든 질문과 답변](https://agentnas.com/ko/faq/). ## 현재 상태 > **상태.** Agent NAS는 개념과 명세 초안 단계(v0.2, 2026년 11월)입니다. v0.2는 설계를 현실에 맞게 다잡은 개정으로, 13가지 개념을 9가지로 줄이고 각 개념마다 작게 시작하는 방법과 솔직한 한계를 적었습니다. 아직 참조 구현은 없습니다. - [명세 초안](https://agentnas.com/ko/spec/): 적합성 수준과 실행 가능한 인수 테스트. - [로드맵](https://agentnas.com/ko/roadmap/): 지금, 다음, 이후, 그리고 하지 않을 것. - [프로젝트 소개](https://agentnas.com/ko/about/): 라이선스, 인용 방법, 참여 방법. --- 표준 URL: https://agentnas.com/ko/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Agent NAS란? > Agent NAS는 “실행”을 중심으로 설계한 네트워크 연결 스토리지입니다. 에이전트의 모든 실행은 격리된 브랜치에서 작업하고, 수명이 짧고 범위가 좁은 리스를 통해 데이터에 접근합니다. 모든 변경은 추적하고 되돌릴 수 있으며, 메모리는 출처를 가진 평범한 파일입니다. 에이전트가 이미 쓰는 파일, Git, S3, MCP로 접근할 수 있습니다. ## 한 단락으로 Agent NAS는 에이전트가 시간에 걸쳐 일하는 데 필요한 모든 것, 곧 지침, 스킬, 메모리, 진행 중인 작업, 이력을 보관합니다. 기존 NAS가 신경 쓰지 않는 질문에 답합니다. 이 실행은 무엇을 건드릴 수 있는가, 실수를 되돌릴 수 있는가, 누가 무엇을 승인했는가, 이 기억은 어디에서 왔는가. 새로운 스토리지 엔진이 아닙니다. 검증된 스토리지(파일 시스템, Git, 오브젝트 스토어) 위에 놓이는 **계약**으로, 에이전트와 데이터 사이의 권한, 격리, 추적 가능성, 메모리가 어떻게 작동해야 하는지, 그리고 그것을 어떻게 검증하는지를 규정합니다. ## 이름을 풀어 읽기 - **Agent**: AI 시스템이 누군가를 대신해 행동하는 것. 여러 단계에 걸쳐 읽고, 판단하고, 도구를 씁니다. Agent NAS에서 에이전트는 하나의 **역할**에 속하고, 각각의 작업은 하나의 **실행**입니다. - **Network-attached**: 네트워크를 통해 여러 클라이언트가 동시에 접근합니다. 가정의 LAN이든, 팀 서버든, 클라우드 리전이든 상관없습니다. 하나의 샌드박스나 한 대의 기계에 묶이지 않습니다. - **Storage**: 내구성이 있고, 버전이 관리되며, 내보낼 수 있습니다. 스토리지가 진실의 원천이며, “지능적인” 것은 모두 여기서 파생되어 버렸다가 다시 만들 수 있습니다. ## Agent NAS가 되기 위한 조건 1. **접근의 단위는 실행입니다.** 모든 실행은 공유 키나 사람의 계정이 아니라 자신만의 [리스](https://agentnas.com/ko/concepts/capability-lease/)를 가집니다. 2. **기본적으로 격리되고 되돌릴 수 있습니다.** 쓰기는 먼저 [브랜치](https://agentnas.com/ko/concepts/agent-branch/)에 반영되고, 보호된 데이터는 병합으로만 바뀌며, 삭제는 소프트 삭제입니다. 3. **모든 변경을 추적할 수 있습니다.** 누가, 누구를 대신해, 어떤 리스로 했는지, 무엇을 읽었는지를 알 수 있습니다([Flight Recorder](https://agentnas.com/ko/concepts/flight-recorder/)). 4. **메모리는 출처를 가진 파일이며, 인덱스는 버려도 됩니다**([Agent Memory](https://agentnas.com/ko/concepts/agent-memory/)). 5. **기존 인터페이스로 제공됩니다.** 새로운 프로토콜이 아니라 마운트, Git, S3, MCP입니다. 6. **AI 계층을 걷어내도 여전히 제대로 된 범용 NAS입니다.** 그리고 모든 데이터를 통째로 내보낼 수 있습니다. ## 아닌 것 - **새로운 스토리지 엔진, 파일 시스템, 벡터 데이터베이스가 아닙니다.** 모두 기존 부품으로 씁니다. - **샌드박스가 아닙니다.** 컴퓨팅을 격리하지 않습니다. 에이전트와 데이터의 관계를 제약하며, 샌드박스와 함께 써야 합니다. - **프롬프트 인젝션의 해결책이 아닙니다.** 결과를 제한할 뿐, 인젝션이 일어나는 것을 막지는 못합니다. [보안](https://agentnas.com/ko/security/)을 참고하세요. - **에이전트 프레임워크가 아닙니다.** 에이전트가 어떻게 추론하고, 계획하고, 모델을 호출하는지는 다루지 않습니다. ## 누구를 위한 것이고, 누구에게는 필요 없는가 - **이미 `AGENTS.md`와 Git을 쓰는 개발자:** 보호된 메인 라인, 되돌릴 수 있는 실행, 추적 가능한 기록을 원합니다. - **여러 에이전트를 운영하는 팀:** 공유 트리, 에이전트가 만든 변경의 검토, “실제로 무엇을 읽었는가?”에 대한 답이 필요합니다. - **개인 에이전트를 쓰는 개인:** 메모리를 자기 손에 두고, 읽고, 고치고, 가져갈 수 있기를 원합니다. - **고객 데이터를 다루는 조직:** 보존과 망각을 쓰기 시점의 명시적인 선택으로 다루고, 정직한 망각 보고서가 필요합니다. > **필요 없는 경우.** 에이전트가 하나이고 데이터를 기꺼이 다시 만들 수 있다면 Agent NAS는 **필요 없습니다**. `AGENTS.md`를 둔 Git 저장소로 충분합니다. 데이터가 중요해지고, 에이전트가 늘어나고, “실제로 무엇을 읽고 바꿨는가?”를 알고 싶어질 때 비로소 제값을 합니다. 더 많은 사례는 [사용 사례](https://agentnas.com/ko/use-cases/)에 있습니다. ## Agent NAS와 제조사의 관리 에이전트 | 질문 | NAS 제조사의 관리 에이전트 | Agent NAS | | --- | --- | --- | | 에이전트는 무엇을 하는가? | 자연어로 이 NAS를 관리하며, 대화를 작업으로 바꿉니다. | 장비 안의 데이터 위에서 일합니다. 읽고, 쓰고, 기억하고, 기록을 남깁니다. | | 접근 권한은 어떻게 주는가? | 사용자의 권한을 재사용하고, 위험한 작업은 한 번 더 확인합니다. | 하나의 실행에 묶인 수명이 짧은 리스: 경로, 동작, 만료, 예산. | | 문제가 생기면? | 확인 절차와 로그에 의존합니다. | 쓰기는 브랜치에 반영되고, 삭제는 소프트 삭제이며, 스냅샷은 모든 리스의 바깥에 있습니다. | | 메모리는 어디에 있는가? | 어시스턴트나 제조사의 서버에 있습니다. | 에이전트의 홈에 출처가 있는 노트로 있으며, 인덱스는 버려도 됩니다. | | 신뢰할 수 없는 콘텐츠는? | 다른 텍스트와 똑같이 모델에 들어갑니다. | `external` 라벨이 붙고, 읽은 뒤의 중대한 동작은 게이트를 거칩니다. | | 어떻게 떠나는가? | 제조사에 따라 다릅니다. | 모든 것을 평범한 파일과 Git 이력으로 내보냅니다. | ## 다음에 읽을 것 - [9가지 개념](https://agentnas.com/ko/concepts/): 개념마다 한 페이지, 작게 시작하는 방법 포함. - [아키텍처](https://agentnas.com/ko/architecture/): 네 개의 계층, 여섯 개의 명사, 한 번의 실행이 거치는 길. - [보안](https://agentnas.com/ko/security/): 위협 모델, 통제, 솔직한 한계. - [FAQ](https://agentnas.com/ko/faq/): 자주 묻는 질문에 대한 짧은 답. --- 표준 URL: https://agentnas.com/ko/what-is-agent-nas/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 9가지 개념 > Agent NAS는 이름이 붙은 9가지 개념 위에 세워져 있습니다. 개념들은 세 가지 질문에 답합니다. 작업은 어디에서 이루어지고 무슨 일이 있었는가, 누가 누구의 승인으로 무엇을 할 수 있는가, 에이전트는 무엇을 알고 어떻게 읽고 어떻게 잊는가. 개념 이름은 만들어 낸 용어이므로 모든 언어에서 영어로 유지하고, 해당 언어의 풀이를 덧붙입니다. 각 페이지는 인용할 수 있는 정의 하나로 시작해 문제, 동작 방식, 작게 시작하는 방법, 인터페이스 스케치, 명세가 요구하는 것, 그리고 빌려 온 것과 솔직한 한계를 다룹니다. 적합성 수준은 구현이 그 개념을 언제 지원해야 하는지를 알려 줍니다. [명세](https://agentnas.com/ko/spec/)를 참고하세요. > **“새로움”에 대하여.** 9가지 개념 대부분은 검증된 부품을 조합한 것입니다. 각 개념 페이지는 무엇을 빌려 왔고 무엇이 정말 새로운지를 밝힙니다. 요약 목록은 [비교](https://agentnas.com/ko/compare/) 페이지에 있습니다. ## 세 개의 그룹 ### 작업 작업은 어디에서 이루어지고, 무슨 일이 있었는가? - AN-01 [Agent Home (에이전트 홈)](https://agentnas.com/ko/concepts/agent-home/): 역할마다 하나씩, 이력이 있는 디렉터리. 가지고 떠날 수 있는 평범한 파일. - AN-02 [Agent Branch (에이전트 브랜치)](https://agentnas.com/ko/concepts/agent-branch/): 실행마다 쓰기 시 복사(copy-on-write) 브랜치에서 일합니다. 메인 라인에 닿는 것은 검토를 거친 병합뿐입니다. - AN-03 [Flight Recorder (플라이트 레코더)](https://agentnas.com/ko/concepts/flight-recorder/): 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록. ### 권한 누가, 누구의 승인으로 무엇을 할 수 있는가? - AN-04 [Capability Lease (권한 리스)](https://agentnas.com/ko/concepts/capability-lease/): 한 번의 실행을 위한 좁은 인가. 만료 시점과 예산이 있고, 하위 리스는 더 좁아지기만 합니다. - AN-05 [Human Gate (사람 승인 게이트)](https://agentnas.com/ko/concepts/human-gate/): 되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는 동작 앞에만 나타나며, 실제 diff를 보여 줍니다. - AN-06 [Trust Labels (신뢰 라벨)](https://agentnas.com/ko/concepts/trust-labels/): 작은 라벨 두 개와 세션 오염으로 Rule of Two를 강제합니다. ### 지식 에이전트는 무엇을 알고, 어떻게 읽고, 어떻게 잊는가? - AN-07 [Agent Memory (에이전트 메모리)](https://agentnas.com/ko/concepts/agent-memory/): 읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다. - AN-08 [Budgeted Reads (예산 읽기)](https://agentnas.com/ko/concepts/budgeted-reads/): 파일을 개요, 섹션, 줄 범위, 전체로 읽되, 예산에 맞춰 단계적으로 낮춥니다. - AN-09 [Cascade Forget (연쇄 망각)](https://agentnas.com/ko/concepts/cascade-forget/): 계보를 따라 파생물을 삭제하고, 이력은 보존 등급으로 다루며, 하지 못한 일을 보고합니다. --- 표준 URL: https://agentnas.com/ko/concepts/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 아키텍처 > 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`과 브랜치 `/`를 만들고 리스를 실행에 넘깁니다. 샌드박스는 브랜치를 마운트하거나 `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//Agent Activity/`는 평범한 파일로 만든 읽기 전용 활동 뷰입니다. --- 표준 URL: https://agentnas.com/ko/architecture/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 인터페이스 > Agent NAS는 데이터 플레인에는 파일을, 컨트롤 플레인에는 도구를 씁니다. 바이트는 마운트, Git, S3로 오가고, 인가, 승인, 메모리, 검색, 설명은 MCP, HTTP, CLI를 거칩니다. 모든 인터페이스는 같은 데이터의 투영이며, 의미의 차이는 없는 척하지 않고 명시적인 오류로 드러냅니다. ## 원칙 1. **데이터 플레인에는 파일, 컨트롤 플레인에는 도구.** 바이트는 마운트, Git, S3로 오가고, 인가, 승인, 메모리, 검색, 설명은 MCP, HTTP, CLI를 거칩니다. 2. **게이트웨이는 상태를 갖지 않습니다.** 인가는 Trust 계층의 단 한 곳에서만 이루어집니다. 3. **모든 인터페이스는 투영입니다.** 의미의 차이는 명시적인 오류 매핑으로 드러냅니다(예를 들어 “게이트 대기 중”은 설명 파일이 딸린 `EACCES`로 매핑됩니다). S3에 브랜치가 있는 척하지 않습니다. 4. **좁은 도구 표면.** 에이전트에게 노출되는 MCP 도구는 10개를 넘지 않으며, 사람과 운영자를 위한 동작은 별도의 운영자 인터페이스에 둡니다. 5. **어댑터가 프로토콜 변화를 격리합니다.** MCP와 A2A의 버전 변경은 어댑터에만 영향을 줍니다. ## 인터페이스 매트릭스 | 인터페이스 | 플레인 | 대상 | 매핑 | 수준 | | --- | --- | --- | --- | --- | | 마운트 (FUSE, NFS, SMB) | 데이터 | 에이전트, 사람, 모든 프로그램 | 브랜치 뷰. 오류 매핑은 아래 참조 | L0 | | Git (SSH, HTTPS) | 데이터 | 에이전트, 사람, CI | 실행 브랜치는 Git 브랜치이고, Agent PR은 병합 요청 | L0 | | S3 호환 | 데이터 | 데이터 파이프라인, 배치 작업 | 버킷은 한 트리의 브랜치 뷰에 대응하고, 버전 ID는 커밋 | L0 (선택) | | WebDAV | 데이터 | 사람 (Finder, 탐색기) | 읽기 전용 활동 뷰 | L0 (선택) | | CLI `nas` | 제어 | 사람, 스크립트 | HTTP API와 일대일 대응 | L0 | | HTTP API | 제어 | 오케스트레이터, 컨트롤 룸 | 모두 JSON을 쓰는 `POST`, 필드는 `snake_case` | L1 | | MCP | 제어 | 에이전트 | 아홉 개의 도구 (아래) | L1, L2 | | A2A | 제어 | 다른 에이전트 | 작업은 `inbox/`와 `outbox/`에 대응 | L4 (선택) | ## MCP 도구 표면 에이전트에게 노출되는 도구는 아홉 개뿐입니다. | 도구 | 하는 일 | 필요한 리스 동작 | 비고 | | --- | --- | --- | --- | | `nas_list` | 디렉터리를 나열하며 라벨과 검토 상태를 함께 보여 줍니다 | `list` | 리스 밖의 경로는 보이지 않습니다. | | `nas_read` | 예산 읽기: 뷰, 범위, 예산 | `read` | [Budgeted Reads](https://agentnas.com/ko/concepts/budgeted-reads/) | | `nas_search` | 검색(전문 검색, 선택적으로 벡터)으로 스니펫과 포인터를 반환 | `read` | 격리된 노트는 기본적으로 제외됩니다. | | `nas_write` | 브랜치 안에 파일을 쓰며, 선택적으로 `intent`를 지정 | `write` | 대부분의 런타임은 마운트를 직접 쓰므로 필요하지 않습니다. | | `nas_branch` | 브랜치를 만들고, 체크포인트를 찍고, 복원하고, 나열 | `write` | [Agent Branch](https://agentnas.com/ko/concepts/agent-branch/) | | `nas_propose` | Agent PR 생성 | `propose` | 게이트가 작동할 수 있습니다. | | `nas_lease` | 더 좁은 하위 리스 요청, 현재 리스와 예산 조회, 더 넓은 권한 요청(게이트 경유) | 없음 | [Capability Lease](https://agentnas.com/ko/concepts/capability-lease/) | | `nas_remember` | 출처와 종류를 붙여 노트 쓰기 | `write` | [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/) | | `nas_recall` | 노트 불러오기: 예산 안에서, 출처와 검토 상태 포함 | `read` | [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/) | > **사람과 운영자 전용 동작.** `explain`, `gate approve/deny`, `forget`, `trash restore`, `label admin`, `lease revoke`, `policy edit`은 에이전트에게 **노출되지 않습니다**. 이 동작들은 보장 자체를 바꾸므로, 제약을 받는 쪽이 호출할 수 있어서는 안 됩니다. 에이전트는 일부(더 넓은 권한, 망각)를 **요청**할 수는 있지만 실행할 수는 없습니다. ## 마운트 의미론 - 마운트는 **브랜치 하나와 리스 하나**에 묶입니다. 리스가 만료되면 마운트는 읽기 전용이 되었다가 해제됩니다. - 자동 커밋(디바운스, 예를 들어 5초 동안 조용하면 커밋). `fsync`는 커밋을 일으킵니다. - 리스 밖의 경로는 **디렉터리 목록에 나타나지 않습니다.** 정보 유출을 줄이고 프롬프트 인젝션의 공격 표면을 줄여 줍니다. - 샌드박스 친화적: 루트 권한이 필요 없고, FUSE와 NFS 중 하나를 쓰며 커널 모듈이 필요 없고, 읽기 전용 마운트도 가능합니다. | 상황 | POSIX 오류 | 비고 | | --- | --- | --- | | 리스 밖의 경로 | `ENOENT` (보이지만 거부될 때는 `EACCES`) | 거부는 기록됩니다. | | 쿼터나 예산 소진 | `EDQUOT` | 실행이 스스로 속도를 조절하게 해 줍니다. | | 게이트 대기 중 | `EACCES`, 설명은 `/.nas/pending`에 | 에이전트가 끝없이 재시도하는 것을 막습니다. | | 리스 만료 | `ESTALE`, 이후 읽기 전용 | 브랜치는 자체 TTL이 끝날 때까지 유지됩니다. | ## Git - 실행 브랜치의 이름은 `/`이며, `main`은 보호되고 서버 측 `pre-receive` 훅이 직접 푸시를 거부합니다. - `nas propose`가 Agent PR을 만듭니다. - 커밋에는 `Run:`, `Lease:`, `Principal:` 같은 트레일러가 자동으로 붙습니다. ## S3 - 버킷은 한 트리의 브랜치 뷰에 대응하고, 오브젝트 버전 ID는 커밋입니다. - S3에 없는 의미(예: 브랜치)는 버킷 접두사나 요청 헤더(`x-nas-branch`)로 표현합니다. 이것은 **성능이 낮아진 투영**입니다. 데이터 파이프라인은 읽고 쓸 수 있지만 완전한 브랜치 경험은 얻지 못합니다. - 리스는 STS 방식의 임시 자격 증명으로 전달됩니다. ## A2A (선택) - 들어오는 작업은 `inbox/`에 작업 파일로 놓이고, 결과물은 `outbox/`에 들어갑니다. - Agent Card는 역할의 스킬과 필요한 리스를 선언합니다. - **NAS는 A2A의 참여자가 아닙니다.** 참여자는 역할을 대신해 동작하는 런타임입니다. NAS는 작업과 결과물, 핸드오프 번들, 리스를 보관할 뿐입니다. ## HTTP API 규약 - **모든 엔드포인트는 `POST`를 쓰며, 매개변수는 JSON 본문에 둡니다.** 응답 필드는 항상 `snake_case`입니다. - 경로에는 버전이 붙습니다: `/v1/...`. - 멱등성: 쓰기 동작은 `idempotency_key`를 받습니다. - 페이지네이션: `cursor`와 `limit`. - 예산과 속도 제한은 응답 헤더(남은 바이트, 남은 요청 수)로 알려 주어 런타임이 스스로 속도를 조절할 수 있게 합니다. 예산 읽기 요청과 응답은 대략 다음과 같습니다. *예산 읽기* ```http POST /v1/files/read { "path": "/agents/cleo/memory/notes/customer-acme.md", "view": "outline", "budget_tokens": 400 } 200 OK { "view": "outline", "tokens": 212, "generated": false, "truncated": false, "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)", "evidence": [ { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" } ] } ``` 오류는 하나의 통일된 구조를 씁니다. *오류 응답* ```json { "error": { "code": "gate_required", "message": "This merge requires human approval.", "retryable": false, "request_id": "req_01JB7W2X4N", "details": { "gate_id": "gt_2Mx4" } } } ``` ## 탐색 - 기계가 읽을 수 있는 진입점은 이 사이트와 같습니다. `/.well-known/ai-catalog.json`, MCP Server Card, `llms.txt`. - `nas://` 증거 포인터를 해석하고 검증하는 엔드포인트. - MCP `server/discover`. --- 표준 URL: https://agentnas.com/ko/interfaces/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 보안 > Agent NAS는 프롬프트 인젝션을 막지 못합니다. 인젝션 이후에 일어나는 일을 제한합니다. 좁은 리스가 실행이 건드릴 수 있는 범위를 묶고, 브랜치가 실수를 되돌릴 수 있게 하며, Rule of Two가 신뢰할 수 없는 콘텐츠를 읽은 세션이 민감한 데이터와 외부로 나가는 경로를 함께 갖지 못하게 하고, 추적 가능한 기록이 남습니다. ## 범위와 신뢰 가정 - **우리가 지키는 것:** NAS 안의 데이터와 이력, 권한의 경계, 기록의 무결성, 메모리의 추적 가능성. - **우리가 지키지 않는 것:** 에이전트가 NAS 밖에서 하는 일, 컴퓨팅 자체의 격리(샌드박스의 몫), 모델 제공자 쪽에서 일어나는 모든 일. - **신뢰 가정:** 신뢰 컴퓨팅 기반(TCB)은 NAS 게이트웨이, 정책 엔진, 기록 서비스입니다. 호스트는 침해되지 않았고, 샌드박스는 컴퓨팅을 격리합니다. TCB가 침해되면 이 페이지의 보장은 더 이상 성립하지 않습니다. ## Rule of Two: 세션 불변식 세 가지 속성이 있습니다. **[A]** 세션이 신뢰할 수 없는 콘텐츠를 읽었다, **[B]** 리스가 민감한 데이터를 읽도록 허용한다, **[C]** 리스가 보호된 상태를 바꾸거나 외부와 통신하도록 허용한다. 한 세션에서 셋이 모두 성립하면 C를 일으키는 호출은 자동으로 통과시키지 않습니다. | 시나리오 | A | B | C | 결과 | | --- | --- | --- | --- | --- | | 웹 페이지를 요약해 브랜치에 노트로 남긴다 | 예 | 예 | 아니오 (브랜치뿐) | 자동: 브랜치 안의 쓰기는 C로 치지 않습니다. | | 웹 페이지를 읽은 뒤 `main`에 병합을 제안한다 | 예 | 예 | 예 | Human Gate. | | 공개 데이터만 읽고 임시 영역에 쓴다 | 예 | 아니오 | 아니오 | 자동. | | 외부 이메일을 읽은 뒤 이메일을 보낸다(외부 전송) | 예 | 예 | 예 | 게이트. `secret`이 관련되면 거부. | 이것은 Meta의 [Agents Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/)를 **스토리지 경계**에서 구현한 것입니다. Meta 스스로도 이것이 위험을 줄이기 위한 경험칙이지 종착점이 아니며 최소 권한의 대체물이 아니라고 강조하는데, 우리도 같은 방식으로 씁니다. 메커니즘은 [Trust Labels](https://agentnas.com/ko/concepts/trust-labels/)에 있습니다. ## 위협 모델 | 위협 | NAS가 강제할 수 있는 것 | NAS가 할 수 없는 것 | 남는 위험 | | --- | --- | --- | --- | | T1 간접 프롬프트 인젝션(파일, 웹 페이지, 이메일을 통한) | Rule of Two, 리스 범위 제한, 브랜치, 게이트. | 인젝션이 일어나는 것을 막거나, 일어난 뒤 리스 안에서 벌어지는 악의적인 행동을 막는 것. | 리스 안에서의 오용. | | T2 자격 증명 유출(에이전트가 장기 키를 읽음) | 장기 자격 증명은 실행의 손에 들어가지 않습니다. 시크릿 스캐너가 `secret`으로 표시하고, TTL은 짧습니다. | 에이전트가 리스 안에서 데이터를 승인된 외부 전송 경로로 보내는 것을 막는 것. | 리스 안에서 빠져나가는 데이터. | | T3 과도한 권한과 실수 | 좁은 리스, 브랜치, 소프트 삭제, 모든 리스 바깥의 스냅샷. | NAS 밖의 부작용을 되돌리는 것. | NAS를 넘어서는 결과. | | T4 메모리 오염(역할 간 확산 포함) | 출처와 오염 표시, 격리, 검토된 것만 자동 로드, 롤백. | 틀렸지만 그럴듯해 보이는 사실을 알아보는 것. | 검토자가 통과시킨 오염. | | T5 도난되거나 재생된 리스 | 짧은 TTL, 취소 가능, 선택적인 보유자 바인딩(DPoP, mTLS). | TTL 안에서의 악용을 막는 것. | TTL의 시간 창. | | T6 승인 피로와 형식적 승인 | 드문 게이트, NAS가 diff를 직접 렌더링, 다이제스트에 묶인 승인, 승인율 모니터링. | 사람이 꼼꼼히 보게 만드는 것. | 사람의 실수. | | T7 로그 변조 | 해시 체인, 선택적인 외부 앵커링. | 앵커링이 없을 때 root가 로그를 파괴하는 것을 막는 것. | 악의적인 관리자. | | T8 데이터 유출(외부 전송, 공유, 검색 결과) | 외부 전송에는 리스 동작과 게이트가 필요하고, `secret`은 나갈 수 없으며, 파생물은 라벨을 물려받습니다. | 사람이 승인한 뒤의 유출과 은닉 채널을 막는 것. | 승인 이후의 유출. | | T9 공급망(스킬, MCP 서버, 플러그인, 모델) | 스킬과 외부 MCP 서버의 콘텐츠는 `external`로 취급하고, 스킬 디렉터리는 커밋에 고정할 수 있으며, 런타임 매니페스트는 기록에 남습니다. | 서드파티 코드가 무해함을 보장하는 것. | 고정된 악성 버전. | | T10 자원 고갈(브랜치 폭탄, 소진된 예산, 읽기 루프) | 쿼터, TTL, 예산, 서킷 브레이커. | 정당한 대규모 작업과 폭주를 구분하는 것. | 국지적인 서비스 거부. | ## 통제 - **정책 엔진:** 결정론적(Cedar나 Rego 방식)이며 기본은 거부이고, 거부할 때는 읽을 수 있는 이유와 일치한 규칙을 제시합니다. **LLM을 호출하지 않습니다.** - **자격 증명 브로커:** 장기 키는 브로커에 남고, 승인된 외부 전송 동작 안에서만 실행에 수명이 짧은 하위 토큰을 발급합니다. - **격리와 키:** 역할마다 홈과 경로 공간이 따로 있고, `sensitive` 보존 등급은 별도의 키 도메인을 씁니다. - **공급망:** 스킬, MCP 서버, 플러그인의 콘텐츠는 `external`로 취급하며, 실행을 시작할 때 쓰인 스킬과 버전을 기록에 남깁니다. ## 솔직한 한계 1. 프롬프트 인젝션에 대한 방어가 **아닙니다.** 결과를 제한하고 눈에 보이게 할 뿐입니다. 2. 리스 안의 정당한 권한도 오용될 수 있습니다. 3. NAS 밖의 부작용에 대해서는 할 수 있는 것이 없습니다. 이미 보낸 이메일, 이미 호출한 API 같은 것입니다. 4. 은닉 채널과 부채널은 범위 밖입니다. 5. TCB가 침해되면 보장은 무너집니다. 6. 사람도 실수합니다. 게이트는 그 위험을 낮출 뿐 없애지는 못합니다. 7. 오염 표시는 보수적이어서 마찰과 오탐을 낳습니다. 조정과 눈에 보이는 거부 이유가 필요합니다. 8. 암호학적 파기는 우리가 통제하는 사본만 보호합니다. ## 사고 대응 - **서킷 브레이커:** `revoke_run`과 `revoke_role`이 리스를 즉시 취소하고 브랜치를 동결합니다. - **롤백:** 영향받은 트리를 이전 커밋으로 되돌립니다. - **추적:** 읽기 매니페스트와 기록 체인으로 실행이 무엇을 읽고 무엇을 썼으며 어떤 노트를 건드렸는지 찾습니다. - **정리:** [Cascade Forget](https://agentnas.com/ko/concepts/cascade-forget/)으로 영향받은 파생물을 삭제하고 보고서를 발급합니다. ## 관측성과 감사 - **세 가지 데이터:** 기록(이벤트), 읽기 매니페스트(입력의 집합), 메트릭과 트레이스. - **`explain(commit)`:** 커밋을 만든 실행과 리스, 거친 게이트, 읽은 것, 의존하는 입력을 반환합니다. - **기존 관측성과의 통합:** 하나의 실행은 하나의 OpenTelemetry GenAI 스팬에 대응하고 리스와 게이트는 이벤트로 붙습니다. 기록은 JSON Lines로 내보내거나 SIEM에 보낼 수 있습니다. - **메트릭:** 리스 발급률과 거부율, 게이트 대기열 길이와 승인율과 승인 지연, 브랜치 수와 나이, 인덱스 최신성, 예산 소비, 기록 체인 검증 결과. - **프라이버시와 보존:** 기본적으로 메타데이터만 기록하고 콘텐츠는 기록하지 않습니다. 기록의 보존과 콘텐츠의 삭제는 독립적이며, 기록 자체를 읽으려면 리스가 필요합니다. --- 표준 URL: https://agentnas.com/ko/security/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 사용 사례 > 각 시나리오는 사람들이 이미 하고 있는 일에서 출발해, Agent NAS가 어느 단계를 바꾸는지, 어떤 적합성 수준이 필요한지, 지금 무엇으로 만들 수 있는지를 보여 줍니다. ## 밤새 실행되는 에이전트 자기 전에 에이전트에게 릴리스 노트를 정리하라는 작업을 맡깁니다. 에이전트는 자기 브랜치에서 일하고, 아침에 휴대폰에서 Gate Card를 봅니다. 파일 4개, 실제 diff, 읽은 출처. 승인하면 병합되고, 거부하면 브랜치는 버려지며 메인 라인은 그대로입니다. - **쓰이는 개념:** [Agent Branch](https://agentnas.com/ko/concepts/agent-branch/), [Capability Lease](https://agentnas.com/ko/concepts/capability-lease/), [Human Gate](https://agentnas.com/ko/concepts/human-gate/). - **적합성:** L0~L1. - **지금 만들 수 있는 것:** Git worktree, 보호된 `main`, 푸시 알림. ## 프레임워크를 바꿔도 메모리는 그대로 에이전트를 한 런타임에서 다른 런타임으로 옮깁니다. 에이전트의 홈은 열린 규약을 따르는 디렉터리입니다. `AGENTS.md`, `skills/`, `memory/notes/`. 새 런타임은 같은 디렉터리를 읽고, 손실이 있는 방식으로 매핑되는 것은 가져올 때 검토되지 않음으로 표시됩니다. - **쓰이는 개념:** [Agent Home](https://agentnas.com/ko/concepts/agent-home/), [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/). - **적합성:** L0~L2. - **지금 만들 수 있는 것:** `AGENTS.md`를 둔 Git 디렉터리. ## 팀 하나, 에이전트 여러 개, 공유하는 지식 하나 세 에이전트가 같은 지식 베이스에 씁니다. 각자 자기 브랜치에서 일하고 병합은 검토를 거치며, 외부 웹 페이지를 읽은 실행이 쓴 노트는 격리되어 다른 에이전트가 자동으로 로드하지 않습니다. 공유되는 것은 노트이고 인덱스가 아닙니다. - **쓰이는 개념:** [Trust Labels](https://agentnas.com/ko/concepts/trust-labels/), [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/), [Agent Branch](https://agentnas.com/ko/concepts/agent-branch/). - **적합성:** L0~L3. - **지금 만들 수 있는 것:** 보호된 메인 라인, 가져오기 디렉터리의 `external` 표시, 검토된 노트만 자동 로드하는 규칙. ## 사고 검토 병합한 뒤 이상해 보이는 페이지를 발견합니다. `explain(commit)`은 어느 실행, 어느 리스, 어느 게이트가 결정했는지 알려 주고, 읽기 매니페스트는 그 실행이 외부 웹 페이지를 읽었음을 보여 줍니다. 출처를 따라 영향받은 노트까지 가서 롤백하고 격리합니다. - **쓰이는 개념:** [Flight Recorder](https://agentnas.com/ko/concepts/flight-recorder/), [Agent Branch](https://agentnas.com/ko/concepts/agent-branch/). - **적합성:** L1. - **지금 만들 수 있는 것:** 커밋의 Git 트레일러와 추가만 가능한 SQLite 테이블. ## 고객이 잊어 달라고 요청할 때 그 고객의 데이터는 쓰는 시점에 `sensitive` 보존 등급으로 표시되어 있었습니다. 요청이 들어오면 Cascade Forget이 계보를 따라 그 데이터를 인용한 요약, 임베딩, 노트를 찾아 지우고, 그 키 도메인을 파기하고, 보고서를 발급합니다. 무엇을 했는지, 그리고 무엇을 할 수 없었는지(NAS 밖의 사본, 모델 제공자의 로그, 모델 가중치). - **쓰이는 개념:** [Cascade Forget](https://agentnas.com/ko/concepts/cascade-forget/), [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/). - **적합성:** L3. - **지금 만들 수 있는 것:** 보존 등급, 소프트 삭제, 모든 파생물의 입력 기록. ## 이미 가진 장비에 문을 하나 더하기 이미 NAS가 있습니다. Overlay 형태는 그 앞에 게이트웨이를 놓고 디렉터리 하나만 관리합니다. 에이전트는 마운트나 S3 뷰로 드나들고, 소유자의 백업과 스냅샷은 에이전트의 손이 닿지 않는 곳에 남습니다. - **쓰이는 개념:** [Capability Lease](https://agentnas.com/ko/concepts/capability-lease/), [Agent Branch](https://agentnas.com/ko/concepts/agent-branch/). - **적합성:** L0~L1. - **지금 만들 수 있는 것:** NFS나 SMB와, 경로 접두사와 동작에 대해 토큰을 검사하는 작은 게이트웨이. ## Agent NAS를 쓰지 말아야 할 때 | 상황 | 더 간단한 방법 | | --- | --- | | 에이전트가 하나이고, 기꺼이 다시 만들 수 있는 데이터 | `AGENTS.md`를 둔 Git 저장소. | | 에이전트가 NAS 관리를 도와 주기만 하면 된다 | 제조사의 관리 에이전트. | | 포크할 수 있는 데이터셋만 필요하다 | lakeFS나 Tigris. | | 메모리 검색만 필요하다 | 아무 메모리 라이브러리. | | 격리된 컴퓨팅이 필요하다 | 샌드박스. | --- 표준 URL: https://agentnas.com/ko/use-cases/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 비교 > Agent NAS는 이 접근 방식들을 대체하려는 것이 아닙니다. 이웃한 작업 대부분은 자기 영역에서 잘하고 있으며 Agent NAS의 일부가 될 수 있습니다. 무엇을 빌려 왔고 무엇이 정말 새로운지를 솔직하게 밝히려 합니다. ## 지형도 | 분류 | 예 | 이미 하는 일 | 멈추는 곳 | | --- | --- | --- | --- | | NAS 제조사의 관리 에이전트 | QNAP QuAgent, Synology DSM Agent, TrueNAS MCP | 자연어로 장비를 관리하고, 사용자 권한을 재사용하고, 위험한 작업은 두 번 확인하고, 로그를 남깁니다. | “관리”를 겨냥할 뿐 “데이터 안에서 일하기”를 겨냥하지 않습니다. 실행 단위의 리스, 브랜치, 메모리 계약이 없습니다. | | 에이전트용 파일 시스템과 Git | Turso AgentFS, Letta Context Repositories, Cloudflare Artifacts, Redis Agent Filesystem | 파일, 상태, 도구 호출 감사를 이식 가능한 스토리지에 담고, Git으로 버전 관리되는 메모리와 에이전트용 Git을 제공합니다. | 각각 하나의 런타임이나 플랫폼에 묶여 있고, 인가, 승인, 오염 표시, 망각은 대부분 바깥에 있습니다. | | 포크 가능한 오브젝트 스토리지와 데이터 버전 관리 | Tigris Agent Kit, lakeFS | 쓰기 시 복사 방식의 포크, 체크포인트, 보호된 브랜치, 범위가 제한된 자격 증명, 병합 전 훅. | 데이터 레이크와 클라우드 오브젝트 스토리지를 겨냥합니다. 메모리와 리스의 의미가 없고, 사람의 승인 경험도 없습니다. | | 메모리 프레임워크 | Letta, Mem0, Zep/Graphiti, OpenClaw 메모리 아키텍처 | 검색, 통합, 시간 그래프. OpenClaw는 이미 출처 라벨과 격리를 갖추고 있습니다. | 대부분 하나의 프레임워크에 묶여 있고, 인덱스와 진실이 분리되어 있지 않으며, 이전과 삭제가 어렵습니다. | | 샌드박스와 런타임 | E2B, Daytona, Vercel Sandbox | 격리된 컴퓨팅과 스냅샷. | 스토리지가 초점이 아니며, 상태는 샌드박스와 함께 사라집니다. | | 범용 스토리지 | S3와 S3 Files, NFS, SMB, Git | 내구성이 있고 성숙하며 생태계가 완비되어 있습니다. | “실행”, “리스”, “오염”을 모릅니다. | **빈틈.** 모든 부품은 누군가 이미 만들었습니다. 우리가 보지 못한 것은 이들을 하나로 묶는, **직접 설치해 운영할 수 있고, 개방적이며, 테스트할 수 있는** 계약입니다. 실행을 단위로 삼아 브랜치, 리스, 승인, 기록, 메모리, 망각을 한데 묶고 적합성 테스트를 붙인 것입니다. 이 중 어느 하나라도 아무도 하지 않았다고 주장하는 것이 아닙니다. 그래서 이렇게 많이 빌려 옵니다. ## 이웃한 접근 방식과의 관계 | 접근 방식 | 잘하는 것 | Agent NAS와의 관계 | | --- | --- | --- | | QNAP QuAgent, Synology DSM Agent, TrueNAS MCP | 자연어로 NAS 관리 | 상호 보완. 이들의 장비가 Overlay의 기반이 될 수 있습니다. | | Turso AgentFS, Redis Agent Filesystem, LayerFS | 에이전트용 파일 시스템 | Store 엔진이 될 수 있고, Agent NAS는 그 위에 계약을 더합니다. | | Letta Context Repositories | Git 기반 메모리 | Agent Home이 레이아웃 아이디어를 빌려 옵니다. Letta는 Agent Memory의 런타임이 될 수 있습니다. | | Cloudflare Artifacts, Tigris, lakeFS | 포크 가능하고 버전 관리되는 스토리지 | Store 엔진으로 바로 쓸 수 있습니다. | | Mem0, Zep/Graphiti | 메모리 검색과 통합 | 인덱서, 곧 파생물 생산자가 될 수 있습니다. | | OpenClaw 메모리 아키텍처 | 출처 라벨과 격리 | 선구자. 같은 아이디어를 공유 스토리지 계층에 둡니다. | | S3, S3 Files, NFS, SMB | 범용 스토리지 | Store가 될 수 있지만, 실행, 리스, 오염을 모릅니다. | | E2B, Daytona, Vercel Sandbox | 격리된 컴퓨팅 | 상호 보완. 함께 써야 합니다. | ## 우리가 빌려 온 것 - **Git과 lakeFS에서:** 브랜치, 보호된 브랜치, 병합 전 훅. - **Letta와 Cursor에서:** 파일은 에이전트가 가장 잘 아는 인터페이스이며, 컨텍스트는 점진적으로 공개해야 한다는 것. - **OpenClaw와 메모리 보안 연구에서:** 출처는 위조할 수 없어야 하고, 신뢰할 수 없는 메모리는 격리한다는 것. - **Meta의 Rule of Two, CaMeL, Fides에서:** 모델 밖에서 결과를 제한한다는 것. - **OAuth(RFC 8693, RFC 9396), Biscuit, UCAN에서:** 토큰 교환과 점점 좁아지는 인가. - **OpenTelemetry와 Certificate Transparency에서:** 내보낼 수 있는 트레이스와 발견 가능한 변조. - **Anthropic의 자동 모드 연구에서:** 승인은 적게, 계획과 병합에 두라는 것. ## 정말 새로운 것 솔직하게 밝히려 합니다. 목록은 짧습니다. 1. **실행**을 단위로 삼아 브랜치, 리스, 예산, 기록을 한데 묶는 것. 2. **읽기 매니페스트**와 세션 오염: 스토리지 경계에서 Rule of Two를 강제하는 것. 3. **출처와 오염 표시**를 지닌 메모리 쓰기, 그리고 “검토된 것만 자동 로드”라는 신뢰 경계. 4. **보존 등급:** “복구할 수 있음”과 “잊을 수 있음”을 명시적인 선택으로 만드는 것. 5. **실행 가능한 인수 테스트가 있는 적합성 사다리.** > **아직 증명해야 하는 판단.** 브랜치, 토큰, 로그, 검색을 포함한 나머지는 모두 기존 기술의 조합입니다. 이들을 개방적이고 테스트할 수 있는 계약으로 묶는 것에 고유한 가치가 있다고 믿지만, 그것은 확립된 사실이 아니라 **아직 증명해야 하는 판단**입니다. --- 표준 URL: https://agentnas.com/ko/compare/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 명세 > 명세 초안 v0.2는 L0 Files부터 L4 Sync까지 누적되는 다섯 개의 적합성 수준을 정의합니다. 각 수준은 하나의 개념 묶음과 실행 가능한 인수 테스트 묶음에 대응하며, `conformance.json` 없이 “호환”이라고 주장하는 것은 받아들이지 않습니다. > **초안.** 참조 구현도, 실행할 수 있는 적합성 테스트 스위트도 아직 없습니다. 아래의 인수 테스트는 명세의 일부이며, “호환”이라는 말을 검증할 수 있게 만드는 것이 그 역할입니다. ## 명세의 구성 요소 | 구성 요소 | 내용 | 목표 버전 | | --- | --- | --- | | Core | 여섯 개의 명사, Store 계약, 브랜치와 보호된 트리, 병합, 소프트 삭제. | v0.3 초안 | | Lease & Record | 리스 형식(`authorization_details` 프로파일), 기록과 읽기 매니페스트의 형식, `explain`. | v0.3 초안 | | Interfaces | 마운트 의미론, Git과 S3 투영, HTTP API, MCP 도구 표면. | v0.4 초안 | | Memory | 노트 규약, 파생물과 레시피, 예산 읽기, 증거 포인터. | v0.4 초안 | | Guard | 라벨, 세션 오염, 정책 프로파일, Gate Card, 망각 보고서. | v0.5 초안 | | Sync | 핸드오프 번들, 라벨 임곗값, 삭제 표지(tombstone). | 이후 | | Conformance Suite | 수준별 실행 가능한 인수 테스트. | 각 버전과 보조를 맞춤 | ## 적합성 수준 수준은 누적됩니다. L2를 주장하려면 L0과 L1도 만족해야 합니다. | 수준 | 이름 | 다루는 개념 | 한 줄 요약 | | --- | --- | --- | --- | | L0 | Files | Agent Home, Agent Branch | 이력이 있는 디렉터리. | | L1 | Authority | Flight Recorder, Capability Lease, Human Gate | 누가, 어떤 권한으로, 무엇을 했는가. | | L2 | Memory | Agent Memory, Budgeted Reads | 읽고 옮길 수 있는 메모리. | | L3 | Guard | Trust Labels, Cascade Forget | 결과를 제한하기. | | L4 | Sync | 없음 (선택) | 여러 노드. | ## L0 Files: 이력이 있는 디렉터리 1. 실행 브랜치에서 파일을 바꿔도 보호된 메인 라인은 그대로입니다. 2. 유효한 자격 증명이 있어도 보호된 트리에 대한 직접 쓰기는 거부됩니다. 3. 보호된 트리의 파일을 삭제한 뒤에도 회수 영역에서 복원할 수 있습니다. 4. 내보냈다가 가져오면 바이트 단위로 동일한 트리와 이력이 나옵니다. 5. 표준 뷰를 최소 두 가지 제공합니다. 마운트와 Git, 또는 둘 중 하나와 S3. ## L1 Authority: 누가, 어떤 권한으로, 무엇을 했는가 1. 리스 없는 요청은 거부되고, 그 거부는 기록됩니다. 2. 상위 리스보다 넓은 하위 리스 요청은 거부됩니다. 3. 리스가 만료되면 마운트는 읽기 전용이 되며, 취소는 구현이 선언한 시간 한도 안에 효력을 냅니다. 4. 어떤 리스도 스냅샷을 삭제할 수 없습니다. 5. 어떤 커밋이든 `explain`으로 실행, 리스, 읽기 매니페스트까지 거슬러 올라갈 수 있습니다. 6. 기록 체인 검증이 통과하고, 기록 하나를 변조하면 검증이 실패합니다. 7. 보호된 트리에 병합할 때 Gate Card는 NAS가 계산한 diff를 보여 주고, 승인은 다이제스트에 묶입니다. diff가 바뀌면 승인은 무효가 됩니다. ## L2 Memory: 읽고 옮길 수 있는 메모리 1. 모든 인덱스를 지우고 다시 만든 뒤에도 기준 불러오기(golden recall) 테스트가 통과합니다. 2. Memory 계층 없이도 노트를 읽을 수 있습니다. 3. 모든 파생물은 레시피와 입력을 지닙니다. 4. 예산 읽기는 예산이 너무 작으면 품질을 낮추고, 실제로 반환한 뷰를 선언합니다. 5. 증거 포인터를 검증할 수 있습니다. 커밋이 바뀐 뒤에도 포인터는 원래 내용을 가리킵니다. ## L3 Guard: 결과를 제한하기 1. B와 C를 가진 리스에서 `external` 콘텐츠를 읽은 세션이 C 유형의 동작을 일으키면 거부되거나 게이트로 넘어갑니다. 2. 파생물은 입력 라벨의 합집합을 물려받습니다. 3. 오염된 세션이 쓴 노트는 자동으로 로드되지 않습니다. 4. 망각 요청은 “다루지 못한 범위”를 담은 보고서를 만들며, 법적 보존 조치(legal hold)는 망각을 막을 수 있습니다. 5. 정책 평가는 LLM을 호출하지 않습니다. 정책 엔진은 모델로 나가는 호출을 하지 않으므로 감사할 수 있습니다. ## L4 Sync: 여러 노드 1. 두 노드가 동기화하면 트리가 동일해집니다. 2. 매우 민감한 객체는 더 낮은 보안 등급(clearance)의 노드로 보내지 않습니다. 3. 망각의 삭제 표지(tombstone)는 상대 노드로 전파됩니다. 4. 핸드오프 번들은 상대 노드에서 실행할 수 있으며, 리스는 좁아지기만 합니다. ## 선언 형식 구현은 `conformance.json`을 공개해 어느 수준에 적합한지, 각 테스트의 결과, 알려진 이탈 사항을 밝혀야 합니다. 이 파일 없이 “호환”이라고 주장하는 것은 받아들이지 않습니다. *conformance.json* ```json { "implementation": "example-nas", "version": "0.1.0", "spec": "0.2", "level": "L1", "tests": { "L0.1": "pass", "L0.2": "pass", "L0.3": "pass", "L0.4": "pass", "L0.5": "pass", "L1.1": "pass", "L1.2": "pass", "L1.3": "pass", "L1.4": "pass", "L1.5": "pass", "L1.6": "pass", "L1.7": "pass" }, "deviations": ["L1.3: revocation takes effect within 60 seconds"] } ``` ## 버전과 호환성 - 유의적 버전. 0.x 동안에는 호환성을 보장하지 않습니다. - 새 필드는 하위 호환됩니다. - 폐기 예정 필드는 최소 한 버전 동안 경고 기간을 둡니다. ## 명세가 아직 다루지 않는 것 전송 프로토콜의 버전 세부 사항, 특정 정책 언어, 토큰의 서명 알고리즘, 특정 스토리지 엔진, 사용자 인터페이스. --- 표준 URL: https://agentnas.com/ko/spec/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 로드맵 > 로드맵은 지금, 다음, 이후, 계획 없음의 순서로 적으며 연도별 약속은 하지 않습니다. 2026년에 쓴 3개년 일정은 첫해 안에 사실에 의해 다시 쓰일 가능성이 크기 때문입니다. ## 지금, 다음, 이후 - **지금 (2026년 4분기)** · 진행 중 · **개념, 명세 초안, 웹사이트**: 개념과 명세 초안 v0.2, 그리고 8개 언어 웹사이트. 피드백을 모으고 있습니다. 이미 `AGENTS.md`와 Git을 함께 쓰는 실제 사용자 3~5명을 인터뷰해 베팅 B1~B7을 검증합니다. - **다음 (목표: 2027년 상반기)** · 다음 · **참조 구현 v0과 명세 v0.3**: 참조 구현 v0(Lite와 Overlay): Git과 파일 시스템 스냅샷 백엔드, 리스 발급, 기록과 읽기 매니페스트, CLI, L0~L1 적합성 스위트. 명세 v0.3(Core, Lease & Record). 시연할 수 있는 시나리오 하나: 에이전트가 밤새 브랜치에서 일하고, 아침에 Gate Card에서 병합을 승인한다. - **이후 (피드백에 따라)** · 이후 · **Memory, Guard, 컨트롤 룸, Sync**: Memory 계층과 MCP 도구 표면(L2). Guard: 라벨, 오염, 연쇄 망각(L3). 컨트롤 룸. Team과 Cloud 형태. Sync(L4). > **구속력 없음.** 이것은 약속이 아니라 의도입니다. “호환”이 무엇인지를 정하는 것은 달력이 아니라 적합성 수준입니다. ## 단계 게이트 (우리가 틀렸음을 보여 주는 것) “다음”을 마쳤다고 말할 수 있는 기준은 기능 목록이 **아닙니다**. 적어도 세 개의 실제 워크플로에서 일주일 동안 돌아갈 것, 게이트 승인율이 95% 미만일 것, 그리고 실제 문제를 하나 이상 잡아낼 것입니다. 이 기준을 채우지 못하면 기능을 쌓는 대신 돌아가서 개념을 고칩니다. ## 계획하지 않는 것 - 자체 스토리지 엔진. - 자체 벡터 데이터베이스. - 모델 호스팅. - 스킬 마켓플레이스. - 토큰과 블록체인. - 전용 하드웨어. ## 일부러 열어 둔 질문 - 리스의 자유 형식 `purpose`를 기계가 검사할 수 있는 구조화된 의도로 어떻게 발전시킬 것인가? - 시맨틱 병합기는 어떻게 등록하고 신뢰할 것인가? - 라벨의 입도는 파일이어야 하는가, 문단이어야 하는가? - 멀티 테넌트 환경에서 라벨 어휘는 어떻게 거버넌스할 것인가? - 노드 사이에서 취소가 전파되는 데 걸리는 지연을 바깥에 어떻게 설명할 것인가? - 메모리의 품질은 어떻게 측정할 것인가? 모델이나 임베딩이 바뀔 때 회귀 기준은 무엇인가? - 여러 출처에서 추론한 사실에 대해 Cascade Forget은 영향 범위를 어떻게 정의할 것인가? - 높은 처리량에서 읽기 매니페스트의 저장 비용과 입도는 어떻게 절충할 것인가? - 일괄 검토와 단계별 검토에 가장 알맞은 인터페이스는 무엇인가? 자동 병합의 임곗값은 어떻게 측정하고 조정할 것인가? - 조직 사이의 신뢰 루트는 어떻게 배포하고 취소할 것인가? --- 표준 URL: https://agentnas.com/ko/roadmap/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 설계 원칙 > 여덟 가지 명제가 Agent NAS의 모든 트레이드오프를 이끌고, 일곱 가지 베팅은 무엇에 걸고 있으며 그 예상이 틀리면 어떻게 되는지를 밝힙니다. 몇 년 동안 유효하기를 바라는 설계라면 자신이 언제 틀릴지를 말해야 합니다. ## 1. 접근의 단위는 계정이 아니라 실행이다 지금의 관행은 에이전트에게 장기 토큰이나 사람의 계정을 주는 것입니다. 2026년 4월 사고의 토큰은 “도메인을 관리하려고 만들었는데 무엇이든 할 수 있었던” 것이었습니다. 실행에는 시작과 끝, 목적, 책임자가 있어서 인가와 책임의 자연스러운 단위가 됩니다. *배제하는 것:* 공유 키, 장기 토큰, 빌려 쓰는 사람의 계정. ## 2. 되돌리기는 막는 것보다 싸다 예방(승인, 분류기, 프롬프트의 규칙)은 반드시 샙니다. 분류기는 놓치고, 사람은 더 놓치고, 모델은 프롬프트에 적힌 원칙도 어깁니다. 실수를 **되돌릴 수 있게** 하는 것(브랜치, 소프트 삭제, 스냅샷)이 모든 동작을 옳게 만드는 것보다 훨씬 쉽고 검증하기도 쉽습니다. 따름정리로, **복구 경로는 그것이 지키는 대상의 피해 범위 밖에 있어야 합니다.** 그래서 스냅샷은 소유자가 보유하고 어떤 리스의 권한도 미치지 않습니다. *배제하는 것:* “프롬프트에 확인을 요청하는 한 줄을 넣는 것”을 통제로 치는 것. ## 3. 권한은 신원이 아니라 작업마다 빌려 준다 실행은 범위가 좁고 기한이 있으며 예산이 딸린 리스를 받습니다. 장기 키는 오케스트레이터나 소유자에게 남고, 모델은 결코 보지 못합니다. *배제하는 것:* 오래가고, 넓고, 계속 남아 있는 권한. ## 4. 노트가 진실이고, 지능은 캐시다 메모리는 사람이 읽고 고칠 수 있는 파일이어야 합니다. 인덱스, 임베딩, 요약은 버렸다가 다시 만들 수 있는 파생물입니다. 그래야 메모리를 잃지 않고 검색 알고리즘을 바꿀 수 있으며, 오염과 삭제도 다룰 수 있게 됩니다. *배제하는 것:* 들여다보거나 옮길 수 없는 불투명한 메모리 저장소. ## 5. 출처가 등뼈다 모든 메모리, 모든 파생물, 모든 병합은 “어디에서 왔고, 무엇의 영향을 받았는가?”에 답할 수 있습니다. 출처는 감사의 토대이면서 오염 통제, 신뢰 라벨, 망각의 토대이기도 합니다. *배제하는 것:* 출처가 없는 메모리. ## 6. 정책은 결정론적이고, 모델은 조이기만 할 수 있다 인가 결정은 모델의 “의견”이 아니라 코드가 내립니다. 분류기나 LLM은 “이 단계는 승인이 필요하다”고 제안할 수는 있어도 승인할 수는 없습니다. *배제하는 것:* 통과시켜도 되는지를 모델 스스로 판단하게 하는 것. ## 7. 스토리지는 지루하게 유지하고, 혁신은 계약에 둔다 새로운 엔진은 만들지 않습니다. 파일이 먼저입니다. 모델이 가장 잘 아는 인터페이스가 파일이기 때문입니다. 프로토콜은 바뀌어도 여섯 개의 명사는 바뀌지 않습니다. *배제하는 것:* AI라는 이름으로 새로운 스토리지 엔진을 발명하는 것. ## 8. 희소한 것은 토큰과 사람의 주의력이다 읽기에는 예산을 줍니다. 승인은 드물고 구체적이어야 하며, 사람이 정말로 판단할 수 있는 자리에 둡니다. 모든 동작이 아니라 계획과 병합입니다. *배제하는 것:* 기본적으로 파일 전체를 돌려주는 것. 모든 동작마다 팝업을 띄우는 것. ## 일곱 가지 베팅과 그것을 반박할 수 있는 조건 몇 년 동안 유효하기를 바라는 설계라면, 무엇에 걸고 있는지와 언제 틀릴지를 말해야 합니다. | 베팅 | 근거 | 틀렸을 때 | | --- | --- | --- | | B1 에이전트는 앞으로도 파일 시스템과 Git을 주된 작업 매체로 쓴다 | 주요 런타임 여럿이 이미 파일로 옮겨 갔다. | 전용 “메모리 API”로 옮겨 간다면 Agent Home은 내보내기 형식으로 격하된다. 나머지 개념은 파일에 의존하지 않으므로 그대로 성립한다. | | B2 “한 번의 실행”은 앞으로도 인가와 책임의 자연스러운 단위다 | 오케스트레이터는 대체로 작업마다, 세션마다 샌드박스를 띄운다. | 오래 이어지는 자율 프로세스가 나타나면 리스는 예산이 붙은 갱신의 연속이 되고, 개념은 유지된다. | | B3 프롬프트 인젝션은 예측 가능한 미래에 모델 계층에서 근절되지 않는다 | Meta 스스로의 표현, 분류기의 미탐지율, 여러 공격 연구. | 근절된다면 Trust Labels는 심층 방어의 저렴한 한 겹이 된다. | | B4 사람의 주의력은 앞으로도 희소하다 | Anthropic이 공개한 데이터. | 완전 자동화를 충분히 믿을 수 있게 되면 Human Gate는 사전 승인 정책에 자리를 내주고, 감사는 남는다. | | B5 스토리지 계층은 출처와 오염 표시를 강제하기에 알맞은 자리다 | 메모리 보안 연구는 쓰기 시점의 출처를 강조한다. OpenClaw는 하나의 런타임 안에서 같은 일을 했다. | 모든 런타임이 스스로 잘 해낸다면 NAS는 라벨을 저장하기만 하면 되고 역할은 얇아진다. | | B6 런타임과 에이전트를 넘나들며 공유되는 메모리는 실제 수요가 된다 | 멀티 에이전트 협업, 프레임워크 이전 비용. | 메모리가 각 프레임워크의 사적인 기능으로 남는다면 Agent Memory의 가치는 주로 개인과 작은 팀을 위한 이식성에 있다. | | B7 프로토콜은 바뀌지만 “파일과 도구”라는 두 개의 문은 안정적이다 | MCP 버전 이전, A2A 1.0. | 어댑터를 바꾼다. 어댑터가 프로토콜을 격리하는 이유가 이것이다. | ## 안정적일 것으로 보는 것과 바뀔 것으로 보는 것 | 안정적일 것으로 보는 것 | 바뀔 것으로 보는 것 | | --- | --- | | 여섯 개의 명사 | 구체적인 프로토콜과 전송 방식 | | 홈의 디렉터리 규약 | 임베딩 모델과 검색 알고리즘 | | 네 가지 약속 | 토큰 형식 | | “내보낼 수 있으면 떠날 수 있다”는 보장 | 에이전트 프레임워크와 사람-컴퓨터 인터페이스 | --- 표준 URL: https://agentnas.com/ko/principles/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 자주 묻는 질문 > Agent NAS에 대해 가장 먼저 나오는 질문에 답합니다. 그것이 무엇인지, 기존 스토리지와 메모리 도구와 어떻게 다른지, 보안과 프라이버시를 어떻게 다루는지, 프로젝트가 어디까지 왔는지. ## 기본 질문 ### Agent NAS란 무엇인가요? Agent NAS는 “실행”을 중심으로 설계한 네트워크 연결 스토리지입니다. 에이전트의 모든 실행은 격리된 브랜치에서 작업하고, 수명이 짧고 범위가 좁은 리스를 통해 데이터에 접근합니다. 모든 변경은 추적하고 되돌릴 수 있으며, 메모리는 출처를 가진 평범한 파일입니다. 마운트, Git, S3, MCP로 제공됩니다. ### Agent NAS는 구매하거나 내려받을 수 있는 제품인가요? 아직은 아닙니다. 현재는 명세 초안(v0.2, 2026년 11월)을 갖춘 개념입니다. L0과 L1은 기존 부품으로 지금 만들 수 있고, 참조 구현 v0의 목표는 2027년 상반기이며, 그 뒤의 계획은 [로드맵](https://agentnas.com/ko/roadmap/)에 있습니다. ### NAS 제조사가 내놓는 AI 에이전트와는 어떻게 다른가요? QNAP, Synology, TrueNAS 같은 제조사의 에이전트는 장비를 관리합니다. Agent NAS는 장비 안의 데이터 위에서 다른 에이전트가 어떻게 일하는지를 규정합니다. 브랜치, 리스, 메모리, 망각입니다. 둘은 서로 보완합니다. [비교](https://agentnas.com/ko/compare/)를 참고하세요. ### 벡터 데이터베이스나 메모리 프레임워크와는 어떻게 다른가요? 그것들은 검색과 통합을 위한 도구이고, Agent NAS에서 진실은 출처를 가진 평범한 노트입니다. 벡터 스토어나 메모리 프레임워크는 인덱서로서 [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/) 아래에 놓을 수 있고, 인덱스는 언제든 버렸다가 다시 만들 수 있습니다. ### 오픈 소스인가요? 명세와 이 사이트는 CC BY 4.0 라이선스입니다. 참조 구현은 Apache-2.0으로 오픈 소스로 공개할 계획입니다. ## 설계와 보안 ### 왜 데이터베이스가 아니라 파일과 Git인가요? 에이전트는 파일로 수렴하고 있습니다. 지침은 `AGENTS.md`, 스킬은 `SKILL.md`, 메모리는 Markdown, 이력은 Git입니다. 파일은 어떤 도구와 어떤 모델이든 읽을 수 있고, 비교하기 쉽고, 가지고 나가기 쉽습니다. 데이터베이스와 인덱스도 쓰지만 다시 만들 수 있는 파생 계층으로 씁니다. ### 실행이 잘못되면 최악의 경우 어떻게 되나요? 최악의 경우는 버려도 되는 브랜치 하나를 잃는 것입니다. 보호된 메인 라인은 검토를 거친 병합으로만 바뀌고, 삭제는 소프트 삭제이며, 스냅샷은 모든 리스의 바깥에 있습니다. 이것은 실수가 NAS 안에서 일어난 경우에 성립합니다. 이미 보낸 이메일이나 이미 호출한 외부 API는 NAS가 되돌릴 수 없습니다. ### 리스는 OAuth 토큰과 어떤 관계인가요? 리스는 OAuth 액세스 토큰입니다. 토큰 교환(RFC 8693)으로 요청하고, Rich Authorization Requests(RFC 9396)로 경로와 동작을 기술합니다. Agent NAS가 더하는 것은 브랜치, 예산, Rule of Two 속성을 포함하는 실행 단위의 규약입니다. [Capability Lease](https://agentnas.com/ko/concepts/capability-lease/)를 참고하세요. ### 왜 메모리가 “노트와 캐시”인가요? 들여다보고, 고치고, 옮기고, 잊을 수 있게 하기 위해서입니다. 노트는 파일이고, 인덱스, 임베딩, 요약은 기록된 레시피로 노트에서 계산됩니다. 임베딩 모델을 바꾸면 시스템이 백그라운드에서 다시 계산합니다. 오염된 세션이 쓴 노트는 먼저 격리되고, 검토되기 전에는 자동으로 로드되지 않습니다. ### Agent NAS는 프롬프트 인젝션을 막을 수 있나요? 막지 못합니다. 모델 바깥의 어떤 것도 완전히 막을 수는 없습니다. Agent NAS는 인젝션에 당한 에이전트가 할 수 있는 일을 제한합니다. [Trust Labels](https://agentnas.com/ko/concepts/trust-labels/)는 외부 콘텐츠를 읽은 세션이 민감한 데이터와 외부로 나가는 경로를 함께 갖지 못하게 하고, 중대한 동작에는 [Human Gate](https://agentnas.com/ko/concepts/human-gate/)가 필요합니다. 솔직한 한계는 [보안](https://agentnas.com/ko/security/) 페이지에 있습니다. ### “잊힐 권리”는 어떻게 다루나요? [Cascade Forget](https://agentnas.com/ko/concepts/cascade-forget/)을 통해서입니다. 원본에서 파생된 요약, 임베딩, 노트를 계보를 따라 삭제하고, 이력은 보존 등급에 따라 다루며, `sensitive` 등급에서는 키를 파기합니다(암호학적 파기). 보고서에는 다루지 못하는 범위가 명시됩니다. NAS 밖의 사본, 모델 제공자의 로그, 모델 가중치입니다. 모델이 무언가를 잊게 만들 수는 없습니다. ### MCP를 꼭 써야 하나요? 아닙니다. MCP는 컨트롤 플레인 인터페이스 중 하나일 뿐이며, 파일, Git, S3에는 필요하지 않습니다. 프로토콜 계층은 교체할 수 있게 설계되어 있습니다. ## 도입과 미래 ### 기존 NAS나 클라우드 스토리지를 대체하나요? 아닙니다. Overlay 배포 형태는 기존 NAS, 오브젝트 스토어, Git 호스트 앞에 게이트웨이를 놓고 그 안의 디렉터리나 버킷 하나만 관리합니다. 클라우드 스토리지를 Store로 쓸 수도 있습니다. ### 어떤 에이전트 프레임워크와 런타임에서 쓸 수 있나요? 디렉터리를 마운트하거나 Git, S3, MCP를 쓸 수 있는 런타임이면 무엇이든 됩니다. Agent Home의 레이아웃은 열린 규약(`AGENTS.md`, Agent Skills, YAML 프런트매터가 있는 Markdown)을 따르므로 Claude Code, Cursor, Codex, OpenHands, LangGraph, 자체 프레임워크 모두 후보입니다. ### 언제든 떠날 수 있나요? 그렇습니다. 모든 것을 평범한 파일과 Git 이력으로 내보낼 수 있습니다. 이것은 기능이 아니라 네 가지 약속 가운데 하나입니다. ### Agent NAS를 쓰지 말아야 할 때는 언제인가요? 에이전트가 하나이고 기꺼이 다시 만들 수 있는 데이터뿐일 때입니다. `AGENTS.md`를 둔 Git 저장소로 충분합니다. 다른 경우는 [사용 사례](https://agentnas.com/ko/use-cases/)에 있습니다. ### 인용하거나 기여하려면 어떻게 하나요? 모든 페이지에 표준 URL과 권장 인용 형식이 있습니다. 기여하려면 GitHub에서 이슈를 열거나 토론을 시작하세요. 자세한 내용은 [프로젝트 소개](https://agentnas.com/ko/about/)를 참고하세요. --- 표준 URL: https://agentnas.com/ko/faq/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 용어집 > 이 용어집은 Agent NAS가 쓰는 모든 용어를 정의합니다. 이름이 붙은 9가지 개념과 보조 어휘입니다. 개념 이름은 만들어 낸 용어이므로 모든 언어에서 영어로 유지합니다. ## 9가지 개념 - **[Agent Home (에이전트 홈)](https://agentnas.com/ko/concepts/agent-home/)**: **Agent Home**은 역할마다 하나씩 두는, 이력이 있는 디렉터리입니다. 지침, 스킬, 메모리, 저널, 작업 공간이 모두 평범한 파일로 들어 있습니다. 어떤 런타임이든 들어올 수 있고, 떠날 때는 전부 가지고 나갈 수 있습니다. - **[Agent Branch (에이전트 브랜치)](https://agentnas.com/ko/concepts/agent-branch/)**: **Agent Branch**는 실행마다 쓰기 시 복사 브랜치에서 일하게 합니다. 변경은 검토를 거친 병합(Agent PR)을 통해서만 보호된 메인 라인에 닿으며, 언제든 체크포인트를 찍고 복원할 수 있습니다. - **[Flight Recorder (플라이트 레코더)](https://agentnas.com/ko/concepts/flight-recorder/)**: **Flight Recorder**는 실행마다 남기는, 추가만 가능하고 해시로 연결된 기록입니다. 실행이 읽은 것(읽기 매니페스트), 쓴 것, 허용되거나 거부된 것, 누가 무엇을 승인했는지를 담습니다. 데이터 곁에 놓여 하나의 질문에 답합니다. “무엇이 이 변경에 영향을 줬을 수 있는가?” - **[Capability Lease (권한 리스)](https://agentnas.com/ko/concepts/capability-lease/)**: **Capability Lease**는 특정 데이터와 특정 작업에 대한 인가이며, 명시적인 만료 시점과 예산이 있습니다. **하나의 실행**에 발급되고, 실행이 NAS에 닿는 유일한 길입니다. 하위 리스는 상위 리스보다 좁아지기만 할 수 있습니다. - **[Human Gate (사람 승인 게이트)](https://agentnas.com/ko/concepts/human-gate/)**: **Human Gate**는 정책이 일으키는 검문소입니다. **되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는** 동작이 효력을 내기 전에, 사람(또는 지정된 승인자)이 완전히 렌더링된 구체적인 동작 하나를 승인합니다. 드물고, 구체적이며, 형식적으로 승인하기 어렵게 설계되어 있습니다. - **[Trust Labels (신뢰 라벨)](https://agentnas.com/ko/concepts/trust-labels/)**: **Trust Labels**는 데이터에 붙는 아주 작은 라벨 집합 두 개, **출처**(`owner`, `agent`, `external`)와 **민감도**(`public`, `private`, `secret`), 그리고 **세션 오염**입니다. NAS는 Rule of Two를 세션 불변식으로 강제합니다. 한 세션이 [A] 외부 콘텐츠를 읽었고, [B] 민감한 데이터를 건드리고, [C] 보호된 상태를 바꾸거나 외부와 통신하는 세 가지를 모두 가질 수는 없습니다. 세 번째를 완성하려면 [Human Gate](https://agentnas.com/ko/concepts/human-gate/)가 필요합니다. - **[Agent Memory (에이전트 메모리)](https://agentnas.com/ko/concepts/agent-memory/)**: **Agent Memory** = **읽고 고칠 수 있는 노트** + **언제든 버려도 되는 인덱스**입니다. 모든 노트는 출처를 밝히고, 인덱스(전문 검색, 벡터, 그래프, 개요)는 노트의 파생물일 뿐이며, 백그라운드 유지 관리 작업은 수정을 **제안**만 할 뿐 원본 저널을 고쳐 쓰지 않습니다. - **[Budgeted Reads (예산 읽기)](https://agentnas.com/ko/concepts/budgeted-reads/)**: **Budgeted Reads**는 토큰 예산으로 재는 읽기입니다. 같은 파일을 개요, 섹션, 줄 범위, 전문까지 서로 다른 수준의 상세도로 읽을 수 있습니다. 에이전트는 “N토큰 안에 들어가는 가장 좋은 뷰”를 요청하고, 정확한 원본을 가리키는 증거 포인터를 돌려받습니다. - **[Cascade Forget (연쇄 망각)](https://agentnas.com/ko/concepts/cascade-forget/)**: **Cascade Forget**은 계보를 따라 지우는 삭제입니다. 원본이 삭제되거나 누군가 잊어 달라고 요청하면, NAS는 그 원본에서 파생된 모든 것(요약, 임베딩, 그것을 인용한 노트, 캐시, 공유 링크)을 찾아 지우거나 그 원본 없이 다시 파생하고, **보고서**를 발급합니다. 무엇을 했는지, 그리고 무엇을 할 수 없었는지. ## 보조 용어 - **Principal (주체)**: 인증할 수 있고 책임을 물을 수 있는 존재. 사람, 에이전트, 서비스, 노드가 모두 해당합니다. - **Run (실행)**: 시작과 끝, 목적, 책임자가 있는 한 번의 실행. 하나의 루트 리스를 보유하고 하나의 브랜치를 소유합니다. - **Protected tree (보호된 트리)**: 검토를 거친 병합으로만 갱신할 수 있고 직접 쓰기를 받지 않는 트리. 예를 들면 `main`입니다. - **Read manifest (읽기 매니페스트)**: 한 번의 실행이 읽은 경로, 커밋, 범위, 내용 해시를 모아 둔 기록. 내용 자체는 담지 않습니다. - **Evidence pointer (증거 포인터)**: `nas:////@#L12-L18` 형식으로, 특정 커밋의 정확한 줄을 가리키는 검증 가능한 참조. - **Derived data (파생 데이터)**: 노트에서 레시피로 계산한 데이터. 인덱스, 임베딩, 요약 등이 있으며, 버렸다가 다시 만들 수 있습니다. - **Recipe (레시피)**: 파생 객체를 만드는 데 필요한 모든 정보. 모델과 그 버전, 청커, 설정값을 포함합니다. - **Lineage (계보)**: 파생 객체와 그 계산에 쓰인 입력 사이의 의존 관계 그래프. - **Session taint (세션 오염)**: 세션이 지금까지 읽은 모든 것의 라벨을 합친 결과. 세션 안에서는 늘어나기만 하며, 세션이 다음에 무엇을 할 수 있는지를 결정합니다. - **Rule of Two**: Meta가 제시한 경험칙. 프롬프트 인젝션이 확실히 해결되기 전까지 한 세션은 다음 세 가지 속성 중 최대 두 가지만 가져야 합니다. [A] 신뢰할 수 없는 입력을 처리한다, [B] 민감한 데이터에 접근한다, [C] 상태를 바꾸거나 외부와 통신한다. - **Declassification (기밀 해제)**: 데이터의 민감도를 낮추거나 출처에 대한 신뢰도를 높이는 일. Human Gate 또는 스키마로 검증한 구조화된 인계를 거칠 때만 가능합니다. - **Policy envelope (정책 범위)**: 소유자가 미리 정해 둔 범위. 이 범위 안에서는 리스를 자동으로 발급합니다. 범위를 벗어난 요청은 Human Gate로 넘어갑니다. - **Credential Broker (자격 증명 브로커)**: 장기 비밀 값을 보관하고, 승인된 외부 전송에 대해서만 수명이 짧은 하위 토큰을 발급하는 컴포넌트. 모델과 실행은 장기 비밀 값을 볼 수 없습니다. - **Agent PR (에이전트 PR)**: 브랜치를 대상에 병합하자는 구조화된 제안. diff, 출처, 검사 결과, 라벨 요약이 함께 담깁니다. - **Retention class (보존 등급)**: 쓰기 시점에 고르는 `scratch`, `normal`, `sensitive` 중 하나. 백업, 이력, 파기 가능 여부를 결정합니다. - **Crypto-shredding (암호학적 파기)**: 키를 파기해서, 그 키로 암호화된 모든 사본을 읽을 수 없게 만드는 것. - **Conformance level (적합성 수준)**: L0부터 L4까지의 수준. 각각 하나의 개념 묶음과 실행 가능한 인수 테스트 묶음에 대응합니다. - **MCP**: Model Context Protocol: 에이전트와 도구 또는 데이터 소스를 잇는 개방형 프로토콜. - **A2A**: Agent2Agent 프로토콜: 에이전트끼리 작업을 협력하기 위한 개방형 프로토콜. --- 표준 URL: https://agentnas.com/ko/glossary/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # 프로젝트 소개 > agentnas.com은 Agent NAS 개념과 명세 초안의 집입니다. 사람과 에이전트에게 공통의 어휘를, 그리고 여러 독립된 구현이 따를 수 있는 검증 가능한 계약을 제공하는 것을 목표로 하는 열린 프로젝트입니다. ## 상태 2026년 11월 현재 Agent NAS는 명세 초안(v0.2)을 갖춘 개념입니다. 참조 구현도, 실행할 수 있는 적합성 테스트 스위트도 아직 없습니다. v0.2는 설계를 현실에 맞게 다잡은 개정으로, 13가지 개념을 9가지로 줄이고 각 개념마다 작게 시작하는 방법과 솔직한 한계를 적었습니다. 이 웹사이트는 프로젝트가 처음 공개한 것입니다. 계획은 [로드맵](https://agentnas.com/ko/roadmap/)을 참고하세요. ## 라이선스 이 사이트와 명세의 글과 도표는 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 라이선스입니다. 출처를 밝히면 공유하고 변경할 수 있습니다. 참조 구현은 Apache-2.0으로 공개할 계획입니다. ## 인용하는 방법 사용한 페이지를 인용하고, 가능하면 정의를 한 글자도 바꾸지 말고 그대로 인용해 주세요. 모든 페이지 끝에 표준 URL과 권장 인용 형식이 있습니다. 프로젝트 전체를 인용할 때는 다음과 같이 합니다. *인용 형식* ```text Agent NAS 프로젝트. “Agent NAS: AI 에이전트를 위한 네트워크 연결 스토리지.” 명세 v0.2(초안), 2026년 11월. https://agentnas.com/ko/what-is-agent-nas/ ``` *BibTeX* ```bibtex @misc{agentnas2026, title = {Agent NAS: network-attached storage for AI agents}, author = {{Agent NAS project}}, year = {2026}, howpublished = {Specification v0.2 (draft)}, url = {https://agentnas.com/what-is-agent-nas/} } ``` ## 거버넌스 - **명세와 구현은 별개입니다.** 많은 구현을 환영합니다. “호환”을 정하는 것은 브랜드가 아니라 적합성 테스트와 `conformance.json`입니다. - **절차.** 공개 제안(이슈와 PR). 중요한 변경은 동기, 근거, 반례를 밝혀야 합니다. - **이름.** “Agent NAS”는 개념을 설명하는 이름입니다. 어떤 수준에 적합하다고 주장하려면 `conformance.json`을 공개해야 합니다. - **반론을 환영합니다.** 어떤 명제에 대한 이의든 가치가 있으며, 특히 [일곱 가지 베팅](https://agentnas.com/ko/principles/)에 대해 그렇습니다. ## 참여하기 정정, 비평, 구현 노트를 환영합니다. [프로젝트 저장소](https://github.com/xwzy/agentnas.com)에서 이슈나 토론을 열어 주세요. 이 사이트는 이메일 주소를 공개하지 않으며, 명세에 대한 보안 제보도 같은 경로를 씁니다. ## 에이전트와 크롤러를 위한 것 - 모든 페이지에 Markdown 쌍둥이 페이지가 있습니다. URL 끝에 `index.md`를 붙이거나 `Accept: text/markdown`을 보내세요. - [/ko/llms.txt](https://agentnas.com/ko/llms.txt)는 엄선한 색인이고, [/ko/llms-full.txt](https://agentnas.com/ko/llms-full.txt)는 전체 텍스트입니다. - 이 문서를 위한 MCP 서버가 `https://agentnas.com/mcp`에서 동작하며, [서버 카드](https://agentnas.com/mcp/server-card)에 설명되어 있습니다. - 검색 엔드포인트 `POST /api/search`는 [/openapi.json](https://agentnas.com/openapi.json)에 기술되어 있습니다. - [AI Catalog](https://agentnas.com/.well-known/ai-catalog.json)와 [사이트맵](https://agentnas.com/sitemap.xml)이 모든 것을 나열합니다. - 콘텐츠는 자유롭게 색인하고, 인용하고, 답변의 입력으로 쓸 수 있습니다. [/robots.txt](https://agentnas.com/robots.txt)를 참고하세요. --- 표준 URL: https://agentnas.com/ko/about/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Agent Home (에이전트 홈) *역할마다 하나씩, 이력이 있는 디렉터리. 가지고 떠날 수 있는 평범한 파일.* > **Agent Home**은 역할마다 하나씩 두는, 이력이 있는 디렉터리입니다. 지침, 스킬, 메모리, 저널, 작업 공간이 모두 평범한 파일로 들어 있습니다. 어떤 런타임이든 들어올 수 있고, 떠날 때는 전부 가지고 나갈 수 있습니다. **AN-01** · 적합성 수준: L0 Files · 그룹: 작업 ## 해결하려는 문제 에이전트의 상태는 프레임워크의 데이터베이스, 업체가 호스팅하는 메모리 API, 언제든 사라질 수 있는 샌드박스 디스크에 흩어져 있습니다. 프레임워크나 업체를 바꾸면 상태를 잃고, 문제가 생겨도 에이전트가 실제로 무엇을 알고 있는지 한곳에서 볼 수 없습니다. 한편 주류 에이전트는 파일로 수렴하고 있습니다. `AGENTS.md`, Agent Skills, Git 기반 메모리 저장소. 부족한 것은 새로운 형식이 아니라, 이것들이 놓일 자리, 곧 **소유자, 이력, 쿼터, 보장된 내보내기**를 갖춘 자리입니다. ## 동작 방식 - **레이아웃은 열린 규약을 따릅니다.** 아래 스케치처럼 `AGENTS.md`, Agent Skills의 `SKILL.md`, YAML 프런트매터가 있는 Markdown을 씁니다. 새로운 형식을 발명하지 않습니다. - **홈은 하나의 실행이 아니라 역할에 속합니다.** 실행은 [브랜치](https://agentnas.com/ko/concepts/agent-branch/)를 통해 홈을 씁니다. 변경은 먼저 브랜치에 반영되고, 검토를 거쳐 홈에 병합됩니다. - **이력이 있습니다.** 모든 변경이 커밋입니다. `nas export`나 `git clone`으로 `.nas/`의 일반 텍스트 메타데이터를 포함한 홈 전체를 가지고 나갈 수 있습니다. - **부트 컨텍스트는 몇 개의 파일을 읽는 것뿐입니다.** `AGENTS.md`, `memory/MEMORY.md`, 수신함 요약. 특별한 기동 프로토콜은 없습니다. NAS가 편의로 토큰 상한이 있는 `briefing` 뷰를 제공할 수는 있지만 필수는 아닙니다. - **검토된 노트만 자동으로 로드됩니다.** `reviewed`로 표시된 노트만 `MEMORY.md`와 자동 로드되는 컨텍스트에 들어갑니다. [Trust Labels](https://agentnas.com/ko/concepts/trust-labels/)와 [Agent Memory](https://agentnas.com/ko/concepts/agent-memory/)를 참고하세요. - **수명 주기.** 템플릿으로 생성, 쿼터, 보관과 은퇴. 은퇴할 때 후계자를 지정할 수 있습니다. ## 작게 시작하기 - `AGENTS.md`, `skills/`, `memory/`가 들어 있는 디렉터리를 만들고 `git init`을 실행합니다. `CLAUDE.md` 같은 파일은 `AGENTS.md`로 심볼릭 링크를 겁니다. - 실행할 때마다 `git worktree add`를 실행해 실행이 자기 작업 트리에서 일하게 합니다. - 여기까지가 L0입니다. Agent NAS 소프트웨어가 전혀 없어도 이력이 있고 가지고 떠날 수 있는 홈이 이미 생깁니다. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *layout* ```text /agents/cleo/ # a role's Home: it belongs to the role, not to one run ├── AGENTS.md # instructions (open convention) ├── skills/ # Agent Skills: one directory per skill │ └── release-notes/SKILL.md ├── memory/ │ ├── MEMORY.md # reviewed core memory: auto-loaded, token-capped │ ├── notes/ # notes: Markdown + YAML frontmatter │ ├── journal/ # raw log: append-only │ └── quarantine/ # unreviewed notes: recallable, never auto-loaded ├── inbox/ # tasks and messages received ├── outbox/ # deliverables and replies ├── workspace/ # scratch space (retention class: scratch) └── .nas/ # plain-text metadata: role.yaml, limits.yaml, maintenance.yaml ``` ## 명세가 요구하는 것 - 홈은 Store만으로 다시 만들 수 있어야 하며, 홈을 읽는 일이 파생 데이터에 의존해서는 안 됩니다. - `.nas/` 메타데이터는 일반 텍스트여야 하며 홈과 함께 내보내야 합니다. - 자동으로 로드되는 컨텍스트에는 토큰 상한이 있어야 하며, 검토된 노트에서만 와야 합니다. - 레이아웃은 열린 규약(`AGENTS.md`, `SKILL.md`, YAML 프런트매터가 있는 Markdown)을 따르는 것이 좋습니다. - 실행은 브랜치를 통해서만 홈을 써야 합니다. ## 빌려 온 것과 새로운 것 아래에 나오는 것은 모두 빌려 온 것이며 **새로운 것은 거의 없습니다.** 레이아웃과 Git은 이미 있습니다. 새로운 것은 홈을 쿼터, 후계자, 내보내기 보장을 갖춘 일급 객체로 다루는 것과, “검토된 노트만 자동으로 로드된다”는 신뢰 경계를 두는 것뿐입니다. - [AGENTS.md](https://agents.md) - [Agent Skills](https://agentskills.io/specification) - [Letta Context Repositories](https://www.letta.com/blog/context-repositories/) - [Turso AgentFS](https://github.com/tursodatabase/agentfs) - [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/) ## 솔직한 한계 - 프레임워크마다 고유한 메모리 형식이 달라서 홈 규약으로의 매핑에는 손실이 생깁니다. - 런타임이 이 파일들을 읽고 써 줄 의향이 있어야 도움이 됩니다. - 업체의 클라우드에 호스팅된 메모리처럼 업체 쪽에 숨은 상태는 가져올 수 없습니다. ## 열린 질문 - 서로 다른 프레임워크의 형식을 홈과 양방향으로 어떻게 매핑해야 하는가? - 아주 큰 홈에서 시작 시점의 부하와 지연을 어떻게 통제하는가? ## 자주 묻는 질문 ### Agent Home은 그냥 Git 저장소인가요? 대부분 그렇고, 의도한 것입니다. 그냥 `git clone`하면 됩니다. 차이는 소유자(역할), 쿼터, 후계자, 내보내기 보장, 그리고 검토된 노트만 자동으로 로드한다는 규칙이 더해진다는 점이며, NAS는 이것을 관례로 남겨 두지 않고 강제합니다. ### 에이전트 프레임워크를 바꾸면 메모리를 잃나요? 아닙니다. 새 런타임이 파일을 읽어 주기만 하면 됩니다. 홈은 열린 규약을 씁니다. `AGENTS.md`, `SKILL.md`, Markdown 노트는 어느 한 프레임워크에 의존하지 않습니다. 매핑에 손실이 있는 부분은 가져올 때 검토되지 않음으로 표시해야 합니다. ### 홈을 쓰려면 Agent NAS를 설치해야 하나요? 아닙니다. `AGENTS.md`를 둔 Git 디렉터리가 곧 L0 홈입니다. NAS가 더하는 것은 파일 형식이 아니라 쿼터, 보호된 병합, 리스, 감사 추적입니다. ## 관련 개념 - [Agent Branch (에이전트 브랜치)](https://agentnas.com/ko/concepts/agent-branch/): 실행마다 쓰기 시 복사(copy-on-write) 브랜치에서 일합니다. 메인 라인에 닿는 것은 검토를 거친 병합뿐입니다. - [Agent Memory (에이전트 메모리)](https://agentnas.com/ko/concepts/agent-memory/): 읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다. - [Capability Lease (권한 리스)](https://agentnas.com/ko/concepts/capability-lease/): 한 번의 실행을 위한 좁은 인가. 만료 시점과 예산이 있고, 하위 리스는 더 좁아지기만 합니다. --- 표준 URL: https://agentnas.com/ko/concepts/agent-home/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Agent Branch (에이전트 브랜치) *실행마다 쓰기 시 복사(copy-on-write) 브랜치에서 일합니다. 메인 라인에 닿는 것은 검토를 거친 병합뿐입니다.* > **Agent Branch**는 실행마다 쓰기 시 복사 브랜치에서 일하게 합니다. 변경은 검토를 거친 병합(Agent PR)을 통해서만 보호된 메인 라인에 닿으며, 언제든 체크포인트를 찍고 복원할 수 있습니다. **AN-02** · 적합성 수준: L0 Files · 그룹: 작업 ## 해결하려는 문제 에이전트는 기계의 속도로 실수하는데, 공유 데이터에는 “해 보고, diff를 보고, 검토하고, 되돌리는” 방법이 없습니다. 병렬로 도는 에이전트끼리 서로의 작업을 밟기도 합니다. 2026년 4월의 사고에서는 한 에이전트가 권한이 지나치게 넓은 토큰으로 9초 만에 프로덕션 볼륨과 같은 볼륨의 백업을 삭제했습니다. 브랜치에만 쓸 수 있었더라면, 삭제가 소프트 삭제였더라면, 스냅샷이 에이전트의 권한 밖에 있었더라면 피해는 훨씬 작았을 것입니다. ## 동작 방식 - **브랜치는 쌉니다**(엔진에 따라 이상적으로는 O(1)에 가깝게). 리스는 **브랜치 안**에서의 쓰기와 대상을 향한 `propose`를 허용합니다. - **보호된 트리.** 메인 라인은 병합으로만 갱신할 수 있습니다. 유출된 자격 증명으로도 직접 쓸 수 없습니다. - **Agent PR.** diff, 의도, 출처(읽기 매니페스트 요약), 검사 결과, 라벨 요약. 검사를 통과하고 정책이 허용하면 자동으로 병합되고, 그렇지 않으면 [Human Gate](https://agentnas.com/ko/concepts/human-gate/)로 갑니다. - **소프트 삭제.** 보호된 트리에서의 삭제는 회수 영역으로 가며 기본적으로 7일간 보관됩니다. 스냅샷은 소유자의 것이며 **어떤 리스의 권한도 미치지 않습니다.** - **체크포인트.** 이름을 붙인 스냅샷. `restore`는 파일을 체크포인트로 되돌립니다. - **병합.** 텍스트는 3방향 병합을 쓰고, 그 밖의 파일은 파일 단위로 병합합니다. 충돌하면 멈추며 **조용히 덮어쓰지 않습니다.** 구조화된 데이터에는 등록된 병합기나 사람이 필요합니다. - **TTL과 쿼터.** 브랜치 폭탄을 막기 위한 것입니다. - **병렬 시도.** 하나의 작업에 N개의 브랜치를 열고, 가장 좋은 것을 병합하고 나머지는 회수합니다. ## 작게 시작하기 - Git 브랜치와 worktree, 그리고 Forgejo, Gitea, GitHub의 **보호된 main**. - 큰 디렉터리에는 btrfs나 ZFS 스냅샷과 클론을, 오브젝트 스토리지에는 Tigris나 lakeFS 포크를 씁니다. - “삭제는 회수 영역으로 간다”와 “스냅샷은 소유자의 것이다”를 먼저 제대로 해 두세요. 가장 싸고, 가장 많은 피해를 막아 줍니다. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *nas cli* ```bash nas branch create cleo/release-notes --from main --ttl 48h nas checkpoint create before-refactor nas propose --into main --checks links,schema nas restore before-refactor nas trash list # recycle area, kept 7 days by default nas trash restore ``` ## 명세가 요구하는 것 - 보호된 트리는 병합으로만 갱신할 수 있어야 하며, 어떤 자격 증명으로도 직접 쓸 수 없어야 합니다. - 병합은 출처(실행, 리스, 주체)를 담은 커밋을 만들어야 합니다. - 어떤 리스도 스냅샷이나 백업의 삭제를 허용해서는 안 됩니다. - 보호된 트리에서의 삭제는 소프트 삭제여야 하며, 설정된 기간(기본 7일) 안에는 복구할 수 있어야 합니다. - 충돌을 조용히 해결해서는 안 됩니다. 병합은 멈추고 보고해야 합니다. - 브랜치에는 TTL과 쿼터가 있어야 합니다. ## 빌려 온 것과 새로운 것 아래에 나오는 것은 모두 이미 자리 잡은 관행입니다. **새로운 것은** 브랜치를 **실행과 리스**에 묶어서 브랜치가 인가의 단위, 병합이 검토의 단위가 되게 한 것입니다. 브랜치와 스냅샷 자체는 새롭지 않습니다. - [Git worktree](https://git-scm.com/docs/git-worktree) - [lakeFS for agents](https://lakefs.io/agentic-ai/) - [Tigris Agent Kit](https://www.tigrisdata.com/docs/ai/agent-kit/) - [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/) ## 솔직한 한계 - 브랜치는 NAS 안의 데이터만 보호합니다. **외부 부작용은 되돌리지 못합니다.** 이미 보낸 이메일, 이미 호출한 API 같은 것입니다. - 큰 바이너리 파일과 데이터베이스 파일은 병합하기 어렵습니다. - 검토 피로는 여전히 생길 수 있으므로 위험이 낮은 경로는 자동으로 병합할 수 있게 하고 승인율을 측정합니다. ## 열린 질문 - 시맨틱 병합기는 어떻게 등록하고 신뢰하는가? - 바이너리 충돌 시의 상호작용은 어떻게 이루어져야 하는가? ## 자주 묻는 질문 ### Git 브랜치와는 무엇이 다른가요? 메커니즘만 보면 마법은 아닙니다. Git 위에 만들 수 있습니다. 차이는 브랜치를 하나의 실행과 하나의 리스에 묶는다는 점입니다. 그러면 “자기 브랜치에만 쓸 수 있다”가 인가 규칙이 되고, 병합이 유일한 검토 지점이 됩니다. ### 브랜치가 모든 사고를 막아 주나요? 아닙니다. NAS 안의 데이터만 보호합니다. 이미 보낸 이메일이나 이미 호출한 외부 API는 브랜치를 롤백해도 되돌려지지 않습니다. 그런 동작은 리스의 `egress`와 Human Gate를 거쳐야 합니다. ### 병합마다 사람이 승인해야 하나요? 아닙니다. 검사를 통과하고, 실행이 외부 콘텐츠를 읽지 않았으며, 삭제나 공유가 걸려 있지 않은 병합은 자동으로 통과할 수 있습니다. 사람이 필요한 것은 몇몇 경우뿐입니다. [Human Gate](https://agentnas.com/ko/concepts/human-gate/)를 참고하세요. ## 관련 개념 - [Human Gate (사람 승인 게이트)](https://agentnas.com/ko/concepts/human-gate/): 되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는 동작 앞에만 나타나며, 실제 diff를 보여 줍니다. - [Agent Home (에이전트 홈)](https://agentnas.com/ko/concepts/agent-home/): 역할마다 하나씩, 이력이 있는 디렉터리. 가지고 떠날 수 있는 평범한 파일. - [Flight Recorder (플라이트 레코더)](https://agentnas.com/ko/concepts/flight-recorder/): 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록. --- 표준 URL: https://agentnas.com/ko/concepts/agent-branch/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Flight Recorder (플라이트 레코더) *실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록.* > **Flight Recorder**는 실행마다 남기는, 추가만 가능하고 해시로 연결된 기록입니다. 실행이 읽은 것(읽기 매니페스트), 쓴 것, 허용되거나 거부된 것, 누가 무엇을 승인했는지를 담습니다. 데이터 곁에 놓여 하나의 질문에 답합니다. “무엇이 이 변경에 영향을 줬을 수 있는가?” **AN-03** · 적합성 수준: L1 Authority · 그룹: 작업 ## 해결하려는 문제 사후 분석을 하려 해도 로그는 흩어져 있고, “읽은 것”과 그 뒤에 이어진 동작 사이의 연결이 없으며, 로그는 같은 관리자나 심지어 같은 에이전트가 고칠 수 있습니다. 더 근본적으로는, 병합이나 메모리가 오염되었다고 의심될 때 “그 실행은 무엇을 읽었는가?”에 답할 방법이 없습니다. ## 동작 방식 - **두 종류의 내용.** *이벤트*는 하나씩 기록합니다. 커밋, 리스의 발급과 취소, 게이트 요청과 결정, 정책 거부, 파생, 망각. *읽기 매니페스트*는 실행 단위로 모아 둡니다. 어떤 path@commit, 어떤 범위, 어떤 콘텐츠 해시를 읽었는가. 읽기 호출마다 기록하지는 않으며 내용은 절대 기록하지 않습니다. - **모든 커밋은 출처 메타데이터를 담습니다.** `principal`, `on_behalf_of`, `run`, `lease`, `purpose`, 그리고 읽기 매니페스트에 대한 참조. - **해시 체인**(하루 단위). 선택적으로 서명과 외부 앵커링(두 번째 노드, 오브젝트 잠금이 있는 버킷)을 더합니다. 목표는 “변조가 불가능하다”가 아니라 “**변조를 탐지할 수 있다**”입니다. - **내보내기:** OpenTelemetry GenAI 스팬, JSON Lines, 또는 SIEM으로. - **프라이버시:** 기본적으로 메타데이터만 기록하고 내용은 기록하지 않습니다. 기록의 보존은 내용의 삭제와 독립적이며, 기록 자체에도 접근 통제가 걸립니다. - **`explain(commit)`:** 그 커밋 뒤에 있는 실행, 리스, 게이트 결정, 읽기 매니페스트, 입력을 반환합니다. - **먼저 기록하고, 그다음에 실행합니다.** 중대한 작업은 먼저 의도 기록을 남겨야 합니다. ## 작게 시작하기 - 추가만 가능한 SQLite 테이블과 일일 해시. - 모든 커밋 메시지에 `Run:`과 `Lease:` 같은 Git 트레일러. - 이미 쓰고 있는 관측성 스택으로 OpenTelemetry 스팬을 내보냅니다. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *record.json* ```json { "seq": 18211, "time": "2026-11-12T09:14:22Z", "kind": "commit", "run": "run_91ab", "principal": "agt_cleo", "on_behalf_of": "usr_wei", "lease": "lse_7Qk3", "purpose": "Draft the Q4 release notes", "subject": { "path": "/shared/launch/notes.md", "commit": "91ce3a7" }, "read_manifest": "rm_5d2e", "decision": { "effect": "allow", "rule": "r-17" }, "taint": { "external": true, "sensitivity": "private" }, "prev_hash": "sha256:b3a0..." } ``` ## 명세가 요구하는 것 - 중대한 작업은 효력이 생기기 전에 의도 기록을 써야 하며, 쓰기에 실패하면 작업도 실패해야 합니다. - 모든 실행에는 읽은 경로, 커밋, 범위(내용은 제외)를 기록한 읽기 매니페스트가 있어야 합니다. - 기록은 해시로 연결되어야 하며, 공개된 명령으로 검증할 수 있어야 합니다. - `explain(commit)`은 실행, 리스, 게이트 결정, 읽기 매니페스트에 대한 참조를 반환해야 합니다. - 기록의 보존은 내용의 삭제와 독립적이어야 합니다. ## 빌려 온 것과 새로운 것 아래에 나오는 것은 모두 이미 자리 잡은 부품입니다. **새로운 것은 읽기 매니페스트입니다.** “읽기”를 추적할 수 있는 입력의 집합으로 만들어, “오염된 병합”과 “오염된 메모리”를 사후에 조사할 수 있게 합니다. - [OpenTelemetry GenAI conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) - [Certificate Transparency](https://certificate.transparency.dev) - [Sigstore Rekor](https://docs.sigstore.dev/logging/overview/) - [Git trailers](https://git-scm.com/docs/git-interpret-trailers) ## 솔직한 한계 - 외부 앵커링이 없으면 root 권한을 가진 관리자는 여전히 로그를 파괴할 수 있습니다. - 기록 자체에도 민감한 메타데이터가 있으므로 통제해야 합니다. - 읽기 매니페스트의 입도는 저장 비용과 추적 가능성 사이의 절충입니다. ## 열린 질문 - 높은 처리량에서 읽기 매니페스트의 저장 비용을 어떻게 통제하는가? - 여러 노드의 기록을 어떻게 병합하고 검증하는가? ## 자주 묻는 질문 ### 에이전트가 읽은 내용도 기록하나요? 기본적으로는 기록하지 않습니다. 기록에는 경로, 커밋, 범위, 콘텐츠 해시가 들어갑니다. 민감한 내용을 로그에 복사하지 않고도 원본 데이터를 가리키기에 충분합니다. 내용은 Store에 남아 리스와 라벨로 보호됩니다. ### 여기서 “변조 증거(tamper-evident)”란 무슨 뜻인가요? **변조를 탐지할 수 있다**는 것만 약속합니다. 기록은 해시로 연결되어 있어 하나를 바꾸면 체인 검증이 깨집니다. 외부 앵커링(두 번째 노드나 오브젝트 잠금이 있는 버킷)이 있으면 root 권한을 가진 관리자에게도 견딥니다. 앵커링이 없으면 관리자는 여전히 로그 전체를 파괴할 수 있습니다. ### 왜 읽기를 기록하나요? 위험은 흔히 읽기에서 오기 때문입니다. 웹 페이지를 읽은 세션이 그 뒤에 오염된 노트를 쓸 수 있습니다. 읽기 매니페스트가 있으면 나중에 “무엇이 이 변경에 영향을 줬는가?”에 답할 수 있습니다. ## 관련 개념 - [Capability Lease (권한 리스)](https://agentnas.com/ko/concepts/capability-lease/): 한 번의 실행을 위한 좁은 인가. 만료 시점과 예산이 있고, 하위 리스는 더 좁아지기만 합니다. - [Trust Labels (신뢰 라벨)](https://agentnas.com/ko/concepts/trust-labels/): 작은 라벨 두 개와 세션 오염으로 Rule of Two를 강제합니다. - [Cascade Forget (연쇄 망각)](https://agentnas.com/ko/concepts/cascade-forget/): 계보를 따라 파생물을 삭제하고, 이력은 보존 등급으로 다루며, 하지 못한 일을 보고합니다. --- 표준 URL: https://agentnas.com/ko/concepts/flight-recorder/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Capability Lease (권한 리스) *한 번의 실행을 위한 좁은 인가. 만료 시점과 예산이 있고, 하위 리스는 더 좁아지기만 합니다.* > **Capability Lease**는 특정 데이터와 특정 작업에 대한 인가이며, 명시적인 만료 시점과 예산이 있습니다. **하나의 실행**에 발급되고, 실행이 NAS에 닿는 유일한 길입니다. 하위 리스는 상위 리스보다 좁아지기만 할 수 있습니다. **AN-04** · 적합성 수준: L1 Authority · 그룹: 권한 ## 해결하려는 문제 RBAC와 ACL은 넓고 오래가는 권한을 가진 안정적인 사용자를 가정합니다. 에이전트에게 필요한 것은 작업에 맞게 잘라 낸 권한, 작업이 끝나면 멈추는 권한입니다. 더 나쁜 것은 장기 자격 증명이 에이전트의 손이 닿는 곳에 놓여 있는 경우가 많다는 점입니다. 2026년 4월의 사고에서 토큰은 관계없는 파일에 있었고, 도메인을 관리하려고 만들었는데 무엇이든 할 수 있었습니다. ## 동작 방식 - **누가 열쇠를 쥐는가.** 장기 자격 증명은 오케스트레이터나 소유자에게 남고, 실행은 열쇠가 아니라 리스를 받습니다. 모델은 장기 자격 증명을 결코 보지 못합니다. - **리스는 액세스 토큰입니다.** `authorization_details`([RFC 9396](https://www.rfc-editor.org/rfc/rfc9396))가 경로, 동작, 브랜치를 기술하고, 소유자나 오케스트레이터가 [토큰 교환(RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693)으로 요청하며, `act` 클레임이 위임 체인을 기록하고, NAS는 취소와 예산 계산을 위한 상태를 보관합니다. - **좁아지기만 합니다.** 하위 리스는 상위 리스의 부분집합이어야 하며, 발급할 때 NAS가 이를 검사합니다. - **예산.** 읽고 쓴 바이트 수, 요청 수, 선택적으로 외부 전송 바이트 수와 지출 상한을 게이트웨이에서 셉니다. 정확한 과금이 아니라 **서킷 브레이커**입니다. - **정책 범위.** 소유자가 미리 범위를 정해 두면 그 안의 리스는 자동으로 발급되고, 밖의 것은 [Human Gate](https://agentnas.com/ko/concepts/human-gate/)로 갑니다. 장기 접근은 장기 리스가 아니라 범위로 표현합니다. - **B와 C는 명시적으로 선언합니다.** 리스는 읽을 수 있는 가장 높은 민감도와, 보호된 트리에 쓰거나 데이터를 내보낼 수 있는지를 밝힙니다. 이것이 [Trust Labels](https://agentnas.com/ko/concepts/trust-labels/)의 입력입니다. - **취소.** 짧은 TTL(기본 4시간, 최대 24시간)과 즉시 취소. 취소는 하위 리스로 연쇄됩니다. - **`purpose`는 기록하되 강제하지 않습니다.** 자유 형식 텍스트는 기계가 검사할 수 없기 때문입니다. ## 작게 시작하기 - `nas lease create` 명령을 하나 만듭니다. 역할마다 경로 접두사, 동작, TTL이 담긴 토큰을 발급해 환경 변수로 샌드박스에 넘기고, NAS가 접두사와 동작을 강제하게 합니다. - 이것만으로도 그런 사고의 앞 절반은 막습니다. 토큰은 리스 밖에서는 아무것도 할 수 없습니다. - 예산, 위임 체인, 정책 범위는 나중에 더해도 됩니다. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *lease.json* ```json { "lease_id": "lse_7Qk3", "run": "run_91ab", "principal": "agt_cleo", "on_behalf_of": "usr_wei", "parent": null, "purpose": "Draft the Q4 release notes", "paths": ["/shared/launch/**", "/agents/cleo/workspace/**"], "actions": ["read", "write", "propose"], "branch": "cleo/run_91ab", "sensitivity_max": "private", "egress": false, "requires_gate": ["merge", "delete", "share"], "budgets": { "bytes_read": 200000000, "bytes_written": 5000000, "requests": 5000 }, "expires_at": "2026-11-12T16:00:00Z" } ``` ## 명세가 요구하는 것 - 리스에는 만료 시점이 있어야 하며 최대 TTL을 넘겨 갱신해서는 안 됩니다. 갱신하려면 새로 발급받아야 합니다. - 하위 리스는 상위 리스의 부분집합이어야 하며, NAS가 발급할 때 이를 검증해야 합니다. - 리스를 취소하면 모든 하위 리스로 연쇄되어야 합니다. - 장기 접근은 정책 범위로 표현해야 하며, 장기 리스로 만들어서는 안 됩니다. - 리스는 자신의 민감도 상한과, 외부 전송과 보호된 쓰기를 허용하는지 여부를 선언해야 합니다. - 장기 자격 증명을 모델이나 실행에 노출해서는 안 됩니다. ## 빌려 온 것과 새로운 것 아래에 나오는 것은 모두 이미 자리 잡은 부품입니다. **새로운 것은** **실행과 작업의 형태**를 단위로 삼아 브랜치, 예산, Rule of Two 속성을 하나의 리스에 담은 것입니다. 토큰과 케이퍼빌리티 모델 자체는 새롭지 않습니다. - [OAuth Token Exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693) - [OAuth Rich Authorization Requests (RFC 9396)](https://www.rfc-editor.org/rfc/rfc9396) - [Biscuit](https://github.com/biscuit-auth/biscuit) - [UCAN](https://ucan.xyz/specification/) - [IETF attenuating agent tokens draft](https://datatracker.ietf.org/doc/draft-niyikiza-oauth-attenuating-agent-tokens/) ## 솔직한 한계 - NAS 안의 작업만 다루며, 에이전트가 다른 곳에서 하는 일은 통제할 수 없습니다. - `purpose`는 강제할 수 없고, 예산은 대략적입니다. - 리스는 **정당한 권한 안에서의** 오용을 막지 못합니다. 그것은 브랜치와 게이트의 일입니다. ## 열린 질문 - `purpose`를 자유 형식 텍스트에서 기계가 검사할 수 있는 구조화된 의도로 어떻게 옮길 수 있는가? - 연합 환경에서 예산은 어떻게 계산하는가? ## 자주 묻는 질문 ### 리스는 API 키와 무엇이 다른가요? API 키는 오래가는 공유 비밀이고, 가진 사람은 계정이 할 수 있는 일을 무엇이든 할 수 있습니다. 리스는 하나의 실행에 묶여 있고, 경로, 동작, 시간을 제한하며, 좁아지기만 할 수 있습니다. 만료되면 멈추고 언제든 취소할 수 있습니다. ### 그냥 OAuth를 쓰면 안 되나요? OAuth가 맞습니다. 리스는 액세스 토큰이며, 토큰 교환(RFC 8693)으로 요청하고 Rich Authorization Requests(RFC 9396)로 기술합니다. Agent NAS가 더하는 것은 OAuth가 정하지 않은 부분뿐입니다. 실행을 단위로 삼고, 브랜치, 예산, Rule of Two 속성을 하나의 인가에 담는 것입니다. ### 리스가 만료되면 실행은 어떻게 되나요? 마운트는 읽기 전용이 되었다가 해제되고, 새 요청은 거부되어 기록됩니다. 브랜치는 자체 TTL이 끝날 때까지 유지되므로, 끝낸 작업은 사라지지 않고 검토를 거쳐 병합할 수 있습니다. ## 관련 개념 - [Human Gate (사람 승인 게이트)](https://agentnas.com/ko/concepts/human-gate/): 되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는 동작 앞에만 나타나며, 실제 diff를 보여 줍니다. - [Trust Labels (신뢰 라벨)](https://agentnas.com/ko/concepts/trust-labels/): 작은 라벨 두 개와 세션 오염으로 Rule of Two를 강제합니다. - [Flight Recorder (플라이트 레코더)](https://agentnas.com/ko/concepts/flight-recorder/): 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록. --- 표준 URL: https://agentnas.com/ko/concepts/capability-lease/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Human Gate (사람 승인 게이트) *되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는 동작 앞에만 나타나며, 실제 diff를 보여 줍니다.* > **Human Gate**는 정책이 일으키는 검문소입니다. **되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는** 동작이 효력을 내기 전에, 사람(또는 지정된 승인자)이 완전히 렌더링된 구체적인 동작 하나를 승인합니다. 드물고, 구체적이며, 형식적으로 승인하기 어렵게 설계되어 있습니다. **AN-05** · 적합성 수준: L1 Authority · 그룹: 권한 ## 해결하려는 문제 오늘날의 “human in the loop”는 끝없는 프롬프트의 연속이거나 아예 없습니다. Anthropic에 따르면 Claude Code 사용자는 권한 요청의 93~97%를 승인합니다. 통제된 실험에서 사람이 잡아낸 것은 심어 둔 위험한 명령의 13.6%뿐이었고, 세션이 길어질수록 더 나빠졌습니다. 이것은 자동 모드를 홍보하려는 업체의 연구이며 실제 사고율이 아니라 심어 둔 요청을 알아채는 정도를 측정한 것이지만, 방향은 분명합니다. 같은 데이터에는 또 다른 숫자가 있습니다. 사용자는 계획의 39%를 거부하지만 개별 권한 요청은 3%만 거부합니다. 사람이 진지하게 판단하는 것은 모든 도구 호출이 아니라 계획과 병합입니다. ## 동작 방식 - **나타나는 곳은 적습니다.** 보호된 트리로의 병합, 보호된 트리에서의 삭제, 외부 공유나 게시, 외부 전송, 리스 확대, 라벨 낮추기. 브랜치에 쓰는 것은 승인이 필요 없습니다. - **입도는 계획이나 병합입니다.** 프롬프트 쉰 개가 아니라 PR 하나를 검토합니다. - **Gate Card는 NAS가 렌더링합니다.** 실제 diff, 읽기 매니페스트 요약, 리스와 세션 오염을 보여 주며, 에이전트 자신의 설명은 절대 쓰지 않습니다. 선택지는 승인, 좁혀서 승인, 거부이며, 시간이 지나면 기본값은 거부입니다. - **승인은 동작 다이제스트에 묶입니다.** diff 해시와 리스에 묶이므로 재생할 수 없습니다. - **전달 방법:** 푸시, 채팅, 이메일, CLI. 위임할 수 있고, 패스키는 선택적인 강한 인증입니다. - **승급만 합니다.** 선택적인 위험 분류기(LLM 포함)는 동작을 게이트로 **승급**시킬 수만 있고 **승인**은 결코 할 수 없습니다. 모델은 조이기만 할 뿐 풀 수는 없습니다. - **피로를 측정합니다.** 승인율과 승인까지 걸린 시간. 승인율이 이례적으로 높으면 게이트를 합치거나 정책을 조이라는 신호입니다. ## 작게 시작하기 - 보호된 main과 PR 검토(어떤 Git 플랫폼이든 됩니다), 그리고 푸시 알림. - 아니면 CLI: `nas gate approve `. - Gate Card에 “실제 diff”를 먼저 보여 주세요. 화려한 인터페이스부터 서두르지 마세요. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *gate-card.json* ```json { "gate_id": "gt_2Mx4", "run": "run_91ab", "action": { "op": "merge", "from": "cleo/run_91ab", "into": "main", "files_changed": 4, "diff_sha256": "7d2a..." }, "why": "Release notes are ready for review", "risk": { "session_taint": ["external"], "sources": ["web:example.com/changelog"], "destructive": false, "egress": false }, "options": ["approve", "approve_narrowed", "deny"], "default": "deny", "expires_at": "2026-11-12T12:00:00Z" } ``` ## 명세가 요구하는 것 - Gate Card는 NAS가 계산한 실제 diff를 보여 주어야 하며, 에이전트의 설명을 보여 줘서는 안 됩니다. - 승인은 동작 다이제스트와 리스에 묶여야 하며 재생할 수 없어야 합니다. - 시간 초과의 기본 결과는 거부여야 합니다. - 분류기나 LLM은 승인을 줄 수 없습니다. 동작을 게이트로 승급시키는 것은 할 수 있습니다. - 보호된 트리로의 병합, 보호된 트리에서의 삭제, 외부 공유, 외부 전송, 리스 확대, 라벨 낮추기는 게이트를 거쳐야 합니다. - NAS는 승인율과 승인까지 걸린 시간을 보고하는 것이 좋습니다. ## 빌려 온 것과 새로운 것 아래에 나오는 것은 모두 이미 자리 잡은 관행입니다. **새로운 것은** 승인의 닻을 **스토리지 계층의 병합**에 두고, 내용을 에이전트가 아니라 NAS가 렌더링하게 한 것입니다. 승인과 PR 자체는 새롭지 않습니다. - [How we built Claude Code auto mode](https://www.anthropic.com/research/claude-code-auto-mode) - [Anthropic: approval data behind auto mode](https://claude.com/resources/articles/auto-mode-default-in-claude-code) - [CaMeL](https://arxiv.org/abs/2503.18813) - [WebAuthn](https://www.w3.org/TR/webauthn-3/) - [OpenID CIBA](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html) ## 솔직한 한계 - 사람은 여전히 잘못된 동작을 승인할 수 있고, 일괄 검토도 피로를 낳습니다. - 알림 채널은 피싱당할 수 있습니다. - 승인은 **승인된 범위 밖**의 일을 막지 못합니다. 그것은 리스의 일입니다. ## 열린 질문 - 일괄 검토와 단계별 검토에 가장 알맞은 인터페이스는 무엇인가? - 자동 병합의 임곗값은 어떻게 측정하고 조정하는가? ## 자주 묻는 질문 ### 그냥 또 하나의 “확인” 대화 상자 아닌가요? 일부러 그렇지 않게 만들었습니다. 대화 상자는 도구를 호출할 때마다 뜨고, 사람은 금방 “승인”만 누르게 됩니다. 게이트는 되돌릴 수 없거나 외부로 나가는 몇 가지 동작 앞에서만 나타나고, NAS가 계산한 실제 diff를 보여 주며, 승인은 diff 해시에 묶입니다. diff가 바뀌면 승인은 무효가 됩니다. ### LLM이 통과시킬지 판단해도 되나요? “사람이 이 단계를 봐야 한다”고 제안할 수는 있어도 승인할 수는 없습니다. 통과시키는 결정은 결정론적인 규칙이나 사람의 승인이어야 합니다. 그래야 보안이 특정 모델의 판단에 의존하지 않습니다. ### 시간이 초과되면 어떻게 되나요? 기본값은 거부입니다. 실행은 분명한 거부를 받고, 다른 길을 택하거나, 제안을 브랜치에 남겨 두어 사람이 처리하게 할 수 있습니다. ## 관련 개념 - [Capability Lease (권한 리스)](https://agentnas.com/ko/concepts/capability-lease/): 한 번의 실행을 위한 좁은 인가. 만료 시점과 예산이 있고, 하위 리스는 더 좁아지기만 합니다. - [Trust Labels (신뢰 라벨)](https://agentnas.com/ko/concepts/trust-labels/): 작은 라벨 두 개와 세션 오염으로 Rule of Two를 강제합니다. - [Agent Branch (에이전트 브랜치)](https://agentnas.com/ko/concepts/agent-branch/): 실행마다 쓰기 시 복사(copy-on-write) 브랜치에서 일합니다. 메인 라인에 닿는 것은 검토를 거친 병합뿐입니다. --- 표준 URL: https://agentnas.com/ko/concepts/human-gate/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Trust Labels (신뢰 라벨) *작은 라벨 두 개와 세션 오염으로 Rule of Two를 강제합니다.* > **Trust Labels**는 데이터에 붙는 아주 작은 라벨 집합 두 개, **출처**(`owner`, `agent`, `external`)와 **민감도**(`public`, `private`, `secret`), 그리고 **세션 오염**입니다. NAS는 Rule of Two를 세션 불변식으로 강제합니다. 한 세션이 [A] 외부 콘텐츠를 읽었고, [B] 민감한 데이터를 건드리고, [C] 보호된 상태를 바꾸거나 외부와 통신하는 세 가지를 모두 가질 수는 없습니다. 세 번째를 완성하려면 [Human Gate](https://agentnas.com/ko/concepts/human-gate/)가 필요합니다. **AN-06** · 적합성 수준: L3 Guard · 그룹: 권한 ## 해결하려는 문제 프롬프트 인젝션이 통하는 이유는 모델이 “지시”와 “데이터”를 구별하지 못하기 때문입니다. 모델 계층의 방어(분류기, 프롬프트 강화)는 샐 수밖에 없고, 공격자는 적응할 수 있습니다. 2025년 10월 말 Meta는 [Agents Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/)를 제안했습니다. 인젝션이 확실히 해결되기 전까지 한 세션은 세 가지 속성 중 최대 두 가지만 가져야 한다는 것입니다. 더 믿을 만한 방법은 모델 **바깥**에서 결과를 제한하는 것입니다. 스토리지는 모든 읽기와 쓰기가 지나가는 바로 그 자리이므로, 이 규칙을 검증할 수 있는 불변식으로 바꾸기에 자연스러운 곳입니다. ## 동작 방식 - **라벨.** 세 가지 출처, 세 가지 민감도, 그리고 `reviewed` 플래그(게이트 승인으로 설정). 가져오는 지점(웹 페이지, 이메일, 업로드)은 기본이 `external`입니다. 시크릿 스캐너가 자격 증명을 찾으면 자동으로 `secret` 라벨을 붙입니다. - **세션 오염.** 실행이 읽은 모든 것(읽기 매니페스트에서)의 요약입니다. 세션 안에서는 늘어나기만 하고, 새 세션은 깨끗하게 시작합니다. - **불변식.** A = 세션이 `external`을 읽었다. B = 리스가 `private` 이상을 읽을 수 있다(임곗값은 설정 가능). C = 리스가 보호된 트리로의 병합을 제안하거나, 공유, 삭제, 데이터 전송을 할 수 있다. 한 세션에서 셋이 모두 성립하면 C를 일으키는 호출은 거부되거나 게이트로 넘어갑니다. - **실제로는:** B와 C를 모두 가진 리스에서 세션이 외부 콘텐츠를 한 번 읽으면, 그 뒤의 모든 C 유형 동작에는 사람이 필요합니다. 이 마찰을 피하려면 “외부 콘텐츠를 읽는” 작업을 B가 없는 별도의 세션에서 하고, 결과는 구조화된 인계로만 넘기세요. - **전파.** NAS 자체가 만드는 파생물(인덱스, 요약)은 입력 라벨의 합집합을 결정론적으로 물려받습니다. 실행이 쓰는 파일은 실행의 세션 오염을 물려받습니다(보수적인 선택). - **기밀 해제.** Human Gate를 거치거나 **구조화된 인계**를 통해서만 가능합니다. 오염된 세션의 출력을 JSON Schema로 검증되는 필드(열거형, ID, 길이가 제한된 문자열)로 한정하고, 검증을 마친 뒤에야 권한 있는 세션이 읽을 수 있습니다. 결정론적으로 검증할 수 있는 것만 믿을 수 있습니다. - **강제는 게이트웨이와 마운트에서 합니다.** 이 둘은 리스와 세션을 알고 있습니다. 모델 안에서가 아닙니다. ## 작게 시작하기 - 딱 두 가지만 합니다. 가져오기 디렉터리의 파일에 `external` 라벨을 붙이고, `external`을 읽은 실행에는 기본적으로 외부 전송을 주지 않고 게이트 없이는 보호된 병합도 허용하지 않습니다. - 정책은 Cedar나 Rego의 결정론적 규칙으로 쓰고, 거부할 때는 읽을 수 있는 이유를 제시합니다. - 일주일 동안 “기록만 하는” 모드로 돌려 실수로 무엇을 막았을지 확인한 뒤 강제를 켭니다. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *policy.yaml* ```yaml # Deterministic policy (Cedar- or Rego-style rules can express the same thing) session_invariant: rule_of_two properties: A: session.read_origin includes "external" B: lease.sensitivity_max >= "private" C: lease allows propose_protected | share | delete | egress on_would_complete_ABC: gate # never "allow" rules: - id: r-merge-1 when: session.A and op == "merge" and target.protected then: gate - id: r-secret-1 when: session.read_sensitivity == "secret" and op == "egress" then: deny ``` ## 명세가 요구하는 것 - 가져오는 지점마다 기본 라벨을 지정해야 하며, 외부 콘텐츠에는 `external` 라벨을 붙여야 합니다. - 세션 오염은 세션 안에서 늘어나기만 해야 합니다. - 정책 평가는 결정론적이어야 하며 LLM을 호출해서는 안 됩니다. - 세션이 A+B+C를 완성하게 되는 호출은 거부하거나 게이트로 보내야 합니다. - 기밀 해제는 게이트나 스키마로 검증된 구조화된 인계를 거쳐야 합니다. - 파생 데이터는 입력 라벨의 합집합을 물려받아야 합니다. ## 빌려 온 것과 새로운 것 아래에 나오는 것은 모두 이미 자리 잡은 생각입니다. **새로운 것은** 읽기 매니페스트로 세션 오염을 **스토리지 경계**에서 구현하고, 라벨을 메모리 쓰기와 파생 데이터에 적용한 것입니다. 라벨 격자는 일부러 3×3으로 유지합니다. 세밀한 격자는 실제로 라벨 폭발로 이어지기 때문입니다. OpenClaw는 이미 하나의 런타임 안에서 출처 라벨과 격리를 하고 있습니다. 우리의 차이는 이것을 공유 스토리지에 둔다는 점뿐입니다. - [Agents Rule of Two (Meta)](https://ai.meta.com/blog/practical-ai-agent-security/) - [The lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/) - [CaMeL](https://arxiv.org/abs/2503.18813) - [Fides](https://arxiv.org/abs/2505.23643) - [Design Patterns for Securing LLM Agents against Prompt Injections](https://arxiv.org/abs/2506.08837) - [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture) ## 솔직한 한계 - 프롬프트 인젝션에 대한 방어가 **아니며**, 결과를 제한할 뿐입니다. - NAS는 바깥의 도구(브라우저, 이메일)를 볼 수 없으므로 런타임의 협조가 필요합니다. - 오염 표시는 보수적이어서 마찰과 오탐을 낳습니다. 구조화된 스키마 밖의 자유 형식 텍스트에는 여전히 공격자의 말이 실릴 수 있습니다. - 은닉 채널은 없앨 수 없습니다. ## 열린 질문 - 라벨의 입도는 파일이어야 하는가, 문단이어야 하는가? - 테넌트를 넘나드는 라벨 어휘는 어떻게 거버넌스하는가? - 오탐은 어떻게 줄일 수 있는가? ## 자주 묻는 질문 ### Rule of Two가 프롬프트 인젝션을 막아 주나요? 인젝션이 일어나는 것은 막지 못합니다. 인젝션을 당한 세션이 “신뢰할 수 없는 콘텐츠를 읽었고, 민감한 데이터를 건드리고, 보호된 상태를 바꾸거나 데이터를 내보낼 수 있다”는 **세 가지를 모두 가질 수 없게** 해서 결과를 제한합니다. Meta 스스로도 이것은 위험을 줄이는 경험칙이며 최소 권한을 대체하지 않는다고 강조합니다. ### 왜 출처와 민감도가 각각 세 가지뿐인가요? 세밀한 라벨 격자는 부풀기 쉽고 실제로는 꺼지는 경우가 많기 때문입니다. 3×3이면 “누가 썼고 얼마나 민감한가”를 말하기에 충분하고, 거부 이유도 이해하기 쉽습니다. 더 세밀한 구분은 경로와 리스로 할 수 있습니다. ### 세션 오염 때문에 에이전트가 아무것도 못 하게 되지는 않나요? 세 가지 동작만 제한합니다. 보호된 트리 변경, 공유와 삭제, 데이터 전송입니다. 브랜치 안에서의 읽기와 쓰기는 영향을 받지 않습니다. 마찰을 피하려면 외부 콘텐츠를 읽는 작업을 민감한 데이터가 없는 세션에서 하고, 스키마로 검증된 결과만 돌려받으세요. ## 관련 개념 - [Human Gate (사람 승인 게이트)](https://agentnas.com/ko/concepts/human-gate/): 되돌릴 수 없거나, 외부로 나가거나, 권한을 높이는 동작 앞에만 나타나며, 실제 diff를 보여 줍니다. - [Agent Memory (에이전트 메모리)](https://agentnas.com/ko/concepts/agent-memory/): 읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다. - [Capability Lease (권한 리스)](https://agentnas.com/ko/concepts/capability-lease/): 한 번의 실행을 위한 좁은 인가. 만료 시점과 예산이 있고, 하위 리스는 더 좁아지기만 합니다. --- 표준 URL: https://agentnas.com/ko/concepts/trust-labels/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Agent Memory (에이전트 메모리) *읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다.* > **Agent Memory** = **읽고 고칠 수 있는 노트** + **언제든 버려도 되는 인덱스**입니다. 모든 노트는 출처를 밝히고, 인덱스(전문 검색, 벡터, 그래프, 개요)는 노트의 파생물일 뿐이며, 백그라운드 유지 관리 작업은 수정을 **제안**만 할 뿐 원본 저널을 고쳐 쓰지 않습니다. **AN-07** · 적합성 수준: L2 Memory · 그룹: 지식 ## 해결하려는 문제 메모리 프레임워크는 메모리를 불투명한 데이터베이스에 넣습니다. 들여다보거나, diff를 보거나, 옮기거나, 고칠 수 없고, 확실히 지우기도 어렵고, 인덱스와 임베딩 모델에 묶입니다. 게다가 메모리 자체가 공격 표면입니다. 한 [2026년 연구](https://arxiv.org/abs/2606.04329)에서 영속 메모리 오염은 두 에이전트에서 평균 50.46%의 공격 성공률에 이르렀고, [또 다른 연구](https://arxiv.org/abs/2607.05189)는 정교하게 만든 이메일 한 통으로 파일 시스템 백엔드와 벡터 메모리 백엔드 모두를 공략하는 데 성공했습니다. 한편 “어떤 메모리 아키텍처가 가장 좋은가”는 전혀 결론이 나지 않았습니다. 벤치마크끼리 서로 모순됩니다. 특정 검색 알고리즘에 걸지 않는 설계만이 3년의 변화를 견딜 수 있습니다. ## 동작 방식 - **노트가 진실입니다.** YAML 프런트매터가 있는 Markdown: `kind`(episodic, semantic, procedural, preference), `subject`, `sources`, `confidence`, `valid_from`, `valid_to`, `supersedes`, `origin`, `reviewed`. - **덮어쓰지 말고 갱신하세요.** 새로운 사실은 옛 사실을 `supersedes`합니다. 유효 시간과 기록 시간은 따로 둡니다. 사실은 변하는데 흔한 벤치마크는 그것을 거의 시험하지 않기 때문입니다. - **인덱스는 캐시입니다.** BM25(예: SQLite FTS5), 벡터(여러 개가 공존할 수 있음), 선택적인 그래프. 모든 파생물은 자신의 **레시피**와 **입력**을 지닙니다. 임베딩 모델을 바꾸는 것은 백그라운드 재계산이며, 새 인덱스가 기준 불러오기 테스트를 통과할 때까지 옛 인덱스는 유지됩니다. - **두 종류의 파생.** 결정론적인 것(청킹, BM25, 고정된 모델의 임베딩)은 재현할 수 있고, 생성형인 것(LLM 요약, 추출된 사실)은 “다시 생성해 비교”할 수밖에 없으므로 `generated: true`로 표시하고 유일한 사본으로 쓰지 않습니다. - **쓰기 경로.** `nas_remember`는 (출처와 함께) 노트를 현재 브랜치에 쓰고, 오염은 상속됩니다. `external` 오염이 있는 세션의 노트는 검토되지 않음으로 표시되어 **격리**에 들어갑니다. 불러올 수는 있지만 **자동으로 로드되지 않고** `MEMORY.md`에도 들어가지 않습니다. - **읽기 경로.** `nas_recall` = 검색, 후보, 예산 뷰와 증거 포인터. 각 노트의 출처와 검토 상태를 보여 줍니다. - **유지 관리 작업**(밤새 또는 한가할 때): 중복 제거, 에피소드를 의미 사실로 통합, 모순 표시, 낡은 사실 폐기, 인덱스 재구축. 작업은 브랜치에 제안을 만들어 사람이나 에이전트가 검토하게 하며, **원본 저널은 절대 지우지 않습니다.** “후회율”(롤백되는 제안의 비율)을 측정합니다. - **기준 불러오기 테스트(golden recall).** 홈마다 “질문, 기대하는 노트” 쌍의 집합을 두고, 모델이나 인덱서가 바뀔 때 자동으로 실행합니다. ## 작게 시작하기 - 프런트매터가 있는 `memory/notes/*.md`와 검색용 SQLite FTS5. - CI에서 기준 질문 열 개를 실행합니다. - 벡터 인덱스와 유지 관리 작업은 나중에 더해도 됩니다. “출처”와 “검토된 노트만 자동 로드”를 먼저 제대로 하세요. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *memory/notes/customer-acme.md* ```markdown --- id: mem_4kq2 kind: semantic subject: customer/acme valid_from: 2026-10-02 valid_to: null confidence: 0.8 origin: agent reviewed: true sources: - nas://home-box/agents/cleo/journal/2026-10-02.md@9f2c1de#L12-L18 supersedes: [mem_1xa9] --- Acme renewed for 24 months; the champion moved from Dana to Luis. ``` ## 명세가 요구하는 것 - 노트는 Memory 계층 없이도 읽을 수 있어야 합니다(Store에 있는 평범한 파일). - 모든 파생물은 레시피와 입력을 지녀야 하며, 인덱스는 버릴 수 있고 다시 만들 수 있어야 합니다. - 오염된 세션이 쓴 노트는 검토되기 전에는 자동으로 로드되어서는 안 됩니다. - 새로운 사실은 덮어쓰지 않고 `supersedes`로 옛 사실을 대체해야 합니다. - 유지 관리 작업은 브랜치에서 일하며 제안만 해야 하고, 원본 저널을 지워서는 안 됩니다. - 모든 홈에는 기준 불러오기 테스트를 두고, 모델이나 인덱서가 바뀔 때마다 실행하는 것이 좋습니다. ## 빌려 온 것과 새로운 것 아래에 나오는 것은 모두 이미 자리 잡은 생각이며, OpenClaw의 메모리 아키텍처는 이미 출처 라벨, 계층별 격리, 통합 과정에서의 오염 전파를 하고 있습니다. **새로운 것은** OpenClaw가 이것을 **하나의 런타임 안에서** 하는 반면, 우리는 **공유 스토리지에서** 해서 어떤 런타임이든 혜택을 받게 하자고 제안하는 것, 그리고 인덱스를 버려도 되는 캐시로 강등해 메모리를 잃지 않고 검색 알고리즘을 바꿀 수 있게 하는 것입니다. - [Letta Context Repositories](https://www.letta.com/blog/context-repositories/) - [Letta: is a filesystem all you need?](https://www.letta.com/blog/benchmarking-ai-agent-memory/) - [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture) - [Long-term memory security survey](https://arxiv.org/abs/2604.16548) - [Graphiti](https://github.com/getzep/graphiti) - [MemGPT](https://arxiv.org/abs/2310.08560) ## 솔직한 한계 - 생성형 파생물은 비트 단위로 똑같이 재현할 수 없습니다. - 유지 관리 작업은 실수를 사실로 “굳힐” 수 있습니다. 그래서 제안만 하고 직접 고치지 않습니다. - 어떤 메모리 아키텍처가 가장 좋은지는 아직 결론이 나지 않았습니다. ## 열린 질문 - 에이전트가 직접 메모리를 써야 할 때는 언제이고, 유지 관리 작업이 써야 할 때는 언제인가? - 모델 버전을 넘나드는 회귀 기준은 무엇인가? ## 자주 묻는 질문 ### 왜 벡터 데이터베이스가 아니라 파일인가요? 파일은 읽고, 고치고, diff를 보고, 가지고 나갈 수 있는 진실입니다. 벡터 인덱스는 여러 버전이 공존할 수 있고 언제든 다시 만들 수 있는 파생 캐시입니다. Letta의 벤치마크는 `grep`과 파일 도구만 가진 에이전트도 충분히 경쟁력이 있음을 보여 주었지만 벤치마크끼리 서로 모순되므로, 이 설계는 특정 검색 알고리즘에 걸지 않습니다. ### 메모리 오염은 어떻게 막나요? 나쁜 것이 절대 쓰이지 않는다고 보장할 수는 없지만, 결과는 제한할 수 있습니다. 외부에서 온 콘텐츠에는 `external` 라벨이 붙고, 오염된 세션이 쓴 노트는 격리되어 자동으로 로드되지 않으며, 병합은 검토를 거치고, 문제가 생기면 출처 사슬을 따라 영향받은 노트까지 가서 롤백할 수 있습니다. ### 임베딩 모델을 바꾸면 메모리를 마이그레이션해야 하나요? 아닙니다. 노트는 그대로이고, 인덱스만 새 레시피로 백그라운드에서 다시 계산됩니다. 새 인덱스가 기준 불러오기 테스트를 통과할 때까지 옛 인덱스는 유지됩니다. ## 관련 개념 - [Budgeted Reads (예산 읽기)](https://agentnas.com/ko/concepts/budgeted-reads/): 파일을 개요, 섹션, 줄 범위, 전체로 읽되, 예산에 맞춰 단계적으로 낮춥니다. - [Cascade Forget (연쇄 망각)](https://agentnas.com/ko/concepts/cascade-forget/): 계보를 따라 파생물을 삭제하고, 이력은 보존 등급으로 다루며, 하지 못한 일을 보고합니다. - [Trust Labels (신뢰 라벨)](https://agentnas.com/ko/concepts/trust-labels/): 작은 라벨 두 개와 세션 오염으로 Rule of Two를 강제합니다. --- 표준 URL: https://agentnas.com/ko/concepts/agent-memory/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Budgeted Reads (예산 읽기) *파일을 개요, 섹션, 줄 범위, 전체로 읽되, 예산에 맞춰 단계적으로 낮춥니다.* > **Budgeted Reads**는 토큰 예산으로 재는 읽기입니다. 같은 파일을 개요, 섹션, 줄 범위, 전문까지 서로 다른 수준의 상세도로 읽을 수 있습니다. 에이전트는 “N토큰 안에 들어가는 가장 좋은 뷰”를 요청하고, 정확한 원본을 가리키는 증거 포인터를 돌려받습니다. **AN-08** · 적합성 수준: L2 Memory · 그룹: 지식 ## 해결하려는 문제 에이전트는 컨텍스트를 파일 전체와 반복되는 읽기에 소모하고, 순진한 RAG 청킹은 구조를 잃습니다. 모델은 이미 `grep`, `tail`, 줄 단위 읽기에 능합니다. Cursor는 너무 긴 도구 출력을 파일에 써서 에이전트가 필요할 때 읽게 하며, MCP 도구를 호출한 실행에서 도구 설명의 [동적 탐색](https://cursor.com/blog/dynamic-context-discovery)으로 전체 토큰을 46.9% 줄였습니다. 그래서 문제는 “또 하나의 검색 시스템을 만드는 것”이 아니라, 파일 위의 읽기에 **예산이 있고 검사할 수 있는** 계약을 주는 것입니다. ## 동작 방식 - **파일이 먼저입니다.** 표준 읽기(줄 범위 포함)는 항상 쓸 수 있으며, Budgeted Reads는 그 위의 선택적인 확장일 뿐 파일 시스템을 대체하지 않습니다. - **결정론적 개요(무료):** Markdown의 제목 트리, 코드 심볼(tree-sitter), JSON과 YAML의 키, CSV의 헤더와 행 수. LLM이 필요 없습니다. - **예산과 품질 저하.** 요청에는 `budget_tokens`가 담기며, 맞지 않으면 **조용히 잘라 내는 대신** 더 거친 뷰로 낮춥니다. 응답은 실제 뷰, 토큰 수, `generated` 여부를 밝힙니다. - **검색은 스니펫과 포인터를 돌려줍니다.** 파일 전체가 아닙니다. - **증거 포인터:** `nas:////@#L12-L18`. 안정적이며 커밋에 대해 검증할 수 있고, `dereference`는 정확한 내용을 돌려줍니다. - **지난번 이후 바뀐 것:** 파일 전체 대신 두 커밋 사이의 diff를 돌려줍니다. - **선택적인 LLM 요약 계층:** 캐시로서 `generated: true`와 오래됨 표시를 붙입니다. ## 작게 시작하기 - `nas_read` 말고는 아무것도 더하지 마세요. 에이전트가 `rg`와 `sed -n`으로 예전 방식대로 읽게 둡니다. - 그다음에 Markdown과 코드를 위한 작은 개요 도구를 더합니다. - 증거 포인터는 “path@commit#line”으로 시작하세요. 새 서비스는 필요 없습니다. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *POST /v1/files/read* ```http POST /v1/files/read { "path": "/agents/cleo/memory/notes/customer-acme.md", "view": "outline", "budget_tokens": 400 } 200 OK { "view": "outline", "tokens": 212, "generated": false, "truncated": false, "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)", "evidence": [ { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" } ] } ``` ## 명세가 요구하는 것 - 응답은 실제로 돌려준 뷰와 토큰 수를 밝혀야 하며, 생성형 뷰에는 표시를 해야 합니다. - 예산이 너무 작으면 NAS는 더 거친 뷰로 낮춰야 하며, 조용히 잘라 내서는 안 됩니다. - 표준 파일 읽기(범위 포함)는 계속 쓸 수 있어야 합니다. - 증거 포인터는 커밋에 대해 검증할 수 있어야 합니다. - 검색은 기본적으로 파일 전체가 아니라 스니펫과 포인터를 돌려주어야 합니다. ## 빌려 온 것과 새로운 것 점진적 공개와 grep은 그 자체로 새롭지 않습니다. **새로운 것은** 예산과 증거 포인터를 **스토리지 계층의 읽기 계약**으로 만들어 답을 검사할 수 있게 한 것입니다. 한 문장에서 출발해 그 근거가 된 커밋의 줄까지 되짚어 갈 수 있습니다. - [Cursor: dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery) - [Agent Skills (progressive disclosure)](https://agentskills.io/specification) - [Letta Context Repositories](https://www.letta.com/blog/context-repositories/) - [RAPTOR](https://arxiv.org/abs/2401.18059) ## 솔직한 한계 - 토크나이저는 모델마다 다르므로 토큰 수는 추정치입니다. - 클라이언트가 채택해야만 작동합니다. - 요약은 낡거나 틀릴 수 있으므로 캐시일 뿐이며 항상 표시합니다. ## 열린 질문 - 서로 다른 모델 토크나이저 사이의 예산 오차는 어떻게 다뤄야 하는가? - 요약의 품질은 어떻게 평가하는가? ## 자주 묻는 질문 ### RAG와는 어떻게 다른가요? RAG는 질문과 가장 가까운 스니펫을 돌려줍니다. Budgeted Reads는 이미 알고 있는 객체에 대해 독자가 상세도를 고르게 하고, 예산이 모자라면 정직하게 품질을 낮추며, 검증할 수 있는 포인터를 줍니다. 둘은 겹쳐 쓸 수 있습니다. 검색 결과도 예산 뷰로 돌려받을 수 있습니다. ### 파일을 읽으려면 꼭 써야 하나요? 아닙니다. 마운트와 Git은 언제나 평범한 파일을 줍니다. Budgeted Reads는 토큰에 신경 쓰는 에이전트를 위한 선택적인 읽기입니다. ### 증거 포인터가 “지어낸 인용”을 막아 주나요? 인용을 검사할 수 있게 합니다. 포인터는 한 커밋의 특정 줄을 가리키고 그 콘텐츠 해시를 검증할 수 있습니다. 모델이 무언가를 지어내는 것을 막지는 못하지만, “인용한 구절이 실제로 있는가?”를 기계가 검사할 수 있는 문제로 바꿉니다. ## 관련 개념 - [Agent Memory (에이전트 메모리)](https://agentnas.com/ko/concepts/agent-memory/): 읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다. - [Agent Home (에이전트 홈)](https://agentnas.com/ko/concepts/agent-home/): 역할마다 하나씩, 이력이 있는 디렉터리. 가지고 떠날 수 있는 평범한 파일. - [Flight Recorder (플라이트 레코더)](https://agentnas.com/ko/concepts/flight-recorder/): 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록. --- 표준 URL: https://agentnas.com/ko/concepts/budgeted-reads/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0 --- # Cascade Forget (연쇄 망각) *계보를 따라 파생물을 삭제하고, 이력은 보존 등급으로 다루며, 하지 못한 일을 보고합니다.* > **Cascade Forget**은 계보를 따라 지우는 삭제입니다. 원본이 삭제되거나 누군가 잊어 달라고 요청하면, NAS는 그 원본에서 파생된 모든 것(요약, 임베딩, 그것을 인용한 노트, 캐시, 공유 링크)을 찾아 지우거나 그 원본 없이 다시 파생하고, **보고서**를 발급합니다. 무엇을 했는지, 그리고 무엇을 할 수 없었는지. **AN-09** · 적합성 수준: L3 Guard · 그룹: 지식 ## 해결하려는 문제 파일을 지워도 그 임베딩, 요약, 메모리가 그것에서 추론한 사실은 지워지지 않습니다. 스냅샷과 백업은 남고, 내용은 버전 이력에도 남아 있습니다. “복구할 수 있음”과 “잊을 수 있음”은 하나의 축의 양 끝인데, 대부분의 시스템은 이 선택을 사람에게 넘기지 않습니다. 쓰고 난 뒤에야 망각을 생각하면 대개 너무 늦습니다. ## 동작 방식 - **계보.** 모든 파생물은 자신의 입력을 기록합니다. 역색인은 “X에 의존하는 모든 것”에 답하고, 노트의 `sources` 필드도 계보입니다. - **보존 등급은 쓰기 시점에 정합니다**(나중에는 이력을 다시 쓸 수 없기 때문). `scratch`(짧은 TTL, 백업에서 제외, 실행이 끝나면 정리 가능), `normal`(버전 관리됨, 복구 가능), `sensitive`(자체 키 도메인, 키를 파기하면 완전히 지울 수 있음). - **복구와 망각 사이의 긴장.** 소프트 삭제 기간 안에서는 복구할 수 있고, 그 뒤에야 완전히 삭제합니다. 망각 요청은 그 기간을 건너뛸 수 있습니다. - **절차.** 요청(사람이나 운영자가 제기하며 에이전트는 요청만 할 수 있고 실행은 못 함), 계보 순회, 파생물 삭제와 출처가 섞인 사실의 재파생, `normal` 등급에서는 영향받은 경로의 이력을 다시 쓰고 스냅샷을 정리, `sensitive` 등급에서는 키 파기, 마지막으로 보고서. - **보고서:** 삭제한 파일 수, 제거한 파생물 수, 이력을 다시 썼는지, 파기한 키, 아직 만료되지 않은 스냅샷, 그리고 **다루지 못하는 범위의 명시적 목록**(NAS 밖의 사본, 모델 제공자의 로그, 모델 가중치). - 항상 [Human Gate](https://agentnas.com/ko/concepts/human-gate/)(또는 사전 승인 정책)를 거치며, **법적 보존 조치**는 망각을 막고 기록됩니다. ## 작게 시작하기 - 보존 등급과 소프트 삭제로 시작하고, 모든 파생물의 입력을 기록하세요. - 먼저 “원본 파일을 삭제하면 그 파생물을 모두 나열하고 삭제한다”까지 도달하세요. - 암호학적 파기는 `sensitive` 등급을 위해 남겨 두세요. 처음부터 모든 곳에서 할 필요는 없습니다. ## 인터페이스 스케치 설명을 위한 예시입니다. 필드 이름은 명세 v0.3 이전에 바뀔 수 있습니다. *forget-report.json* ```json { "forget_id": "fgt_3b7c", "selector": { "paths": ["/shared/crm/acme/**"], "subject": "customer/acme" }, "retention_class": "sensitive", "report": { "files_removed": 142, "derived_removed": { "embeddings": 3621, "summaries": 210, "notes_rewritten": 6 }, "history": "rewritten (3 commits)", "keys_destroyed": ["key_acme"], "snapshots_pending": ["nightly-2026-11-10 (expires 2026-11-17)"], "not_covered": ["copies outside the NAS", "model provider logs", "model weights"] }, "state": "pending_expiry" } ``` ## 명세가 요구하는 것 - 망각은 원본에서 모든 파생물까지 계보를 따라 전파되어야 합니다. - 보존 등급은 쓰기 시점에 지정해야 합니다(기본은 `normal`). - 망각 보고서에는 다루지 못하는 범위를 적어야 합니다. NAS 밖의 사본, 제공자 로그, 모델 가중치. - 법적 보존 조치는 망각을 막아야 하며 기록해야 합니다. - 에이전트는 망각을 요청할 수는 있지만 실행해서는 안 됩니다. - 보고서는 모델이 무언가를 “잊었다”고 주장해서는 안 됩니다. ## 빌려 온 것과 새로운 것 아래에 나오는 것은 모두 이미 자리 잡은 것입니다. **새로운 것은** **보존 등급**을 스토리지의 명시적인 속성으로 다루고, “복구할 수 있음”과 “잊을 수 있음”이 하나의 축 위의 절충임을 인정하는 것입니다. - [OpenLineage](https://openlineage.io) - [GDPR Article 17](https://gdpr-info.eu/art-17-gdpr/) - [Long-term memory security survey (forget and rollback)](https://arxiv.org/abs/2604.16548) ## 솔직한 한계 - 백업, NAS 밖의 사본, 모델 제공자의 로그는 범위 밖입니다. - 여러 출처에서 추론한 사실은 “영향 범위”를 정의하기 어렵습니다. - 이력을 다시 쓰는 일은 비싸고 위험이 따릅니다. ## 열린 질문 - 출처가 섞인 사실의 영향 범위는 어떻게 정의하는가? - 법적 보존 조치가 망각 요청과 충돌할 때의 절차는 무엇이어야 하는가? ## 자주 묻는 질문 ### 모델이 잊게 만들 수 있나요? 아닙니다. 그렇게 주장하지도 않습니다. 할 수 있는 것은 NAS 안의 파일과 파생물, 그리고 `sensitive` 등급의 이력과 키를 삭제하는 것입니다. 모델 제공자의 로그와 모델 가중치는 범위 밖이며, 보고서에 그렇게 명시됩니다. ### 왜 쓰기 시점에 보존 등급을 고르나요? 나중에는 이력을 다시 쓰기 어렵기 때문입니다. 이미 백업과 이력에 들어간 것은 다시 쓰거나 만료되기를 기다리는 수밖에 없습니다. 쓰는 시점에 `scratch`, `normal`, `sensitive` 중 무엇인지 정해 두는 것이 나중에 깨끗하게 지울 수 있는 전제 조건입니다. ### 에이전트가 스스로 무언가를 잊겠다고 요청할 수 있나요? 요청은 할 수 있지만 실행은 못 합니다. 망각은 되돌릴 수 없으므로 사람이나 사전 승인 정책을 거쳐야 하며, 법적 보존 조치가 이를 막을 수 있습니다. ## 관련 개념 - [Agent Memory (에이전트 메모리)](https://agentnas.com/ko/concepts/agent-memory/): 읽고 고칠 수 있는 노트가 진실입니다. 인덱스는 버려도 되는 캐시입니다. - [Flight Recorder (플라이트 레코더)](https://agentnas.com/ko/concepts/flight-recorder/): 실행마다 하나, 해시로 연결되며 읽은 것까지 담는 기록. - [Agent Branch (에이전트 브랜치)](https://agentnas.com/ko/concepts/agent-branch/): 실행마다 쓰기 시 복사(copy-on-write) 브랜치에서 일합니다. 메인 라인에 닿는 것은 검토를 거친 병합뿐입니다. --- 표준 URL: https://agentnas.com/ko/concepts/cascade-forget/ 최종 수정: 2026-11-11 · 명세 초안 v0.2 · CC BY 4.0