【#1】Hermes Agent 분석하기

연재 「Hermes Agent 분석하기」 제1회.

연재 「Hermes Agent 분석하기」 총 10회

[제1회 전체상과 읽는 법] (본 기사) - [제2회 코어 대화 루프]

• [제3회 상태 관리와 컴팩션 (Compaction)]
• [제4회 기억 아키텍처와 인격]
• [제5회 툴 시스템]
• [제6회 멀티 에이전트 병렬 처리]
• [제7회 Kanban 영속 태스크 보드]
• [제8회 접속층과 인터페이스 총람]
• [제9회 확장 운용]
• [제10회 보안과 안전 운용]

나는 수중에 있는 Mac Studio에서 로컬 LLM을 돌리고, Obsidian의 vault와 자체 에이전트 기반을 연결하여 일상의 생산성을 지탱하고 있다. 그렇게 '나만의 에이전트'를 운용하다 보면, 어느 시점에서 반드시 이런 생각이 든다——이 상자 안에서 도대체 무슨 일이 일어나고 있는 것인가.

프롬프트를 던지고, 툴이 실행되며, 답이 돌아온다. 그 매끄러운 경험의 이면에는 대화 루프(Conversation Loop), 상태 관리(State Management), 컴팩션(Compaction), 기억의 재주입(Memory Re-injection), 병렬 실행(Parallel Execution), 승인 게이트(Approval Gate)와 같이 수수하지만 본질적인 기구들이 쌓여 있다. 에이전트를 '사용하는' 단계에서 '설계를 이해하고 운용하는' 단계로 나아가려면, 누군가가 작성한 구현체를 한 번 제대로 분석해 보는 것이 지름길이다.

주제로 선택한 것은 Nous Research의 Hermes Agent이다. 툴 호출형(Tool-calling)·멀티 서피스(Multi-surface) 범용 AI 에이전트로, OpenAI SDK 호환성을 축으로 삼으면서 28개의 모델 프로바이더(Model Provider), tools/ 직하 82개 파일(그중 레지스트리에 등록된 툴은 71개), 플러그인/스킬 확장 기구를 갖추고 있다. MIT 라이선스로 소스를 읽을 수 있다. '실용적인 규모를 가지면서도 혼자서 전체를 쫓을 수 있는' 경계선상의 좋은 예시다.

이 연재는 총 10회에 걸쳐 진행된다. 소스를 장별로 읽으며 설계 판단의 의도를 언어로 풀어낼 것이다.

일관되게 내세우는 테제(Thesis)는 인격 = 지능 × 기억 ——자세한 내용은 제4회(하이라이트)에서 다룬다.

• 툴 호출형·멀티 서피스 범용 AI 에이전트 (Nous Research / MIT 라이선스)
• OpenAI SDK 호환성을 축으로 함
• 28개 모델 프로바이더 (plugins/model-providers/ 직하 디렉토리 실측)
• tools/ 직하 82개 파일이지만, 레지스트리에 실제로 등록되는 툴은 71개 (나머지는 승인·URL 안전 체크 등의 비툴 모듈)
• 플러그인/스킬/훅(Hook)/프로필에 의한 확장 기구

'82개 툴'이라고 쓰면 부정확해질 수 있다는 점에 주의해 주길 바란다. 82는 tools/ 직하의 .py 파일 수이지, 툴의 수가 아니다. 실제로 에이전트가 호출할 수 있는 툴은 기동 시 registry.register(...)로 등록되는 71개다. 이 구분은 제5회에서 총 71개의 카탈로그를 나열하며 검증할 것이다.

Hermes는 크게 5개 층으로 나뉜다. 위에서부터 사용자가 접하는 서피스(Surface) (CLI / TUI / Web / 각종 채팅), 그것들을 묶어주는 커넥티비티(Connectivity) (Gateway / ACP / MCP), 핵심부인 코어 런타임(Core Runtime) (대화 루프·상태·기억), 능력을 부여하는 툴 & 확장(Tool & Extension), 그리고 최하층의 **모델 프로바이더(Model Provider)**다.

※ 그림 소스:

01-architecture.mmd

이 '하나의 코어를 다면적으로 노출하는' 설계 사상이 Hermes 전체를 관통한다. 동일한 대화 루프를 에디터에서는 ACP로, Claude Code에서는 MCP로, 외부 앱에서는 OpenAI 호환 API로——동시에 호출할 수 있다. 제8회에서 자세히 다루겠다.

hermes-agent/
├── run_agent.py # 엔트리: 1턴을 구동
├── hermes_state.py # SQLite + FTS5 세션 스토어 (4,125행)
...

UI는 Python 외부에 독립되어 있다 (ui-tui / web / apps / website). 코어는 API를 제공할 뿐이며, 외형은 별도의 레이어가 담당한다는 분리 구조다.

테스트는 1,353개 (test*.py / *_test.py 실측. tests/ 하위의 모든 .py는 1,401개이지만, 테스트 함수를 가진 파일 기준으로 1,353개). 이 규모의 에이전트로서는 매우 탄탄하다.

런타임 상태는 모두 홈 디렉토리 하위의 ~/.hermes/

에 집약된다.

---

state.db

— 세션 메시지 (Session Messages) SQLite 저장소 -
config.yaml

— 설정 (Configuration) -
.env

/auth.json

—평문 자격 증명 (Plaintext Credentials) (제10회에서 다룰 가장 큰 리스크) -
cron

/skills

/memories

/logs

.env

와 auth.json

이 평문이라는 점은 운영상 가장 주의해야 할 부분이다. chmod 600의 철저한 적용은 제10회의 체크리스트에 포함했다.

혼란스러울 수 있으므로 먼저 정리해 둔다. Hermes의 '버전'은 세 가지 계층이 있다.

계층	값	출처
공식 사이트 표시	v0.15.2	hermes-agent.nousresearch.com (2026-06-04 시점)
로컬 자기 신고 버전	v0.15.1	hermes --version (pyproject.toml / hermes_cli/__init__.py)
로컬 실체	v2026.5.29-697-gaeec88c77	git describe --tags

로컬의 main 브랜치는 최신 태그인 v2026.5.29로부터 697 커밋 앞서 있다 (git rev-list --count v2026.5.29..HEAD = 697). 0.15.2는 별도의 태그인 v2026.5.29.2로 생성되었지만