Hermes 같은 코딩 에이전트, 작동 방식 뜯어보기
코드가 아니라 작동 논리로 읽는 Hermes — 입력(TIER 1) → 생각·행동(TIER 2) → 출력(TIER 3)에서 핵심인 가운데 에이전트 루프를 집중해 뜯어봅니다.
Hermes seen through its operating logic rather than its code. Instead of poking around at the code level, we take the architecture apart so you can see the whole thing you'd need to build an agent like it. The overall shape is a flow — bring input in (Tier 1) → think and act (Tier 2) → send output out (Tier 3) — and since the two ends (the entrance and the exit) are relatively simple, we'll focus on the agent loop (Tier 2) in the middle.
Naming the main modules
At the center sits the AI agent core, and it runs as an agentic loop. There are three ways to reach it.
- CLI — type
hermesin the terminal and you're in a conversation right away. - Gateway — always running, connected to messengers like Telegram, Slack, and email.
- API — call Hermes from your own application.
The important thing is that whether it's the CLI or a gateway wired into an external tool like Telegram, Hermes tries to pull in as much context as it possibly can.
Tier 2's agent loop comes with these things pre-built — tools, skills, memory, and files like soul.md and user.md that hold the agent's identity and information about the user. Memory splits two ways: external memory (third-party providers like Mem0 or SuperMemory) and internal memory (the session transcript, where the entire conversation piles up verbatim).
It looks simple from the outside, but the real substance is the core in the middle — the loop.
TIER 2 ① — The agent loop: the cycle that runs every time
The heart of the Hermes agent's logical structure is made up of the following steps. Every time the user sends a message, this loop goes around once — and in broad strokes it's simpler than you'd think.
- The user sends a message.
- Build context. It gathers up the internal memory it has and the pre-prepared prompts, and lays out "the current situation" as a single block. (What goes in is covered in ②.)
- Send the full context + message history to the LLM.
- If the LLM calls a tool, run the tool and return the result back to the LLM. And this repeats as long as the LLM judges it still needs to use tools. A single web search might be one or two loops; a complex task, many more — reading and writing files, running commands, searching.
- Once there's enough information that no more tools are needed, it gives the final response.
- Memory update. Responding to the user isn't the end. The agent analyzes the conversation it just had, asks "was there anything worth remembering?", and if so, writes it into memory.
Step 6 is what makes Hermes special. Because it leaves behind what it learned in each interaction, the next time you ask something similar it already knows — an agent that gets better the more you use it.
TIER 2 ② — Context: what goes into the LLM each turn
Loop step 2, "build context," is actually the single most important part that determines an agent's quality. Hermes's context is surprisingly minimal — it's built on top of a few markdown files.
soul.md— the agent's personality (system prompt). What tone it speaks in, what it's aiming for, how it behaves. Think of a well-written Claude system prompt. Right after install it's usually empty, and at first it only carries a default prompt along the lines of "I am Hermes, an always-on assistant." To use it properly, it's best to write your own, tailored to you.memory/user.md— information about you. Unlikesoul.md, the agent updates this automatically. When something like "I'm a software engineer" comes up in conversation, it recognizes that as a fact about you and records it here.memory/memory.md— arbitrary learned facts. Less about you, more about how to use tools, workflows, and useful things picked up mid-conversation. Consulting the goals (soul.md) as well, anything that seems worth remembering while working accumulates here. Think of it as a kind of experience points.- Past-session summaries — summaries of older conversations likely relevant to the current one, which appear only if you've set up external memory.
- Skill descriptions + tool descriptions — the list and descriptions of the skills and tools available.
- Recent messages — the conversation so far. But once it crosses a certain threshold, it goes in as a summary rather than in full.
The files the agent needs in order to remember are simple, but the 'context' built from them is not actually simple to assemble. Context is a combination of "identity + notes about you + arbitrary notes + a list of what it can do + the recent conversation," and this is passed to the LLM, whole, every turn. In effect, the agent re-reads all of its past information each time.
TIER 2 ③ — Context compression: how it holds up as things get long
When a conversation gets long, the context approaches the model's limit (the context window — typically 250K to 1M tokens). Hermes gets past this limit with compression.
- When: it triggers once you cross a configured ratio (85% by default). It's checked in two places — right before each turn (sending a message) and when the LLM throws a context-overflow error.
- What: it summarizes the earlier messages. It swaps the old messages for a single summary block attached to the context, and deletes the original messages.
- How it knows how full it is: on the first message there's no model response yet, so it can't know the exact token count — it estimates with character count ÷ 4 (running the tokenizer directly is accurate but too expensive). From then on, it just uses the
usage(tokens used) value the model returns alongside its response. - Structured summary: it's not a plain summary but structured into several sections — overall goal, constraints, completed actions, current state, progress, where it's stuck, key decisions made, resolved questions, relevant files, next steps, and so on. (It uses a far richer summary prompt than more minimalist agents do.)
Thanks to this compression, even a 12-hour-long task keeps going without the context breaking — though there's a catch: the quality depends on how well the agent summarizes its own work. The better a model is at 'logical thinking,' the better it'll do the context-summarization job.
TIER 2 ④ — Memory: three forms (the agent's foundation)
Because Memory — the memory system — is what both supplies context to the LLM and stores the LLM's output, the way it stores memory is ultimately the very foundation of the Hermes agent. Hermes's memory comes in three forms.
- Markdown files — the
soul.md,memory.md, anduser.mdwe saw earlier. They're always attached to the context, right after the system prompt. - SQLite database — since Hermes has to be able to load past conversations, it stores the full transcript of every session in SQLite. When it picks a conversation back up with the user, it pulls the history from here. There's also a bare-text table (a SQL table storing just plain text) that makes similarity search easy.
- External memory — external memory modules like Mem0, SuperMemory, or Honcho. Off by default. When turned on, after the first message it queries external memory to anticipate "what's the next question likely to be." This is similar to how people think: when a human hears a particular question, they answer it while simultaneously recalling similar past conversations. External memory works the same way — it generates questions similar to the one the user just asked, and searches the past DB with those questions.
TIER 1 — The way in: the gateway (a bit more detail)
The most interesting of the entrances is the gateway. It's also the part that made Hermes popular.
The gateway runs an asyncio loop and keeps listening to several messengers at once — Telegram, Discord, email, SMS, WhatsApp. Each messenger listens differently (some via webhooks, some a small loop that pokes the API once a second, some websockets), so each one has to be configured separately (register the bot ID, allowed user IDs, etc. with hermes setup gateway).
The key point is that the gateway doesn't just receive messages. When something comes in from Telegram, it receives only that one line, so the gateway has to reassemble the context and message history from scratch every time. It builds a session identifier like telegram + session id + …, pulls that conversation's entire history from SQLite, attaches it to the context, and hands it off to the core. In other words, gateway ↔ SQLite memory ↔ core loop run as one unit.
The gateway also has a session manager, so when you send a new message while the agent is mid-work, it decides whether to interrupt, steer, or queue it. On Telegram, /interrupt stops it, /steer redirects it, and just sending a message piles it onto the queue.
TIER 3 — The way out + automation: cron
On top of this, a module that's characteristic of Hermes is cron. It's what lets the agent perform a few automation tasks.
Think of the cron you'd use on a server — with one difference. Hermes's cron isn't tied to a server cron process; it's its own loop that runs every minute. Every minute a function called tick() runs, checks whether there's a job to execute at that moment, and runs it right away. Cron is what lets you automate things like "email me the AI news every morning" or "send my boss a report every Friday."
The whole thing on one page
In one sentence: Hermes is a loop that, for every message, lays out the context → hands it to the LLM to think → uses tools and feeds the results back, repeating → responds → and leaves what it learned in memory. The entrance (gateway) and exit (cron) are what feed messages into and out of that loop.
코드가 아니라 작동 논리로 보는 Hermes. 단순히 코드 레벨에서 알아보는 것이 아니라, 우리들이 실제 에이전트를 만드는데 필요한 전체 아키텍처를 알 수 있도록 그 구조를 뜯어봅니다. 전체적인 구조는 인풋을 들여오고(TIER 1) → 생각·행동하고(TIER 2) → 나가는(TIER 3) 흐름인데, 처음과 끝(입구·출구)은 비교적 단순하니, 가운데 **에이전트 루프(TIER 2)**를 집중해서 봅니다.
주요 모듈 정의하기
가운데에 AI 에이전트 코어가 있고, 이 코어의 에이전틱 루프(agentic loop) 방식으로 작동합니다. 여기에 접속하는 길은 세 가지예요.
- CLI — 터미널에
hermes라고 치면 바로 대화 시작 - 게이트웨이(gateway) — 항상 떠 있으면서 텔레그램·슬랙·이메일 같은 메신저와 연결
- API — 응용 프로그램에서 Hermes를 호출
중요한건, CLI든 아니면 텔레그램과 같이 외부의 툴과 연동하는 gateway든, 최대한 모든 컨텍스트를 가져오려고 노력한다는 것이다.
Tier2에 속한 에이전트 루프는 이런 것들이 pre-built 되어있어요 — 도구(tools), 기술(skills), 기억(memory), 그리고 에이전트의 정체성·사용자 정보를 담는 soul.md·user.md 같은 파일. 기억은 두 갈래인데, 외부 기억(mem0·supermemory 같은 외부 제공자)과 내부 기억(대화 전체가 그대로 쌓이는 세션 트랜스크립트)으로 나뉘어요.
겉보기엔 단순하지만, 진짜 알맹이는 가운데 코어, 즉 루프예요.
TIER 2 ① — 에이전트 루프: 매번 도는 사이클
Hermes 에이전트 논리 구조의 핵심은 다음 기능들로 이루어져 있어요. 사용자가 메시지를 보낼 때마다 이 loop가 한 바퀴 도는데, 크게 보면 생각보다 단순합니다.
- 사용자가 메시지를 보낸다.
- 컨텍스트를 빌드한다(build context). 갖고 있는 내부 기억과 미리 준비된 프롬프트를 끌어모아 "지금 상황"을 한 덩어리로 차려요. (무엇이 들어가는지는 ②에서)
- 전체 컨텍스트 + 메시지 히스토리를 LLM에 보낸다.
- LLM이 도구를 부르면, 도구를 실행하고 그 결과를 다시 LLM에 돌려준다. 그리고 LLM이 계속 도구를 써야 한다고 판단하는 한 이 과정을 반복해요. 웹 검색 한 번이면 한두 바퀴, 복잡한 작업이면 더 많이 — 파일을 읽고 쓰고, 명령을 실행하고, 검색합니다.
- 더 이상 도구를 사용할 필요 없을 정도로 정보가 충분하면 최종 응답을 준다.
- 메모리 업데이트(memory update). 사용자에게 응답을 한다고 끝이 아니에요. 에이전트가 방금 대화를 분석해서 *"기억해 둘 가치가 있는 게 있었나?"*를 보고, 있으면 기억에 적어둬요.
6번이 Hermes를 특별하게 만드는 지점이에요. 매 상호작용에서 배운 걸 남기니까, 다음에 비슷한 걸 물으면 이미 알고 있는 — 쓸수록 나아지는 에이전트가 되는 거죠.
TIER 2 ② — 컨텍스트: 매 턴 LLM에 무엇이 들어가나
루프 2번 "컨텍스트 빌드"가 사실 에이전트 품질을 좌우하는 가장 중요한 부분이에요. Hermes의 컨텍스트는 의외로 미니멀한데, 몇 개의 마크다운 파일을 기반으로 만들어집니다.
soul.md— 에이전트의 성격(시스템 프롬프트). 어떤 말투로, 무엇을 지향하며, 어떻게 행동할지. Claude의 잘 쓰인 시스템 프롬프트를 떠올리면 돼요. 설치 직후엔 보통 비어 있고, 처음에는 "나는 항상 켜져 있는 Hermes 비서다" 정도의 기본 프롬프트만 작성되어있어요. 제대로 쓰려면 자기한테 맞게 직접 작성하는게 좋습니다.memory/user.md— 당신에 대한 정보.soul.md와 달리 에이전트가 자동으로 갱신해요. 대화 중에 "나는 소프트웨어 엔지니어다" 같은 게 나오면, 그게 당신에 대한 사실임을 알아채고 여기에 적어둬요.memory/memory.md— 임의의 학습된 사실. 당신에 대한 정보라기보단, 도구 쓰는 법·워크플로우·대화 중 알게 된 유용한 것들. 목표(soul.md)도 함께 참고하여 작업을 하면서 기억할 만하다 싶으면 여기에 쌓여요. 일종의 경험치라고 생각하시면 됩니다.- 과거 세션 요약 — 외부 기억을 설정했을 때만 등장하는, 지금 대화와 관련 있을 법한 옛 대화의 요약.
- 스킬 설명 + 도구 설명 — 쓸 수 있는 기술·도구의 목록과 설명.
- 최근 메시지 — 지금까지의 대화. 단, 일정 임계치를 넘으면 통째로가 아니라 요약본으로 들어가요.
agent가 기억하기 위해 필요한 파일들은 간단하지만, 이 파일들을 이용한 '컨텍스트'는 사실 간단하게 만들어지지 않아요. 컨텍스트는 **"정체성 + 너에 대한 메모 + 임의 메모 + 할 수 있는 일 목록 + 최근 대화"**의 조합이고, 이게 매 턴 LLM에게 통째로 전달됩니다. 에이전트는 매번 과거의 전체 정보를 다시 보게 되는 셈이죠.
TIER 2 ③ — 컨텍스트 압축: 길어지면 어떻게 버티나
대화가 길어지면 컨텍스트가 모델의 한계(컨텍스트 윈도우, 보통 25만~100만 토큰)에 가까워져요. Hermes는 이때 **압축(compression)**을 통해 이 한계점을 극복합니다.
- 언제: 설정한 비율(기본 85%)을 넘으면 트리거. 체크 시점은 두 군데 — 매 턴(메시지 보내기) 직전과, LLM이 컨텍스트 초과 에러를 냈을 때.
- 무엇을: 이전 메시지들을 요약해요. 옛 메시지를 요약 한 덩어리로 바꿔 컨텍스트에 붙이고, 원래 메시지들은 삭제해요.
- 얼마나 찼는지 어떻게 아나: 첫 메시지 땐 아직 모델 응답이 없어 토큰 수를 정확히 모르니, 글자 수 ÷ 4로 어림잡아요(토크나이저를 직접 돌리면 정확하지만 너무 비싸서). 그 다음부터는 모델이 응답과 함께 돌려주는
usage(사용 토큰) 값을 그대로 써요. - 구조화된 요약: 단순 요약이 아니라 여러 섹션으로 구조화해요 — 전체 목표, 제약, 완료한 행동, 현재 상태, 진행 경과, 막힌 부분, 내린 핵심 결정, 해결된 질문, 관련 파일, 다음 단계 등. (더 미니멀한 에이전트들 보다 훨씬 더 풍부한 요약 프롬프트를 써요.)
이 압축 덕분에 12시간짜리 긴 작업도 컨텍스트가 끊기지 않고 이어집니다 — 다만 에이전트가 자기 작업을 얼마나 잘 요약하느냐에 품질이 달려 있다는 한계점이 있어요. 더 '논리적인 사고'가 좋은 모델일 수록 컨텍스트 요약 작업을 더 잘 하겠죠.
TIER 2 ④ — 기억: 세 가지 형태 (agent의 근간)
LLM에게 컨텍스트를 주기도 하고, LLM의 결과를 저장하는 것이 Memory, 즉 기억 체계이기 때문에, 이 기억 저장 방식이 결국 Hermes agent의 가장 근간이라고 할 수 있어요. 이 Hermes의 기억은 세 가지 형태가 있어요.
- 마크다운 파일 — 앞서 본
soul.md·memory.md·user.md. 시스템 프롬프트 바로 뒤에 항상 컨텍스트에 붙어요. - SQLite 데이터베이스 — Hermes는 과거 대화를 불러올 수 있어야 하니, 모든 세션의 **전체 트랜스크립트(full transcript)**를 SQLite에 저장해요. 그리고 사용자와 대화를 이어갈 때 여기서 히스토리를 끌어와요. 추가로 bare-text(순수 텍스트만 저장한 SQL 테이블)이 있어 유사도 검색을 쉽게 할 수도 있어요.
- 외부 기억(external memory) — mem0·supermemory·honcho 같은 외부 메모리 모듈. 기본적으로는 off 되어 있어요. 켜두면 첫 메시지 이후에 외부 기억을 조회해 "다음 질문은 뭘까"를 미리 떠올려요. 이건 사람이 생각하는 것과 비슷해요. 인간은 특정 질문을 들으면 그 질문에 답하면서 동시에 과거 비슷한 대화를 떠올리죠. 외부 메모리도 이런 방식으로 방금 사용자가 한 질문과 비슷한 질문을 생성하고, 그 질문들을 과거 DB로부터 서치를 합니다.
TIER 1 — 들어오는 길: 게이트웨이 (조금 더 자세히)
입구 중 가장 흥미로운 건 게이트웨이예요. Hermes를 대중적으로 만든 부분이기도 하고요.
게이트웨이는 asyncio 루프를 돌리면서 텔레그램·디스코드·이메일·SMS·왓츠앱 같은 여러 메신저를 계속 듣고 있어요. 각 메신저는 듣는 방식이 달라서(어떤 건 웹훅, 어떤 건 매초 한 번 API를 찔러보는 작은 루프, 어떤 건 웹소켓), 메신저마다 따로 설정해야 해요(hermes setup gateway로 봇 ID·허용 사용자 ID 등록).
핵심은, 게이트웨이는 메시지를 받기만 하는 게 아니라는 점이에요. 텔레그램에서 오면 그 한 줄만 받으니까, 게이트웨이가 컨텍스트와 메시지 히스토리를 매번 새로 조립해야 해요. 세션 식별자를 텔레그램 + 세션 id + …로 만들어 SQLite에서 그 대화의 히스토리를 통째로 끌어와 컨텍스트에 붙이고, 그걸 코어에 넘기죠. 즉 게이트웨이 ↔ SQLite 기억 ↔ 코어 루프가 한 묶음으로 돌아가요.
또 게이트웨이엔 세션 매니저가 있어서, 에이전트가 일하는 중에 새 메시지를 보내면 그걸 중단(interrupt)할지, 방향을 틀(steer)지, 대기열에 넣(queue)을지 정해요. 텔레그램에서 /interrupt를 쓰면 멈추고, /steer를 쓰면 방향을 틀고, 그냥 보내면 큐에 쌓이는 식이에요.
TIER 3 — 나가는 길 + 자동화: 크론
여기에 더해, Hermes의 특징적인 모듈이 크론(cron) 이에요. 이것 덕분에 몇 가지 자동화 기능을 수행할 수 있어요.
서버에서 쓰던 cron을 떠올리면 되는데, 한 가지 다른 점이 있어요. Hermes의 크론은 서버 cron 프로세스에 묶여 있지 않고, 자체적으로 매분 도는 루프예요. 매분 tick()이라는 함수가 돌면서, 그 순간에 실행할 잡(job)이 있는지 확인하고 바로 실행해요. 크론 덕분에 "매일 아침 AI 뉴스를 이메일로 보내줘", "매주 금요일 상사에게 보고 보내줘" 같은 걸 자동화할 수 있죠.
한 장 정리
한 문장으로: Hermes는 매 메시지마다 컨텍스트를 차리고 → LLM에 넘겨 생각하게 하고 → 도구를 쓰고 결과를 되먹여 반복하다가 → 응답하고 → 배운 걸 기억에 남기는 루프예요. 입구(게이트웨이)와 출구(크론)는 이 루프에 메시지를 넣고 빼주는 역할이고요.