LightVela 문서

요약

Hermes Agent의 파일은 한데 뒤섞인 폴더가 아니라, 책임이 뚜렷한 세 위치에 나뉩니다. 작업 디렉터리는 현재 작업의 입력·출력·도구 실행을 보관하며 명확한 경계가 있습니다. 도구는 작업 공간을 벗어나 임의의 시스템 경로로 이동할 수 없습니다. 컨텍스트 파일(SOUL.md, USER.md, MEMORY.md)은 일반 첨부 파일이 아니라 에이전트가 사용자와 작업을 이해하는 방식을 형성하는 장기 계약입니다. 클라우드 스토리지는 작업 자료와 출력을 보관하는 에이전트의 파일 작업 공간입니다. 파일 하나당 최대 1GB까지 업로드하고 다운로드할 수 있으며, 파일을 삭제해도 해당 에이전트의 클라우드 스토리지에 있는 사본만 제거되고 사용자 컴퓨터의 원본은 그대로 남습니다. 또한 한 에이전트의 파일은 다른 에이전트에서 자동으로 사용할 수 없습니다. 세 위치를 분리하면 문서가 어디에 있고 누가 읽을 수 있으며 얼마나 오래 유지되는지를 언제나 알 수 있습니다. 이를 통해 비밀 정보가 장기 컨텍스트에 들어가지 않게 하고 중요한 자료가 하나의 채팅 기록에만 남는 상황을 피할 수 있습니다.

---

파일 위치가 작업의 연속성을 결정합니다

흔히 생기는 실패 사례를 떠올려 보세요. 프로젝트 브리프를 채팅에 붙여 넣고 핵심을 뽑아 달라고 하면 에이전트가 잘 처리합니다. 사흘 뒤 "그 브리프를 바탕으로 일정을 작성해 줘"라고 요청했지만 결과가 전혀 맞지 않습니다. 브리프가 사흘 전 대화 안에만 있었고, 다시 안정적으로 불러올 수 있는 위치에는 저장되지 않았기 때문입니다.

이제 두 번째 실패를 상상해보세요. 에이전트가 서버 설정을 "기억"할 수 있도록 비밀 키가 포함된 구성 블록을 장기 컨텍스트 파일에 작성했습니다. 그 이후부터 해당 블록은 모든 세션에서 배경으로 읽혀집니다. 이는 메모리의 의도된 용도가 아닙니다. 이는 민감한 데이터가 불필요하게 장기간 노출되는 것입니다.

둘 다 동일한 문제를 지적합니다. 파일이 있는 위치는 깔끔한 환경을 선호하지 않습니다. 자료를 안정적으로 검색할 수 있는지, 누가 읽을지, 보관 기간이 결정됩니다. 이 문서에서는 세 가지 위치와 각 위치의 경계를 설명합니다.

---

1. 세 가지 위치, 세 가지 책임

먼저 세 위치의 역할을 한눈에 비교해 보겠습니다.

가장 자주 혼동되는 쌍은 컨텍스트 파일과 클라우드 저장소입니다. 둘 다 지속되지만 완전히 다른 방식으로 읽혀집니다. 컨텍스트 파일은 모든 세션의 상주 배경인 반면, 클라우드 저장소 파일은 필요할 때 가져오는 자료이며 모든 대화에 자동으로 삽입되지 않습니다.

이러한 구별은 민감한 정보를 처리하는 방법을 직접적으로 결정합니다. 아래에서 설명합니다.

---

2. 작업 디렉터리: 작업이 이루어지는 경계 안의 공간

작업 디렉터리는 현재 작업의 입력과 출력, 도구 실행 결과를 보관합니다. 이 공간에는 두 가지 핵심 특성이 있습니다.

첫째, 작업 현장입니다. 파일 읽기, 파일 쓰기, 명령 실행, 아티팩트 제작 등이 모두 이곳에서 이루어집니다. 실제로 작업을 계속할 수 있는 에이전트는 매번 처음부터 시작하는 대신 여기서 지속하려면 중간 상태가 필요합니다.

둘째, 경계가 명확합니다. 도구는 작업 공간을 지나 임의의 시스템 경로에 도달할 수 없습니다. 이러한 제한은 누락된 기능이 아닙니다. 파일 읽기/쓰기를 모두 사용 가능하고 제어 가능하게 만드는 것은 전제 조건입니다. 전체 파일 시스템에 걸쳐 읽기/쓰기가 제한되지 않는 에이전트는 하나의 잘못된 판단도 잠재적으로 되돌릴 수 없는 결과로 바꿉니다.

이 경계를 이해하면 실질적인 결과가 나옵니다. 에이전트가 문서를 처리하도록 하려면 컴퓨터의 임의 디렉터리를 검색하기보다는 문서를 액세스할 수 있는 위치에 두십시오.

---

3. 컨텍스트 파일: 첨부 파일이 아닌 장기 계약서

이 세 파일을 "에이전트에 업로드한 자료"로 오해하기 쉽지만 역할은 전혀 다릅니다. 컨텍스트 파일은 에이전트가 사용자와 업무 관계를 어떤 방식으로 이해할지 정합니다.

업로드된 자료와 다른 점 세 가지:

차이점 1: 읽기 타이밍. 컨텍스트 파일은 모든 세션에서 사용되는 상주 배경입니다. 클라우드 저장소 파일은 필요할 때만 가져옵니다.

차이점 2: 콘텐츠 형태. 컨텍스트 파일은 대규모 원시 자료 블록이 아닌 안정적인 규칙, 선호도 및 사실 항목에 적합합니다. 10페이지 분량의 브리핑을 MEMORY.md에 넣는 것은 이후의 모든 세션에 부담만 줍니다.

차이점 3: 민감도 요구 사항. 상주하기 때문에 장기 컨텍스트 파일에 비밀번호, 키 또는 불필요하고 민감한 정보를 기록하지 마십시오. 에이전트가 민감한 구성을 처리해야 하는 경우 이를 백그라운드에 무기한 두지 말고 제어된 경로를 통해 제공하고 나중에 정리하십시오.

세 번째 요점은 이 기사에서 가장 중요한 실제 규칙입니다.

세 가지 컨텍스트 파일이 공동으로 동작을 형성하는 방법에 대해서는 "Hermes Agent의 성격이 어디에서 왔는지: 페르소나, 기본 설정 및 장기 메모리"를 참조하세요.

---

4. 클라우드 스토리지: 에이전트용 파일 작업 공간

클라우드 스토리지는 에이전트가 사용할 파일 작업 공간입니다. 콘솔에서 작업 자료를 한곳에 보관하고 파일을 업로드·정리하거나, 필요한 파일을 로컬 환경으로 다운로드할 수 있습니다.

4.1 언제 사용하는가

에이전트가 참고 자료, 작업 문서, 결과물을 다시 사용해야 한다면 채팅에 한 번 붙여 넣는 대신 클라우드 스토리지에 보관하세요. 대표적인 사용 방식은 두 가지입니다.

• 먼저 업로드한 후 처리 — 프로젝트 개요를 업로드한 다음 에이전트에 핵심 포인트 추출을 요청하세요. 해당 자료는 나중에 참조할 수 있도록 계속 유지됩니다.
• 반복 작업을 위한 폴더 만들기 — 진행 중인 작업에 폴더를 제공하고 유지 관리하여 출력물을 안정적으로 보관할 수 있습니다.

4.2 알아야 할 구체적인 한계

사용하기 전에 다음 제한을 확인하세요.

• 단일 파일 업로드 및 다운로드는 최대 1GB까지 지원됩니다. 더 큰 파일은 먼저 분할하거나 압축해야 합니다.
• 삭제하면 해당 에이전트의 클라우드 스토리지에 있는 호스팅된 복사본만 제거됩니다, 컴퓨터에 있는 원본 파일은 제거되지 않습니다. 그럼에도 불구하고 삭제하기 전에 필요한 것이 있으면 모두 다운로드하세요. 호스팅된 복사본은 제거되면 사라집니다.
• 한 에이전트의 파일은 다른 에이전트에서 자동으로 사용할 수 없습니다. 에이전트 간에 자료를 이동하려면 명시적인 조치가 필요합니다. 공유 파일 영역을 가정하지 마십시오.
• 업로드하는 동안 페이지를 열어두고, 완료될 때까지 기다리고, 다른 작업을 수행하기 전에 파일이 현재 폴더에 나타나는지 확인하세요.

4.3 복잡한 폴더 구조는 필요하지 않습니다

폴더 계층을 복잡하게 만들 필요는 없습니다. 대부분의 경우 자료, 진행 중, 완료 세 폴더면 충분합니다. 파일을 실제로 더 빨리 찾을 수 있을 때만 하위 단계를 추가하세요.

구조가 건강한지 확인하는 한 가지 테스트: 폴더 이름으로 해당 자료가 속한 작업을 명확하게 알 수 있습니까? 내부 내용을 기억하기 위해 폴더를 열어야 하는 경우 이름이 실패한 것입니다. 에이전트는 동일한 이름을 사용하여 어떤 자료인지 판단합니다.

---

5. 이 문서는 어디로 가야 하나요? 의사결정 경로

문서를 어디에 둘지 결정할 때는 다음 질문을 순서대로 확인하세요.

질문 1: 규칙인가요, 선호인가요, 아니면 사실 입력인가요? 예 → 컨텍스트 파일. SOUL.md에 대한 규칙, USER.md에 대한 기본 설정, MEMORY.md에 대한 사실. 원시 소스 텍스트가 아닌 정제된 결론을 저장합니다.

질문 2: 보관할 가치가 있고 반복적으로 참조될 가능성이 있는 자료 또는 결과물입니까? 예 → 클라우드 스토리지. 목적을 설명하는 이름을 사용하여 적절한 폴더에 업로드하세요.

질문 3: 이 작업만 수행합니까? 예 → 작업 디렉토리에서 처리하십시오. 장기 보존이 필요하지 않습니다.

질문 4: 비밀번호, 키 또는 민감한 개인정보가 포함되어 있나요? 예 → 장기 컨텍스트 파일에서 제외하세요. 제어된 경로를 통해 제공하고 작업이 끝나면 정리하세요.

이 경로의 가치는 "어디든지 드롭"을 합리적인 선택으로 바꾸는 것입니다. 대부분의 일상적인 마찰은 질문 1과 2를 혼동하는 데서 발생합니다. 대량 자료를 컨텍스트 파일에 넣거나 보관할 만한 자료를 채팅 로그에 남겨 두는 것입니다.

---

6. 일반적인 증상과 살펴봐야 할 곳

마지막 두 행은 컨텍스트 파일을 문서 창고로 취급이라는 동일한 실수의 두 면을 나타냅니다. 테스트는 간단합니다. 콘텐츠의 일부를 모든 세션에서 읽을 필요가 없으면 해당 콘텐츠는 컨텍스트 파일에 속하지 않습니다.

---

7. LightVela의 접근 방식: 위치를 표시하고 제어 가능하게 만들기

Hermes는 시스템 구조에서 작업 디렉터리와 컨텍스트 파일을 구분하지만, 자료를 호스팅하고 찾기 쉽게 정리하는 일은 사용자가 맡습니다. LightVela는 파일 작업 공간을 제품 안에서 확인하고 관리할 수 있는 기능으로 제공하는 방향을 취합니다.

• 통합 파일 작업 공간 — 제품을 종료하지 않고도 콘솔에서 업로드, 생성, 구성, 다운로드, 이름 바꾸기 및 삭제가 가능합니다.
• 명시적인 경계 — 작업 디렉터리가 제한되어 있으며 도구는 작업 공간을 지나 임의의 시스템 경로에 도달하지 않습니다.
• 삭제 의미 지우기 — 삭제하면 해당 에이전트 저장소에 있는 호스팅된 복사본만 제거되고 로컬 원본은 그대로 유지되며 먼저 다운로드하라는 메시지가 표시됩니다.
• 에이전트 간 격리 — 에이전트마다 별도의 파일 영역을 제공하므로 자료가 공유되어서는 안되는 곳으로 누출되지 않습니다.
• 다른 기능과 분리 — 모델을 전환해도 클라우드 스토리지에 파일을 다시 쓰지 않습니다.

---

핵심 요약

• 세 가지 위치에는 각기 다른 역할이 있습니다. 작업 디렉터리는 경계가 있는 작업 공간이고, 컨텍스트 파일은 매 세션에 적용되는 장기 규칙이며, 클라우드 스토리지는 필요할 때 가져오는 자료와 결과물을 보관합니다.
• 컨텍스트 파일과 클라우드 스토리지는 읽기 타이밍이 다릅니다. 전자는 모든 세션에 상주하고 후자는 주문형입니다.
• 클라우드 스토리지의 파일당 업로드·다운로드 한도는 1GB입니다. 삭제하면 호스팅된 사본만 제거되며, 한 에이전트의 파일을 다른 에이전트에서 자동으로 사용할 수는 없습니다.
• 폴더 구조는 단순하게 유지됩니다. 일반적으로 목적을 설명하는 이름을 사용하여 자료/진행 중/완료로 충분합니다.
• 지켜야 할 한 가지 규칙: 장기 컨텍스트 파일에 비밀번호, 키 또는 불필요하고 민감한 정보를 절대 쓰지 마세요.
• 세션이 무겁거나 느리게 느껴지면 먼저 대량 자료가 컨텍스트 파일에 푸시되었는지 확인하세요.