Hermes Agent — self-improving 멀티채널 AI agent runtime

한 줄 요약: CLI, 메신저 게이트웨이, 도구 실행, 지속 메모리, 세션 검색, 스킬 생성/개선, cron 자동화, 멀티-프로바이더 LLM 전환을 하나의 코드베이스로 묶은 “agent operating system” 성격의 프로젝트다.

 

분석 범위 메모

• 본 요약은 README, 공식 문서 사이트(website/docs/가 사실상의 Wiki 역할), 패키징 메타데이터, 공개된 디렉터리 구조, 아키텍처/세션/도구/게이트웨이 관련 문서를 중심으로 정리했다.
• 공개 GitHub Wiki는 별도로 확인되지 않았다.
• GitHub Discussions 링크는 README에 존재하지만, 본 아카이브는 README/문서/구조/패키징 정보 중심으로 작성했다.
• 저장소가 빠르게 변하고 있어 문서 간 수치(예: tool 수, toolset 수)는 조금씩 다르다. 실제 구현 전에는 커밋 pinning이 안전하다.

Figure provenance

• 01_banner_official.png: 저장소 공식 배너 원본.
• 02~07: 공식 README/문서/코드 구조를 기반으로 오프라인 참고용으로 재구성한 도식이다.

---

 

Quick Links

항목	링크	메모
GitHub Repository	https://github.com/nousresearch/hermes-agent	메인 소스 저장소
공식 문서	https://hermes-agent.nousresearch.com/docs/	Docusaurus 기반 문서 허브
Quickstart	https://hermes-agent.nousresearch.com/docs/getting-started/quickstart	빠른 설치/실행 경로
Messaging Gateway 문서	https://hermes-agent.nousresearch.com/docs/user-guide/messaging	Telegram/Discord/Slack/WhatsApp/Signal 등
Architecture 문서	https://hermes-agent.nousresearch.com/docs/developer-guide/architecture	시스템 구조와 주요 파일 맵
Skills Hub	https://agentskills.io	skill 생태계 / 오픈 표준 연결점
Discord	https://discord.gg/NousResearch	커뮤니티
Issues	https://github.com/NousResearch/hermes-agent/issues	버그/기능 요청
Discussions	https://github.com/NousResearch/hermes-agent/discussions	README에는 연결되어 있으나, 본 아카이브는 직접 토론 본문 대신 문서/구조 중심으로 분석
Demo site	별도 hosted playground는 확인되지 않음	CLI + messaging gateway 중심의 운영 모델
관련 논문	공식 README/문서에서 대표 논문 링크는 확인되지 않음	대신 RL / trajectory / Atropos 관련 코드·문서는 존재

---

Key Features

1. 자기개선 루프(self-improving loop)
   작업 경험을 바탕으로 skill을 만들고, 사용 중 개선하며, 기억을 축적하고, 지난 대화를 다시 검색하는 구조가 프로젝트 정체성의 핵심이다.
2. 멀티-프로바이더 / 멀티-모델 런타임
   OpenAI, Anthropic, OpenRouter, Nous Portal, Gemini 계열, DeepSeek, GLM, Moonshot/Kimi, MiniMax, 커스텀 엔드포인트 등으로 전환할 수 있도록 provider resolution 계층이 분리돼 있다.
3. CLI + Messaging Gateway 이중 진입점
   hermes TUI와 hermes gateway가 공존하며, 같은 에이전트 루프를 Telegram/Discord/Slack/WhatsApp/Signal/Email/SMS/Matrix/Mattermost/DingTalk/Feishu/Lark/WeCom/Home Assistant/Webhook에 연결할 수 있다.
4. 강한 도구 실행 계층
   terminal, browser, web extraction, file ops, code execution, MCP, delegate/subagent, cron, memory, session search 등 실제 업무형 agent에 필요한 실행 surface가 넓다.
5. 도구 묶음(toolset)과 승인(approval) 체계
   “무엇을 할 수 있는가”와 “어디서 허용할 것인가”를 toolset/approval로 분리해 운영 리스크를 제어하기 좋다.
6. 지속 세션 저장 + FTS5 검색
   SQLite + FTS5 기반 세션 저장소, lineage 추적, resume/search/summarize 흐름 덕분에 장기적인 대화 기억과 회고가 가능하다.
7. Context compression + prompt caching
   긴 대화에서 중간 구간을 압축해 컨텍스트를 관리하고, 일부 provider에서는 prefix caching을 이용해 비용과 지연을 줄인다.
8. Cron 기반 자연어 자동화
   전통적인 shell cron이 아니라 “fresh AIAgent가 정해진 시점에 스킬과 프롬프트를 받아 실행되는” 구조라서 반복 보고, 점검, 리마인더, 야간 작업 자동화에 적합하다.
9. Subagent / delegation / 병렬화 지향
   복잡한 작업을 하위 에이전트나 스크립트/RPC 스타일로 나눌 수 있어, long-horizon task decomposition에 영감을 준다.
10. 실행 환경 추상화
    local / Docker / SSH / Modal / Daytona / Singularity 백엔드 위에서 terminal 작업을 추상화하므로 로컬 개발, 원격 서버, HPC/컨테이너 경로를 하나의 agent UX로 묶을 수 있다.
11. IDE/Editor integration(ACP)
    ACP(adapter) 레이어를 통해 VS Code / Zed / JetBrains와 같은 editor-native agent 경험으로 확장 가능하다.
12. 연구/평가 친화적 구조
    batch trajectory generation, RL environment, ShareGPT-format trajectory 저장 등 “운영 agent”뿐 아니라 “training/eval harness”로도 재사용 가능하다.

---

Tech Stack

분석 시점 스냅샷: Python package 버전은 0.7.0, Python은 >=3.11, Node.js는 >=18.0.0을 요구한다.

범주	핵심 구성
Runtime / Packaging	Python >=3.11, Node.js >=18.0.0, uv(개발/설치 흐름에서 사용)
Core LLM / Transport	openai>=2.21.0,<3, anthropic>=0.39.0,<1, httpx>=0.28.1,<1, tenacity>=9.1.4,<10, pydantic>=2.12.5,<3
CLI / UX	rich>=14.3.3,<15, prompt_toolkit>=3.0.52,<4, fire>=0.7.1,<1
Config / Templates	python-dotenv>=1.2.1,<2, pyyaml>=6.0.2,<7, jinja2>=3.1.5,<4, requests>=2.33.0,<3
Web / Research utilities	exa-py>=2.9.0,<3, firecrawl-py>=4.16.0,<5, parallel-web>=0.4.2,<1, fal-client>=0.13.1,<1
Browser stack (Node)	agent-browser^0.13.0, @askjo/camoufox-browser^1.0.0
Messaging / Gateway	python-telegram-bot[webhooks]>=22.6,<23, discord.py[voice]>=2.7.1,<3, aiohttp>=3.13.3,<4, slack-bolt>=1.18.0,<2, slack-sdk>=3.27.0,<4, matrix-nio[e2e]>=0.24.0,<1
Audio / Voice	edge-tts>=7.2.7,<8, elevenlabs>=1.0,<2(optional), faster-whisper>=1.0.0,<2, sounddevice>=0.4.6,<1, numpy>=1.24.0,<3
Integration / Agent protocols	mcp>=1.2.0,<2, agent-client-protocol>=0.9.0,<1.0, PyJWT[crypto]>=2.12.0,<3
Scheduling / Ops	croniter>=6.0.0,<7, terminal backends: local / docker / ssh / modal / daytona / singularity
Persistence	SQLite(WAL), FTS5, JSONL transcript export, profile-aware ~/.hermes home
Test / Research surface	tests/ 기반 대규모 pytest 스위트, batch_runner.py, environments/, trajectory helpers

 

실무 해석 포인트

• 이 프로젝트는 “챗 UI”보다 런타임 인프라에 무게가 있다.
• Python 단일 앱처럼 보이지만 실제로는 LLM provider abstraction + tool runtime + messaging control plane + persistent state layer가 결합된 구조다.
• 브라우저/메신저/음성/원격 실행 같은 주변 기능이 optional dependency로 잘 분리돼 있어, 필요한 조합만 활성화하는 식의 배포가 가능하다.

---

Architecture

Hermes Agent의 구조를 한 문장으로 요약하면, 여러 entry point(CLI / Gateway / ACP / Batch / Cron)가 하나의 AIAgent 루프를 공유하고, 그 아래에 prompt builder / provider runtime / tool dispatch / persistent state / plugin ecosystem이 매달린 형태다.

 

Figure 02. 공식 architecture 문서를 기반으로 재구성한 시스템 상위 구조.

1) 상위 시스템 구조

• Entry points
  CLI(hermes), messaging gateway, ACP adapter, batch runner, API-like surfaces가 모두 공통 코어를 향한다.
• Core orchestrator
  run_agent.py의 AIAgent가 prompt 구성, provider 선택, model API 호출, tool call loop, retry/fallback, compression, persistence를 모두 책임진다.
• Tool runtime
  model_tools.py와 tools/registry.py 축을 중심으로 도구를 self-register하고 dispatch한다.
• Persistent state
  세션은 SQLite + FTS5에 저장되고, 검색/재개/요약 흐름으로 이어진다.
• Operational surfaces
  gateway, cron, ACP, plugins, skills가 모두 core loop 주변에서 작동한다.

2) 데이터 흐름

Figure 03. CLI / gateway / cron 흐름이 결국 같은 agent loop로 수렴한다는 점이 핵심이다.

• CLI session
  사용자 입력 → HermesCLI.process_input() → AIAgent.run_conversation() → prompt builder → provider runtime → model API → tool loop → display + session DB 저장
• Gateway message
  플랫폼 이벤트 → adapter → GatewayRunner._handle_message() → 사용자 인증 + session key 계산 → AIAgent → 플랫폼으로 재전송
• Cron job
  scheduler tick → due job 로드 → fresh AIAgent 생성 → skills/context 주입 → job prompt 실행 → 결과 전달 + next_run 업데이트

3) 핵심 디렉터리와 “어디를 건드려야 하는가”

경로	역할	구현/확장 시 포인트
run_agent.py	메인 conversation loop, fallback/retry, tool loop, persistence	가장 강력하지만 가장 무거운 진입점. 가능하면 직접 수정은 최소화
cli.py, hermes_cli/	TUI, slash command, setup, config, auth, model switching	로컬 UX / 운영 명령 / onboarding 흐름 수정 지점
model_tools.py, tools/	tool discovery, schema collection, dispatch, approvals	도메인 기능 추가의 1순위 확장 지점
toolsets.py	tool groupings / platform presets	capability 최소화, 정책 제어, 안전한 배포에 중요
agent/	prompt builder, context compressor, prompt caching, auxiliary client, memory interfaces, trajectories	“에이전트의 두뇌 내부”를 이해할 때 보는 곳
hermes_state.py	SQLite + FTS5 기반 세션 저장	검색, resume, audit, lineage 이해의 핵심
gateway/	멀티-플랫폼 메시징, pairing, delivery, hooks	Slack/Telegram/Discord 같은 채널 확장 지점
plugins/memory/	pluggable memory provider	의료/엔터프라이즈처럼 규제가 있는 도메인에 특히 중요
skills/, optional-skills/	procedural memory / reusable workflows	업무 패턴을 프롬프트-절차로 고정하는 가장 저비용 확장 수단
cron/	scheduled agent jobs	반복 업무, 리포트, 리마인더 자동화
acp_adapter/	editor-native integration	IDE agent 경험에 필요한 경계
environments/, batch_runner.py	RL / eval / trajectory generation	연구, 벤치마크, training data generation에 유용

4) 운영 메커니즘에서 특히 중요한 점

• API mode가 3개
  chat_completions, codex_responses, anthropic_messages를 공통 인터페이스 아래에서 다룬다. 즉, “모델 바꾸기”가 프롬프트/도구/상태 전체를 다시 짜지 않고 가능하다.
• Compression이 2중 구조
  gateway 쪽 hygiene(대략 85% 지점) + agent 내부 compression(기본 50% 지점)으로 긴 세션을 버틴다.
• Prompt caching이 비용 최적화 포인트
  특히 Anthropic 계열에서 반복 prefix 비용을 줄이는 설계가 들어 있다.
• Session storage가 단순 로그가 아니다
  SQLite WAL, FTS5, lineage, source tag, summarize/retrieval 흐름을 갖는 “agent memory substrate”에 가깝다.
• Plugin discovery가 실제 확장성의 열쇠
  ~/.hermes/plugins/, 프로젝트 로컬 .hermes/plugins/, pip entry point까지 고려하는 구조라 배포 방식이 유연하다.

5) Messaging gateway는 별도 제품처럼 볼 가치가 있다

Figure 04. 다양한 채널을 하나의 gateway process로 통합하는 구조는 프로젝트의 큰 차별점이다.

이 저장소에서 gateway는 단순 “봇 연결 스크립트”가 아니라 다음 성격을 가진다.

• 공통 slash command surface
• 공통 session routing
• 공통 authorization/pairing
• 공통 background/cron delivery
• 채널별 media capability 차이만 adapter 수준에서 흡수

즉, Hermes는 CLI agent일 뿐 아니라 멀티채널 agent control plane으로도 해석할 수 있다.

6) 상태 저장과 로컬 홈 구조는 이해해야 한다

Figure 05. ~/.hermes 구조와 state.db의 역할은 실운영/디버깅/백업 전략에 직접 연결된다.

실제로 구현하거나 참고할 때는 ~/.hermes 구조를 먼저 이해하는 편이 좋다.

• config.yaml / .env / auth.json → 실행 구성과 인증
• SOUL.md / context files → 시스템 성격과 프로젝트별 지시문
• skills/ / memories/ / cron/ → 장기 동작 자산
• state.db / sessions/ → 재개, 검색, 감사(audit), export

7) “어디를 확장할 것인가” 관점의 구조 해석

 

Figure 07. Hermes를 참고 구현할 때는 core 수정보다 extension seam을 먼저 보는 편이 낫다.

가장 중요한 기술적 해석은 다음이다.

• monolithic core + modular edges 구조다.
  run_agent.py, cli.py는 크고 무겁지만,
  • tool
  • toolset
  • skill
  • memory plugin
  • gateway adapter
  • provider runtime
    같은 바깥 경계는 비교적 잘 나뉘어 있다.
• 따라서 이 프로젝트를 포크해 제품화하려면, core를 직접 뜯어고치는 방식보다 edge 확장 중심이 유지보수에 유리하다.

---

Usage & Setup

Figure 06. README에 나온 설치/실행/기여 흐름을 오프라인 참고용으로 재구성했다.

1) 가장 빠른 설치

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes

• 지원 경로: Linux / macOS / WSL2
• 주의: native Windows보다는 WSL2 경유가 권장 경로다.

2) 첫 실행 후 자주 쓰는 명령

hermes              # interactive CLI 시작
hermes model        # provider/model 선택
hermes tools        # tool enable/disable
hermes config set   # config key 개별 수정
hermes setup        # 전체 설정 wizard
hermes gateway      # messaging gateway 관련 하위 명령
hermes doctor       # 진단
hermes update       # 업데이트

3) Gateway 쪽 핵심 흐름

hermes gateway setup
hermes gateway start

대화 내부에서는 다음 명령 계열이 중요하다.

/new  /model  /provider  /personality  /retry  /undo
/status  /help  /stop  /approve  /deny
/compress  /usage  /background  /reload-mcp

4) Session / resume / search 관점에서 알아둘 것

• 세션은 자동 저장된다.
• 장기 작업은 resume / search / summarize 흐름이 핵심 UX다.
• 구현 참고용으로 보면, 이 부분이 단순 chat history가 아니라 “stateful agent UX”를 만든다.

5) Contributor / source install

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
python -m pytest tests/ -q

6) 실제로 이 프로젝트를 참고 구현할 때 추천 순서

1. CLI만 먼저 띄운다.
   gateway, voice, cron, MCP까지 한꺼번에 붙이면 디버깅 표면이 너무 넓어진다.
2. provider/model을 먼저 고정한다.
   추상화가 잘 돼 있어도 초기 재현성 확보에는 고정 구성이 낫다.
3. toolset을 최소화한다.
   처음에는 file/web/terminal 정도만 활성화하고, 이후 점진적으로 확장한다.
4. session persistence를 확인한다.
   실제로 agent 품질은 단발성 응답보다 resume/search/압축에서 갈린다.
5. 그 다음에 gateway 또는 cron을 붙인다.
   멀티채널/장기자동화는 코어 루프가 안정화된 뒤에 추가하는 편이 안전하다.

---

Personal Insights

1) 의료 AI(Medical AI) 관점

Hermes에서 가장 영감을 주는 부분은 “의료 지식” 그 자체보다 운영 구조다.

• Longitudinal context
  환자별 대화/작업 흐름을 세션 lineage와 검색 가능한 state로 관리하는 사고방식은, longitudinal clinical assistant 설계에 유용하다.
• Memory provider 분리
  generic file memory 대신, FHIR/EHR/clinical note store와 연결되는 규제 친화적 memory plugin 구조로 바꾸면 의료용 agent shell로 발전시킬 수 있다.
• Toolset gating
  처방/오더/민감정보 조회 같은 고위험 동작을 toolset + approval gate로 분리하는 방식은 의료 안전성 설계와 잘 맞는다.
• 보강해야 할 것
  PHI/PII redaction, structured audit log, role-based access control, deterministic approval, provenance capture, encryption-at-rest는 별도로 강화해야 한다.

기술적으로 빌려갈 만한 아이디어:
“모델 자체를 더 똑똑하게 만드는 것”보다, 상태 저장 + 승인 + 채널 통합 + 작업 재개를 먼저 해결하면 실제 임상 assistant의 품질이 급상승한다는 점.

2) Bioinformatics 관점

Bioinformatics/HPC 워크플로 관점에서는 이 저장소가 상당히 실용적인 출발점이 될 수 있다.

• SSH / Docker / Singularity 추상화
  로컬, 원격 서버, HPC 환경을 하나의 agent UX 아래에 넣기 좋다.
• Skills를 SOP로 활용 가능
  QC pipeline, variant annotation, literature triage, 결과 해석 루틴 등을 skill로 묶으면 “실험실 운영 절차”를 procedural memory로 만들 수 있다.
• Cron + batch runner 조합
  정기 리포트, nightly QC, benchmark regression, 자동 literature sweep에 잘 맞는다.
• Subagent 구조
  샘플별/환자군별/논문별로 병렬 분석을 던지는 패턴을 떠올리기 쉽다.

보강해야 할 것:
container digest pinning, reference genome/version provenance, random seed/parameter capture, artifact registry, reproducibility report가 꼭 추가돼야 한다.

기술적으로 빌려갈 만한 아이디어:
Bioinformatics agent는 자연어 인터페이스보다도 실행 환경 추상화 + 재현성 있는 도구 래핑 + 작업 기록 저장이 더 중요하다는 점을 이 프로젝트가 잘 보여 준다.

3) Autonomous Agent 관점

Autonomous agent 개발 참고용으로는 매우 좋은 사례다. 이유는 다음과 같다.

• Provider abstraction이 현실적이다.
  실제 에이전트는 모델 교체가 잦다. Hermes는 이를 runtime layer로 분리해 놓았다.
• Context hygiene를 진지하게 다룬다.
  compression, caching, iteration budget, fallback이 구조화돼 있다.
• 단일 채널 agent가 아니다.
  CLI/메신저/cron/IDE를 하나의 코어 루프에 붙이는 설계는 “agent OS” 관점에 가깝다.
• Trajectory / training 연결점이 있다.
  운영 시스템과 데이터 생성 파이프라인이 완전히 분리되지 않아 연구-운영 왕복이 쉽다.
• Interruptibility와 approvals가 있다.
  강한 자율성보다 중요한 것은 인간이 개입할 수 있는 통제점인데, 그 부분이 꽤 실전적이다.

내 기술적 해석:
Hermes는 “완성된 autonomous employee”라기보다,
장기 상태를 갖는 tool-using agent runtime을 어떻게 제품 형태로 감쌀 것인가에 대한 좋은 레퍼런스다.

4) 이 프로젝트에서 특히 참고할 만한 설계 원칙

1. Core loop는 공통 인프라로 유지하고, 도메인 로직은 외곽에 둔다.
2. 세션 검색/재개를 1급 기능으로 취급한다.
3. 툴 권한을 toolset과 approval로 분리한다.
4. 모델/채널/실행환경을 각각 별도 추상화 계층으로 둔다.
5. 연구용 trajectory와 실운영 agent를 완전히 단절시키지 않는다.

5) 개인적 결론

Hermes Agent는 “프롬프트 한 장으로 돌아가는 agent”보다 훨씬 무겁고, 그만큼 더 실전적이다.
특히 다음 세 가지를 배우기 좋다.

• stateful agent UX를 만드는 법
• tool/runtime/provider/channel을 서로 독립적으로 교체하는 법
• 장기 작업을 resume/search/compress 체계로 운영하는 법

의료 AI, Bioinformatics, Autonomous Agent 어느 쪽이든, 이 프로젝트를 그대로 복제하기보다 tool/plugin/memory/gateway 경계를 보고 자기 도메인용 runtime shell로 재구성하는 접근이 가장 생산적일 것이다.