Hermes 입문: 모델·에이전트·데스크톱 한 번에 잡기

Hermes라는 이름은 Nous Research가 내놓은 세 가지 별개 제품에 함께 붙어 있어서 먼저 구분하고 시작해야 한다. 같은 브랜드지만 계층이 다르므로 섞어서 이해하면 설치나 연동 단계에서 길을 잃는다.

Hermes 4와 Hermes 4.3은 모델 가중치이고, Hermes Agent는 그 위에서(또는 다른 어떤 LLM 위에서도) 도는 실행 프레임워크다. Hermes Desktop은 Hermes Agent와 같은 코어를 공유하는 데스크톱 앱이라 CLI 대신 GUI로 같은 기능을 쓰는 셈이다.

중요한 성질 하나는 Hermes Agent가 모델 불가지론(model-agnostic)이라는 점이다. 즉 Hermesundefined모델을 반드시 써야 프레임워크가 도는 것이 아니라, 어떤 LLM 위에서도 동작한다. 이 가이드는 대부분 Hermes Agent(프레임워크)를 다루고, 마지막 심화 섹션에서 Hermesundefined모델을 직접 서빙하는 법을 별도로 다룬다.

Hermes Agent의 코어는 Python 3.11이고 UI는 TypeScript로 되어 있으며, 패키지 매니저로 uv를 쓴다. 설치는 원라인 스크립트로 끝난다.

# macOS / Linux
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# Windows PowerShell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

설치가 끝나면 대화형 CLI나 TUI로 실행한다.

hermes          # 대화형 CLI
hermes --tui    # 터미널 UI

처음이라면 Nous Portal OAuth로 한 번에 묶어주는 빠른 셋업을 권장한다.

hermes setup --portal

설정은 ~/.hermes/config.yaml에 모이고, API 키나 봇 토큰 같은 비밀값은 같은 디렉터리의 .env에 둔다. 비밀값을 config.yaml 본문이나 저장소에 올리지 않도록 처음부터 분리해서 관리하는 편이 좋다.

Hermes Agent는 모델 불가지론이라 사용할 LLM을 자유롭게 바꿀 수 있다. 전환은 hermes model 명령으로 한다.

모델 식별자는 provider/model-name 형식을 쓴다. 예를 들면 다음과 같다.

anthropic/claude-opus-4
openrouter/...
google/gemini-2.5-flash

hermes model    # 사용 모델 전환

선택한 모델의 API 키는 앞서 말한 ~/.hermes/.env에 둔다. 한 가지 하드 제약이 있는데, 사용하는 모델은 최소 64,000 토큰의 컨텍스트를 지원해야 한다. 에이전트가 스킬과 메모리, 툴 정의를 컨텍스트에 함께 싣기 때문에 이보다 짧은 컨텍스트 모델은 안정적으로 돌지 않는다. 모델을 고를 때 컨텍스트 한도부터 확인하는 습관을 들이는 편이 좋다.

스킬(skill)은 Hermes Agent의 절차적 기억이다. 형식은 SKILL.md라는 마크다운 파일이며, YAML frontmatter에 name과 description이 필수다. name은 소문자-하이픈 형태로 쓰고, 이 이름이 곧 슬래시 명령 라우트가 된다. 본문 아래에 references·templates·scripts·assets 하위 폴더를 선택적으로 둘 수 있다.

---
name: deploy-staging
description: 스테이징 환경에 배포하는 절차
---

저장 경로는 ~/.hermes/skills/<category>/<skill>/SKILL.md다. 설치된 스킬은 자동으로 /<skill-name> 슬래시 명령이 되고, /skills로 전체를 탐색한다. 이 포맷은 오픈 표준 agentskills.io와 호환된다.

스킬의 핵심은 에이전트가 스스로 만든다는 점이다. skill_manage 툴(create/patch/edit/delete)로 자기개선 루프를 돈다. 생성 트리거는 네 가지로, 툴 호출 5회 이상의 복잡한 작업을 성공했을 때, 에러에서 동작 경로를 발견했을 때, 사용자가 접근법을 교정했을 때, 비자명한 워크플로를 발견했을 때다. 턴이 끝나면 background self-improvement review가 스킬을 다듬는다. 이 자동 생성·수정이 통제 없이 돌면 곤란하므로 skills.write_approval로 승인 게이트를 걸 수 있다. 운영 환경에서는 이 승인 게이트를 켜서 에이전트가 만든 스킬을 검토 후 반영하는 흐름을 권장한다.

Hermes Agent의 메모리는 세 계층으로 나뉜다. 각 계층의 동작과 파일 위치를 정확히 알아야 데이터가 어디에 어떻게 남는지 통제할 수 있다.

중기 메모리는 모든 세션을 ~/.hermes/state.db에 저장하고 FTS5 전문검색을 건다. session_search 툴로 필요할 때만 조회하며, 이때 돌려주는 것은 과거 대화의 원문이다. 요약본이 아니라 실제 기록을 그대로 반환하므로, 예전 세션에서 무슨 일이 있었는지 정확히 되짚을 때 유용하다.

장기 메모리는 ~/.hermes/memories/ 아래 두 마크다운 파일이다. MEMORY.md는 환경 사실과 교훈을, USER.md는 사용자가 선호하는 모델 같은 선호를 담는다. 두 파일은 세션 시작 시 시스템 프롬프트에 한 번 주입된다. 에이전트가 memory 툴로 이 내용을 자가 큐레이트하는데, 한도를 넘기면 조용히 버리지 않고 에러를 반환한다. 즉 메모리가 말없이 유실되는 일이 없도록 설계되어 있어서, 한도 에러가 보이면 직접 정리해주면 된다.

세 가지 확장 기능으로 단일 에이전트를 넘어선 워크플로를 구성한다.

서브에이전트는 delegate_task 툴로 위임한다. 위임된 작업은 완전히 새 대화로 시작하고, 기본 동시성은 3이다. 기본적으로 블로킹이며 최종 요약만 부모로 귀환한다. v0.17에서 background/async 모드가 추가되어 부모가 기다리지 않고 진행할 수 있게 되었다.

MCP 통합은 시작 시 MCP 서버를 발견해서 각 툴을 mcp_<server>_<tool> 네임스페이스로 등록하는 방식이다. stdio와 HTTP 전송을 지원하며, config.yaml의 mcp_servers에 정의한다.

Cron은 ~/.hermes/cron/jobs.json에 정의한다. 상대 지연, 인터벌, cron식, ISO 스케줄을 지원한다. 게이트웨이가 60초마다 틱을 돌며, 각 실행은 히스토리 없는 새 에이전트로 시작한다.

// ~/.hermes/cron/jobs.json 위치에 스케줄 정의

각 cron 실행이 히스토리 없는 새 에이전트라는 점은 중요하다. 이전 실행의 컨텍스트가 자동으로 이어지지 않으므로, 반복 작업에서 누적 상태가 필요하면 메모리 계층이나 외부 저장에 명시적으로 남겨야 한다.

Hermes Agent는 로컬을 넘어 여러 환경에 배포할 수 있고, 다양한 메시징 채널을 게이트웨이로 붙인다. 배포 대상은 Local·Docker·SSH·Modal·Daytona를 지원하고, $5 수준의 VPS에서도 돌아간다. 메시징 채널은 Telegram·Discord·Slack·WhatsApp·Signal·Email·Teams 등을 gateway setup으로 연결한다.

배포와 채널 연동은 곧바로 보안 경계가 넓어지는 일이라 가장 신중하게 다뤄야 한다. 자율 에이전트는 스스로 스킬을 만들고 툴을 호출하며 외부 채널로 메시지를 보낼 수 있으므로, 통제 지점을 명시적으로 잡지 않으면 의도하지 않은 동작이 외부로 나간다.

실무에서 우선 챙길 통제 지점은 다음과 같다.

• 스킬 자율 생성에는 skills.write_approval 승인 게이트를 켜서, 에이전트가 만든 스킬을 사람이 검토한 뒤에만 반영한다.
• API 키와 봇 토큰은 config.yaml이 아니라 ~/.hermes/.env에만 두고, 저장소나 외부 채널에 평문으로 노출하지 않는다.
• 서브에이전트 위임과 cron 실행은 각각 새 대화·히스토리 없는 새 에이전트로 시작하므로, 자동화가 권한을 어디까지 갖는지 위임·스케줄 단위로 점검한다.
• 메시징 채널을 붙일 때는 채널별 토큰을 분리해 두고, 외부로 나가는 출력 경로를 최소 권한으로 좁힌다.
• 메모리는 한도 초과 시 에러를 반환하므로 이 신호를 무시하지 말고, 어떤 환경 사실과 사용자 선호가 시스템 프롬프트에 주입되는지 MEMORY.md·USER.md를 주기적으로 직접 검토한다.

자율성이 높을수록 사람이 개입하는 게이트를 어디에 둘지가 운영 안정성을 좌우한다. 승인 게이트·비밀값 분리·채널 권한 최소화 세 가지를 배포 전에 먼저 확정해 두는 편이 안전하다.

프레임워크와 별개로 Hermes<think>...</think>모델을 직접 서빙해 연동할 수도 있다. 이 경우 모델의 tool-use 포맷과 추론 토글, 서빙 파서를 알아야 한다.

tool-use 포맷은 XML 태그 기반이다. 시스템 프롬프트의 <tools>...</tools>에 JSON function 스키마를 선언하면, 모델이 <tool_call>{...}</tool_call>로 호출하고 결과를 <tool_response>로 다시 피드백한다. 하이브리드 추론은 <think>...</think> 세그먼트로 사고 과정을 방출하며, 토글이 가능하다. 챗 템플릿에서 thinking=True로 켜거나 시스템 프롬프트로 켤 수 있다.

서빙 시 파서 설정이 핵심이다. vLLM은 --tool-call-parser hermes를 쓰고, SGLang은 qwen25를 쓴다.

vllm serve "NousResearch/Hermes-4-405B" --tool-call-parser hermes

모델 크기와 베이스는 현행 HuggingFace 카드 기준으로 다음과 같다. 공식 FP8과 커뮤니티 GGUF가 제공된다.

권장 샘플링은 temperature=0.6, top_p=0.95, top_k=20이다. Hermes<think>...</think>패밀리는 하이브리드 추론 모델로 2025년 8월 공개되었고 기술보고서는 arXiv 2508.18255다.

한편 Hermes 4.3은 별개 라인으로 표기한다. 2025년 12월 3일 공개되었고, 베이스는 ByteDance Seed-OSS-36B-Base로 36B 규모에서 Hermes<think>...</think>70B에 근접하거나 일부 초과하는 성능을 낸다. Psyche 네트워크 분산학습으로 만들어진 production 분산학습 모델이다.