Hermes Agent

• Hermes Agent는 Nous Research가 만든 자가 개선(self-improving) AI 에이전트이자 MIT 라이선스 오픈소스 프로젝트
• 경험에서 스킬을 만들고 사용 중에 그 스킬을 개선하는 내장 학습 루프(built-in learning loop)를 가진 에이전트
• 노트북에 묶이지 않고 $5 VPS·GPU 클러스터·서버리스 인프라에서 상시 동작하는 셀프 호스팅 자율 에이전트

해당 개념이 필요한 이유

• 컨텍스트 피로(Context Fatigue): 일반 챗봇은 세션이 끝나면 다 잊어버려 매번 설명을 반복해야 함 → 영속 메모리로 해결
• 지식 손실(Knowledge Loss): 어렵게 푼 문제의 해법이 사라짐 → 자동으로 재사용 가능한 스킬 문서(SKILL.md)로 저장
• 플랫폼 파편화: 도구마다 흩어진 대화 → Telegram·Discord·Slack·WhatsApp·Signal·CLI를 단일 게이트웨이로 통합
• 모델 종속(Lock-in): 특정 LLM에 묶임 → hermes model로 200+ 모델을 코드 변경 없이 교체
• 반복 작업: 수동 반복 → 자연어 cron 스케줄러로 무인 자동화

AS-IS (일반 챗봇/코파일럿)

sequenceDiagram
    autonumber
    participant U as 사용자
    participant Bot as 챗봇 (stateless)
    U->>Bot: 질문 & 배경 설명
    Bot-->>U: 답변
    Note over Bot: 세션 종료 → 기억 소멸
    U->>Bot: 다음 세션, 처음부터 다시 설명
    Note over U,Bot: 노트북에 묶임, 학습 없음

TO-BE (Hermes Agent)

sequenceDiagram
    autonumber
    participant U as 사용자 (Telegram/CLI 등)
    participant A as Hermes Agent (클라우드 상주)
    participant M as 메모리 / 스킬 저장소
    U->>A: 작업 요청
    A->>A: 도구 실행 & 작업 수행
    A->>M: 결과를 스킬(SKILL.md)·메모리로 저장
    A->>M: 과거 대화 검색(FTS5)으로 맥락 회수
    A-->>U: 결과 (어떤 플랫폼에서도 이어서)
    Note over A,M: 쓸수록 사용자 모델이 깊어지는 학습 루프

핵심 특징 6가지

1. 진짜 터미널 인터페이스(TUI): 멀티라인 편집, 슬래시 명령 자동완성, 대화 히스토리, 작업 중단·재지시, 스트리밍 도구 출력
2. 사용자가 있는 곳에서 동작: 6개 메신저 + CLI를 단일 게이트웨이 프로세스로. 음성 메모 전사, 플랫폼 간 대화 연속성
3. 닫힌 학습 루프(Closed Learning Loop): 주기적 메모리 보존 넛지, 복잡한 작업 후 자동 스킬 생성, 사용 중 스킬 자기 개선, FTS5 세션 검색 + LLM 요약
4. 스케줄 자동화: 플랫폼 전송이 가능한 내장 cron. 일일 리포트·야간 백업·주간 감사를 자연어로
5. 위임과 병렬화: 격리된 서브에이전트를 띄워 병렬 작업. RPC로 도구를 호출하는 파이썬 스크립트로 다단계 파이프라인을 무맥락 비용 턴으로 압축
6. 어디서든 실행: 6개 터미널 백엔드(local·Docker·SSH·Singularity·Modal·Daytona). Modal/Daytona는 유휴 시 휴면하는 서버리스 영속성

아키텍처 구성요소

실제 저장소 디렉토리 구조와 대응한다.

구성요소	디렉토리	역할
Agent 코어	run_agent.py, agent/	의사결정 루프 + 도구 실행 (AIAgent 클래스)
Gateway	gateway/	20+ 메신저를 잇는 통합 메시징 인터페이스
CLI / TUI	hermes_cli/, ui-tui/	터미널 진입점과 UI
Skills	skills/, optional-skills/	절차적 메모리, agentskills.io 표준 호환
Tools	tools/	웹 검색·이미지 생성·코드 실행·클라우드 브라우저 등 70+
Cron	cron/	스케줄 자동화
Providers	providers/	LLM 공급자 추상화(Nous Portal, OpenRouter 등)
State	hermes_state.py	SQLite 세션 저장소(~/.hermes/state.db)

---

학습 루프가 작동하는 방식 (개발자 관점)

Hermes가 “자가 개선(self-improving)“이라 불리는 핵심이다. 단순히 메모리를 저장하는 게 아니라, 매 턴 후 에이전트가 자기 자신을 포크(fork)해서 “이번 대화에서 기억하거나 스킬로 만들 게 있나?”를 스스로 평가하는 구조다. 아래 5개 메커니즘이 맞물려 돈다.

1. 에이전트 턴 루프 (AIAgent.run_conversation)

모든 것의 중심은 run_agent.py의 AIAgent 클래스다. 한 턴은 다음 순서로 처리된다.

run_conversation()
  1. task_id 생성 (없으면)
  2. 사용자 메시지를 대화 히스토리에 추가
  3. 시스템 프롬프트 빌드 또는 캐시 재사용 (prompt_builder.py)
  4. 프리플라이트 압축 필요 여부 확인 (컨텍스트 >50%)
  5. 대화 히스토리로 API 메시지 구성 (api_mode별 변환)
  6. ephemeral 프롬프트 레이어 주입 (예산 경고, 컨텍스트 압박)
  7. Anthropic이면 프롬프트 캐싱 마커 적용
  8. 중단 가능한(interruptible) API 호출
  9. 응답 파싱:
     - tool_calls 있으면 → 실행 후 결과 append → step 5로 루프백
     - 텍스트 응답이면 → 세션 영속화, 필요 시 메모리 flush, 반환

메시지는 내부적으로 항상 OpenAI 호환 포맷(role/content/tool_calls)으로 통일되며, chat_completions·codex_responses·anthropic_messages 세 가지 API 모드가 모두 이 포맷으로 수렴한다.

에이전트 레벨 도구

일부 도구는 일반 레지스트리(tools/registry.py)를 거치지 않고 run_agent.py가 직접 가로채서 에이전트 상태를 바꾼다. 학습 루프의 입구가 여기다.

도구	역할
memory	영속 메모리 파일에 글자 수 제한과 함께 기록
session_search	세션 DB에서 과거 대화 검색
delegate_task	격리된 컨텍스트로 서브에이전트 스폰
todo	에이전트 로컬 작업 상태

2. 백그라운드 자가 개선 리뷰 (agent/background_review.py) — 루프의 심장

턴이 끝나면 run_conversation이 spawn_background_review_thread를 호출해 데몬 스레드를 띄운다. 이 스레드의 동작이 Hermes 학습 루프의 본질이다.

• 대화 스냅샷을 **포크된 AIAgent**에서 **재생(replay)**하며 스스로에게 묻는다: “저장하거나 갱신할 스킬/메모리가 있는가?”
• 이 포크는 메모리·스킬 관리 도구만 화이트리스트로 허용한다. 그 외 모든 도구는 런타임에서 거부된다 (안전장치).
• 결과 쓰기는 메모리·스킬 저장소로 직행한다.
• 메인 대화와 프롬프트 캐시는 절대 건드리지 않는다 — 사용자 향 응답 속도와 캐시 적중률을 보존하기 위한 핵심 불변식(invariant)이다.
• 포크는 부모의 런타임(provider·model·base_url·credentials·캐시된 시스템 프롬프트)을 그대로 상속 → 동일한 prefix 캐시에 적중 → 저렴한 캐시 읽기.
• auxiliary.background_review.{provider,model}로 더 싼 모델에 리뷰를 위임할 수 있다(벤치마크 ~3–5× 절감). 다른 모델은 메인 캐시를 못 쓰므로, 전체 트랜스크립트 대신 압축 digest(최근 턴 원문 + 옛 턴 요약)를 재생한다.

sequenceDiagram
    autonumber
    participant U as 사용자
    participant Main as 메인 AIAgent
    participant Fork as 포크 AIAgent (데몬 스레드)
    participant Store as 메모리/스킬 저장소
    U->>Main: 메시지
    Main->>Main: 도구 실행 & 응답 생성
    Main-->>U: 응답 (즉시)
    Main->>Fork: spawn_background_review_thread(대화 스냅샷)
    Note over Fork: 도구 화이트리스트<br/>= memory + skill 관리 전용
    Fork->>Fork: 대화 재생 → "기억/스킬로 만들 게 있나?"
    Fork->>Store: memory.add / skill_manage.create·patch
    Note over Main,Fork: 메인 대화·프롬프트 캐시는<br/>절대 건드리지 않음

이 리뷰가 만든 메모리/스킬은 다음 세션의 시스템 프롬프트로 흘러 들어가 다음 대화를 더 똑똑하게 만든다. 이것이 “닫힌 루프”가 닫히는 지점이다.

3. 메모리: frozen snapshot 패턴

영속 메모리는 ~/.hermes/memories/의 마크다운 두 파일로 구성된다.

파일	용도	글자 제한
MEMORY.md	에이전트의 개인 노트 — 환경 사실, 컨벤션, 학습한 것	2,200자 (~800 토큰)
USER.md	사용자 프로필 — 선호, 커뮤니케이션 스타일, 기대	1,375자 (~500 토큰)

핵심은 frozen snapshot 패턴이다.

• 세션 시작 시 디스크에서 로드되어 시스템 프롬프트에 고정 블록으로 주입된다 (각 항목은 §로 구분).
• 세션 도중 memory 도구로 추가/교체/삭제하면 디스크에는 즉시 반영되지만, 시스템 프롬프트에는 다음 세션부터 나타난다. → LLM prefix 캐시를 깨지 않기 위함.
• memory 도구 액션: add / replace / remove (읽기 액션은 없음 — 이미 프롬프트에 있으므로). replace·remove는 짧은 고유 substring 매칭 사용.
• 글자 제한을 넘기면 조용히 버리지 않고 에러를 반환 → 에이전트가 같은 턴에서 항목을 통합·삭제한 뒤 재시도.
• 주입 전 보안 스캔(프롬프트 인젝션·자격증명 탈취·invisible Unicode)을 거친다.

4. 스킬: progressive disclosure

스킬은 ~/.hermes/skills/에 SKILL.md(YAML frontmatter + 마크다운)로 저장되며, agentskills.io 오픈 표준과 호환된다. 토큰 절약을 위해 **점진적 공개(progressive disclosure)**로 로드한다.

Level 0: skills_list()           → [{name, description, category}, ...]  (~3k 토큰)
Level 1: skill_view(name)        → 전체 내용 + 메타데이터
Level 2: skill_view(name, path)  → 특정 reference 파일

• 자동 생성: 복잡한 작업(5+ 도구 호출), 에러 발생, 비자명한 워크플로 발견 후 skill_manage 도구로 생성. 액션은 create/patch/edit/delete/write_file.
• 조건부 활성화: fallback_for_toolsets(해당 toolset 없을 때만 노출), requires_toolsets(있을 때만 노출).
• 자기 개선: 사용 중 발견한 개선점을 patch로 반영(토큰 효율적).
• 모든 슬래시 명령(/skill-name)으로 호출 가능. 설치 스킬은 보안 스캔 + 신뢰 레벨(builtin/official/trusted/community) 부여.

5. 세션 검색 (FTS5)

메모리가 “항상 들고 다니는 핵심 사실”이라면, 세션 검색은 “지난주에 그거 얘기했었나?”를 위한 도구다.

• 모든 CLI·메신저 세션이 SQLite(~/.hermes/state.db)에 저장되고, messages_fts 가상 테이블로 FTS5 전문 검색.
• session_search 도구는 실제 메시지를 그대로 반환 — LLM 요약·truncation 없음.
• ~20ms, LLM 호출 0회(무료), 용량 무제한. 메인 컨텍스트를 소비하지 않고 과거를 회수.

비교	영속 메모리	세션 검색
용량	~1,300 토큰	무제한
속도	즉시(프롬프트 내)	~20ms FTS5
비용	매 프롬프트 토큰	무료
관리	에이전트가 큐레이션	자동(전 세션 저장)

동의 게이트 (write_approval)

백그라운드 리뷰의 자동 쓰기가 부담스럽다면 memory.write_approval: true / skills.write_approval: true로 켤 수 있다. 켜면 포그라운드/백그라운드 쓰기가 모두 스테이징되어 /memory pending·/skills pending에서 승인 후에만 반영된다. 게이트웨이 채팅에는 💾 Memory updated 같은 알림이 뜬다(display.memory_notifications로 제어).

---

Gateway / 멀티플랫폼 (심화)

게이트웨이는 Hermes를 20+ 외부 메시징 플랫폼에 잇는 장기 실행 프로세스다. 본질은 멀티 어댑터 라우터(multi-adapter router) — 제각각인 플랫폼 API를 단일 에이전트 인터페이스로 정규화한다. 핵심 설계는 하나의 AIAgent 클래스가 CLI·gateway·ACP·batch·API를 모두 처리하고, 플랫폼 차이는 진입점(어댑터)에만 가둔다는 것이다.

sequenceDiagram
    autonumber
    participant P as 플랫폼 (Telegram 등)
    participant Ad as Platform Adapter
    participant GR as GatewayRunner._handle_message
    participant SS as SessionStore (SQLite)
    participant A as AIAgent
    P->>Ad: raw event
    Ad->>Ad: MessageEvent로 정규화 + 활성 세션 가드 확인
    Ad->>GR: 이벤트 전달
    GR->>GR: 세션 키 생성 + 인가(authorization) 확인
    alt 슬래시 명령
        GR->>GR: 커맨드 핸들러로 디스패치
    else 일반 메시지
        GR->>A: AIAgent 생성 후 run_conversation
        A->>SS: 대화 영속화
        A-->>GR: 응답
    end
    GR->>Ad: send_message
    Ad-->>P: 응답 전송

메시지 흐름과 대화 연속성

1. 플랫폼 어댑터가 raw 이벤트를 받아 MessageEvent로 정규화 (on_message()).
2. 세션 키로 라우팅 컨텍스트를 인코딩: agent:main:{platform}:{chat_type}:{chat_id} (예: agent:main:telegram:private:123456789). 키는 반드시 build_session_key()로 생성. 이 per-chat 세션 스토어 덕분에 메시지를 넘어 대화가 이어진다(일일 시각 또는 idle 타임아웃 정책 전까지).
3. 인가: per-platform allow-all → 플랫폼 allowlist → DM 페어링 → 글로벌 allow-all → 기본 거부 순으로 평가.
4. 슬래시 명령이면 커맨드 핸들러로, 아니면 AIAgent 인스턴스를 만들어 대화 실행.

2단계 메시지 가드 (중단·재지시)

에이전트가 실행 중일 때 들어오는 메시지는 두 단계 가드를 거친다.

• Level 1 — 베이스 어댑터(gateway/platforms/base.py): _active_sessions 확인. 활성이면 _pending_messages에 큐잉하고 interrupt 이벤트 set → 게이트웨이 러너 도달 전에 잡음.
• Level 2 — 게이트웨이 러너(gateway/run.py): _running_agents 확인. /stop·/new·/queue·/status·/approve·/deny는 특수 처리, 그 외는 interrupt() 트리거. /approve 등은 race를 피하려 인라인 디스패치.

어댑터 구조와 부가 메커니즘

• 대부분의 플랫폼은 plugins/platforms/<name>/adapter.py 플러그인 어댑터, 일부 레거시는 gateway/platforms/에 직접. 모두 BasePlatformAdapter를 상속하고 connect()/disconnect()/send_message()/on_message()를 구현.
• 토큰 락(acquire_scoped_lock): 두 프로필이 같은 봇 토큰을 동시에 쓰지 못하게 막음.
• Silence 토큰: 응답이 정확히 [SILENT]/SILENT/NO_REPLY면 전송을 억제하되 턴은 세션 히스토리에 보존.
• 백그라운드 유지보수: cron 틱(스케줄 점검), 세션 만료 정리, 만료 전 메모리 flush, 모델 목록 캐시 갱신.
• 프로세스 관리: 장기 실행 프로세스로 systemd(Linux)/launchd(macOS) 서비스 등록, PID 파일(~/.hermes/gateway.pid)은 프로필 스코프.

시작하기

# 설치 (Linux/macOS/WSL2/Termux)
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
 
hermes              # 대화형 CLI 시작
hermes model        # LLM 공급자·모델 선택
hermes tools        # 활성화할 도구 설정
hermes gateway      # 메신저 게이트웨이 시작 (Telegram, Discord 등)
hermes setup        # 전체 설정 마법사
hermes doctor       # 문제 진단

참고 문서

• Hermes Agent - GitHub (NousResearch)
• 공식 문서
• Agent Loop Internals
• Gateway Internals
• Persistent Memory
• Skills System
• agentskills.io - 스킬 오픈 표준
• 로컬 소스: run_agent.py, agent/background_review.py, hermes_state.py, gateway/run.py