# 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