LightVela 문서

요약

USER.md와 MEMORY.md는 Hermes Agent의 장기 메모리를 구성하는 두 개의 개인 기록이며, 세 가지 이유로 하나로 합칠 수 없습니다. 첫째, 용량이 독립적이어서(USER.md 약 1,375자/500토큰, MEMORY.md 약 2,200자/800토큰) 서로의 공간을 침범하지 않습니다. 둘째, 둘 다 매 세션에 로드되지만 역할이 다릅니다. USER.md는 "사용자가 누구인지"를 안정적으로 설명하고, MEMORY.md는 "함께 수행한 작업"을 계속 기록합니다. 셋째, 업데이트 방식도 다릅니다. USER.md의 선호도 필드는 기존 값을 주로 덮어쓰지만, MEMORY.md는 필요할 때 항목을 추가하고 통합합니다. 둘을 NOTES.md 하나로 합치면 이 세 가지 경계가 모두 사라져 구조는 단순해 보여도 실제 동작은 더 나빠집니다.

먼저 떠오르는 합리적인 질문

Hermes의 계층형 메모리에서 USER.md와 MEMORY.md를 합쳐도 약 3,575자 / 1,300토큰에 불과합니다. 수십만 토큰 규모의 컨텍스트 창이 흔한 시대를 생각하면 매우 절제된 크기입니다.

따라서 대부분의 사람들의 첫 번째 반응은 세 가지 질문입니다.

단일 NOTES.md로 병합해 보는 것은 어떨까요?
왜 수십 킬로바이트까지 확장하면 안 되나요?
왜 두 파일의 상한선이 서로 다른가요(2,200 대 1,375)?

세 질문의 답은 같습니다. USER.md와 MEMORY.md는 성격이 다른 두 종류의 메모리이며, 한곳에 합치면 둘 다 제 역할을 하기 어려워집니다. 아래에서는 이 설계 원칙을 세 가지 관점에서 살펴봅니다.

1. `USER.md`: 안정적이고 구조화된 사용자 프로필

USER.md는 사용자에 대한 안정적인 프로필입니다.

신원 : 이름, 역할, 위치.
선호사항: 의사소통 스타일, 일반적인 기술 스택.
제약사항: 일정, 언어, 피해야 할 주제.
작업 스타일: 결론이 먼저이거나 프로세스가 먼저입니다.
장기 목표: 당신이 무엇을 향해 노력하고 있는지.

주요 특성:

안정적: 며칠 또는 몇 주에 한 번씩 업데이트됩니다.
구조화됨: 섹션과 항목으로 나뉘며 데이터 필드를 기준으로 정리됨.
항상 로드됨: 모든 세션이 시작될 때 시스템 프롬프트에 삽입됩니다.
단단한 한도: ~1,375자 / ~500토큰.

USER.md를 에이전트 모니터 베젤의 스티커 메모라고 생각하세요. 그다지 많지는 않지만 항상 눈에 띄고 유용합니다.

2. `MEMORY.md`: 계속 쌓이고 필요할 때 검색하는 사실 기록

MEMORY.md는 사용자와 에이전트가 함께 수행한 작업을 저장합니다.

프로젝트 상태: agent-demo 프런트엔드는 로컬 개발 포트에서 실행됩니다.
결정: 지난주 영웅 섹션이 애니메이션 그라데이션으로 변경되었습니다.
특정 이벤트: X가 4분기에 배송하기로 A팀과 합의했습니다.
특정 지식: 이 API는 공개 엔드포인트가 아닌 내부 SDK를 통해 인증합니다.

주요 특성:

동적: 거의 모든 실질적인 세션이 하나 또는 두 개의 항목을 작성합니다.
항목 단위: 나중에 쉽게 회상할 수 있도록 정보를 개별 항목으로 추가합니다.
항상 로드 및 주문형 FTS5 일치: 공통 항목은 모든 세션을 로드하고, 기록 항목은 FTS5 일치로 가져옵니다.
일반적으로 8~15개의 항목: 총 최대 2,200자/~~800개의 토큰에 해당하는 8~~15개의 항목을 목표로 합니다.

MEMORY.md를 책상 위 일기장이라고 생각하세요. 단순한 스티커 메모 이상이지만, 아껴서 빠르게 훑어볼 수 있습니다.

3. `NOTES.md` 하나로 합칠 수 없는 세 가지 이유

두 파일 모두 매 세션에 로드되는 Markdown인데 하나로 합치면 되지 않느냐는 질문이 자연스럽게 나옵니다.

세 제약은 각각 독립적으로도 두 파일을 분리해야 할 충분한 이유가 됩니다.

제약 1: 서로 영향을 주지 않는 독립 용량

USER.md에는 500토큰, MEMORY.md에는 800토큰의 별도 한도가 있습니다. 이를 1,300토큰짜리 NOTES.md 하나로 합치면 곧바로 문제가 생깁니다. 공간이 거의 찼을 때 새 사건 하나를 기록하려고 "사용자가 누구인지" 설명하는 줄을 지워야 할까요?

당연히 해서는 안 됩니다. 그러나 일단 병합되면 해당 결정을 내려야 하며 쓸 때마다 내려야 합니다. 별도로 보관하면 두 개의 풀이 독립적으로 발전합니다. MEMORY.md가 가득 차면 스스로 압축될 뿐이며 프로필을 오염시키지 않습니다.

제약 2: 서로 다른 로딩 의미

두 파일 모두 실제로 모든 세션에서 로드되지만 시스템 프롬프트에서의 역할은 완전히 다릅니다.

USER.md 섹션은 "당신이 상대하고 있는 사람"에 대답하여 에이전트의 톤, 세부 수준 및 스택 가정을 설정합니다.
MEMORY.md 섹션은 "당신이 함께 한 일"에 대해 답변하여 에이전트에 사실적인 설명을 제공합니다.

두 가지를 병합하면 서로를 희석할 수 있습니다. 에이전트는 더 이상 "이것이 내가 따라야 하는 의사소통 스타일인지, 아니면 인용해야 하는 과거 사실인지"를 신속하게 알 수 없습니다.

제약 3: 서로 다른 업데이트 의미

USER.md의 기본 설정 필드는 대부분 덮어쓰기: 사용자가 "지금부터 요약 중지"라고 말하면 관련 기본 설정 줄을 직접 덮어씁니다.
MEMORY.md는 대부분 요청 시 추가 및 통합됩니다: 이벤트는 시계열이므로 기록을 임의로 삭제할 수 없습니다. 용량이 가득 차면 다음 오류 응답으로 활성 통합이 트리거됩니다.

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Consolidate now...",
  "current_entries": [...],
  "usage": "2,100/2,200"
}

병합하면 add / replace / remove가 한 파일에서 함께 동작해야 하므로 구현 복잡도와 사용자의 이해가 동시에 나빠집니다.

4. 구체적인 예

에이전트에게 다음과 같이 말한다고 가정해 보겠습니다.

"저는 프론트엔드 엔지니어인 Jasmin이고 결론 우선 커뮤니케이션을 좋아합니다. 저는 Next.js를 사용하여 agent-demo(AI 에이전트 앱)의 글로벌 사이트에서 작업하고 있습니다. 지난주에 히어로 섹션을 애니메이션 그라데이션으로 변경했습니다."

잘 훈련된 Hermes Agent는 다음과 같이 분할합니다.

USER.md에 작성:

## Identity
- Name: Jasmin
- Role: Frontend engineer

## Preferences
- Communication style: conclusion first
- Usual stack: Next.js

MEMORY.md에 작성:

- [2026-07-30] agent-demo: hero section on the global site changed to an animated gradient.
- Related project: agent-demo / global site (global region)

차이점이 보이시나요?

"당신은 어떤 사람인가요?"가 프로필에 입력됩니다. "우리가 함께 한 일"은 아카이브에 들어갑니다.
전자는 귀하가 변경될 때만 변경됩니다(새 직업, 새 팀). 후자는 매일 대화를 통해 성장합니다.
별도의 파일을 통해 각각이 스스로 발전할 수 있습니다.

5. 기록하지 않는 다섯 가지 정보

Hermes는 모든 정보를 USER.md에 넣지 않습니다. 다음 다섯 가지 정보는 기록 대상에서 제외합니다.

일회성 기분: "오늘 머리가 아파요" — 안정적인 속성이 아닙니다.
임시 작업 매개변수: "이 제목을 X로 변경하세요." — 일회용입니다.
모호한 태도: "저는 좀 더 간결한 것을 선호하는 것 같습니다." — 충분히 재사용할 수 없습니다(한정하거나 건너뛰거나).
실시간 대화 맥락에서 추론할 수 있는 모든 것 - 지속할 필요가 없습니다.
민감한 정보(이메일, 비밀번호, 사용자가 명시적으로 확인하지 않은 주소) - 개인정보 관련 콘텐츠는 기본적으로 작성되지 않습니다.

이 건너뛰기 목록은 USER.md를 "500개 토큰 및 고밀도"로 유지하는 것입니다.

6. 이것이 제품에 미치는 영향

에이전트 제품의 경우 USER.md와 MEMORY.md 간의 분할은 단순한 엔지니어링 세부 사항이 아닙니다. 이는 세 가지를 결정합니다.

사용자에게 "내가 당신에 대해 어떻게 생각하는지"를 보여줄 수 있는지 여부 — 안정적이고 읽기 쉽고 편집 가능한 프로필(USER.md의 의미)이 필요합니다.
에이전트가 장기적으로 기억상실을 피할 수 있는지 여부 — 이를 위해서는 성장하고 기억할 수 있는 사실적 아카이브(MEMORY.md의 의미)가 필요합니다.
비용이 제한되어 있는지 여부 - 계층화된 로딩만이 "자신이 누구인지 알 수 있고" 전체 컨텍스트를 태우는 것을 방지할 수 있습니다.

7. LightVela: 두 기록 레이어를 제품 경험으로 전환

LightVela의 내부 에이전트 메모리 디자인은 이러한 계층적 사고를 정확하게 차용합니다. Hermes의 USER.md 및 MEMORY.md는 개발자를 위해 작성된 Markdown 파일입니다. LightVela는 이를 일반 사용자가 직접 조작할 수 있는 두 가지로 변환합니다.

눈에 보이는 프로필 레이어: 사용자는 에이전트가 기억하는 프로필 사실과 각 대화가 어떤 대화에서 나왔는지 확인하고 한 번의 클릭으로 수정할 수 있습니다. 프로필은 더 이상 블랙박스 USER.md가 아닙니다.
구성 가능한 사실 레이어: 사실적 메모리는 단순한 항목 더미 그 이상입니다. 쉽게 기억하고 정리할 수 있도록 프로젝트, 작업 또는 시간별로 태그를 지정할 수 있습니다. 팀 시나리오에서는 팀 메모리와 개인 메모리를 별도의 레이어로 관리할 수 있습니다.
최단 경로: 계층화된 메모리 아이디어가 마음에 들지만 ~/.hermes/USER.md를 편집하고 FTS5를 유지 관리하며 SQLite를 직접 백업하고 싶지 않은 경우 LightVela가 해당 아이디어를 완성된 제품으로 만드는 최단 경로입니다.

한 줄로 말하면: Hermes는 계층형 메모리에 대한 엔지니어링 청사진을 제공했으며 LightVela는 이를 누구나 사용할 수 있는 제품 경험으로 전환합니다.

핵심 요약

USER.md: 매 세션마다 로드되는 안정적이고 구조화된 사용자 프로필(~~500개 토큰, 8~~15개 프로필 필드)
MEMORY.md: 성장하는 주문형 사실 아카이브(~~800개 토큰, 8~~15개 이벤트 항목).
세 가지 엄격한 제약으로 인해 서로 구분됩니다. 독립적인 용량/다른 로딩 의미/다른 업데이트 의미.
레이어링은 좋은 에이전트 메모리의 기본 역량이며, LightVela에서 메모리를 제품화하기 위한 출발점입니다.

LightVela 문서

이 페이지에서