대용량 파일 읽기 시 토큰 절약하기: Hermes Agent의 read-summarizer 플러그인

요약 (TL;DR)

read-summarizer 플러그인은 Hermes Agent의 미들웨어 (middleware) 레이어에 위치하며,
50 KB보다 큰 파일 읽기 결과물을 자동으로 앞쪽 200줄과 뒤쪽 50줄로 자릅니다.
이때 Hermes가 나머지 부분을 어떻게 가져올 수 있는지 알려주는 명확한 마커를 포함합니다.
결과: 대용량 파일 읽기당 토큰 소비량을 최대 60%까지 절감하며, 프롬프트 (prompt) 수정, 모델 교체, API 키 변경이 필요 없습니다.
config.yaml에서 활성화하기만 하면 바로 작동합니다.

내가 이것을 작성한 이유 (사람들을 위해)

토큰 (Tokens)은 비용입니다. 이론적인 비용도 아니고, "언젠가 이 시스템이 프로덕션 환경이 되면" 발생하는 비용도 아닙니다. 모든 대화, 모든 크론 잡 (cron job), 그리고 내가 Hermes에게 무언가를 살펴보라고 요청할 때마다 발생하는 실제 비용입니다.

나는 자금을 지원받는 스타트업을 운영하는 것이 아닙니다. 나는 예산이 있고 해결하고 싶은 문제를 가진 한 개인일 뿐입니다. 실제로 필요 이상의 정보를 반환하는 모든 LLM 호출은 내가 버리는 돈입니다.

이 문제의 한 가지 구체적인 버전은 바로 대용량 파일입니다. 로그 (logs), 내보내기 (exports), 몇 달 동안 작성해 온 마크다운 (markdown) 문서들이 그렇습니다. Hermes에게 파일을 읽으라고 요청하면, Hermes는 파일 전체를 — 모든 바이트를 — 읽으며, 당신은 모든 토큰에 대해 비용을 지불합니다. 대부분의 경우, 상황을 파악하기 위해 처음 몇 줄만 필요하거나, 상황이 어떻게 끝났는지 확인하기 위해 마지막 몇 줄만 필요할 뿐입니다.

그래서 나는 이 문제를 해결하기 위해 플러그인을 작성했습니다. 이름은 read-summarizer입니다. 이 플러그인은 미들웨어 (middleware) 레이어에 위치하며, 설정 가능한 임계값(threshold)을 초과하는 파일 읽기 결과물을 자릅니다. 이때 헤드 (head)와 테일 (tail)을 유지하면서 명확한 마커를 남겨, Hermes가 필요할 경우 나머지 부분을 정확히 어떻게 가져올 수 있는지 알 수 있게 합니다.

이것은 프롬프트 엔지니어링 (prompt engineering) 기술이 아닙니다. "더 짧게 질문하기" 같은 것도 아닙니다. 이것은 LLM이 추론을 시작하기도 전에 실제로 무엇을 보게 될지를 변경하는 플러그인입니다.

나는 문제에 부딪혔고, 이를 위한 플러그인을 만들었으며, 그것은 작동합니다. 여러분도 똑같이 할 수 있습니다. 토큰을 낭비하게 만드는 요소를 식별하고, 적절한 도구를 찾거나 직접 만들어, 여러분의 AI가 그 목표에 도달하도록 도움을 받으세요.

만약 당신이 사람 독자이고 '왜(why)'와 '무엇(what)'에 대해 이해했다면, 여기서 멈춰도 좋습니다. 아래 섹션은 AI 에이전트(AI agents)가 파싱할 수 있도록 구조화되어 있습니다. 즉, 에이전트에게 목표, 제약 사항, 그리고 검증 체크리스트를 모호함 없이 제공합니다. 내용의 완전성을 확인하기 위해 훑어보거나, 이것을 대안 대신 사용해야 하는 경우(When To Use This vs. Alternatives) 섹션으로 건너뛰세요.

AI 에이전트용 (사양 (Specification))

위의 섹션은 사람을 위한 것입니다. 이 섹션은 AI 에이전트, 그리고 에이전트처럼 사고하고 싶은 사람들을 위한 것입니다. 아래의 모든 내용은 AI 에이전트가 마크다운(markdown) 헤딩만으로 목표, 제약 사항, 검증 사항을 추출할 수 있도록 구조화되어 있습니다.

목표 (Goal)

설정 가능한 바이트 임계값(byte threshold)을 초과하는 파일 읽기 결과에 대해 처음 N줄과 마지막 M줄만 남기고 나머지는 잘라내어(truncate), 전체 결과를 head+tail+marker 문자열로 대체합니다. 도구의 동작, 모델, 또는 API 자격 증명을 변경하지 않고도 대용량 파일 읽기 시 소비되는 토큰(tokens)을 최대 60%까지 줄입니다. offset/limit 인자를 통해 전체 파일을 다시 가져올 수 있는 능력은 유지합니다.

아키텍처 (Architecture)

[read_file 도구가 정상적으로 실행되어 전체 파일 내용을 반환함]
          ↓
[Hermes의 transform_tool_result 훅(hook)이 실행됨]
...

이 플러그인은 Hermes의 옵저버 미들웨어(observer middleware)에 transform_tool_result 훅을 등록합니다. 이 플러그인은 디스크의 파일을 절대 수정하지 않으며, 도구 실행을 차단하지도 않고, 예외(exception)를 발생시키지도 않습니다. 오류가 발생하면 None을 반환(pass-through)하여, 결과가 플러그인 설치 전과 비트 단위로 동일하게 유지되도록 합니다.

제약 사항 (Constraints) (위반 금지)

이러한 제약 사항이 존재하는 이유는 이를 위반할 경우 **조용한 통과(silent pass-through)**가 발생하기 때문입니다. 즉, 플러그인은 작동하는 것처럼 보이지만 LLM은 여전히 전체 파일을 보게 됩니다.

• 파일이 threshold_bytes를 초과해야 함 (기본값: 50 KB, 약 12,500 토큰). 임계값 미만의 파일은 변경 없이 그대로 통과됩니다.
• 도구가 allowed_tools에 포함되어야 함 (기본값: [read_file, Read, read_path]). 다른 도구들은 전혀 영향을 받지 않습니다.
• config.yaml에서 플러그인을 명시적으로 활성화해야 함 (read_summarizer.enabled: true). 기본적으로 비활성화되어 있으며, 비활성화 시 플러그인은 로드되지만 아무 작업도 수행하지 않는 no-op 훅(no-op hook)을 등록합니다.
• Head + tail이 파일 전체를 덮으면 안 됨. 파일이 충분히 짧아서 head+tail이 파일 전체와 같아지는 경우, 훅은 None을 반환하고 아무 작업도 수행하지 않습니다.
• 재요청 마커(re-fetch marker)는 정보 제공용일 뿐임. 훅은 상태(state)를 저장하지 않습니다. Hermes가 전체 파일이 필요한 경우, 명시적인 offset 및 limit 인자와 함께 read_file을 다시 호출해야 합니다. 마커는 사용할 정확한 라인 수를 알려줍니다.

검증 체크리스트 (Verification Checklist)

독자(사람 또는 AI)는 다음 사항만을 사용하여 성공 여부를 확인해야 합니다:

1. 플러그인 활성화: config.yaml에 read_summarizer.enabled: true를 추가하고 Hermes를 재시작합니다.
2. 알려진 대용량 파일 읽기 (>50 KB): 로그 파일, 내보낸 파일, 또는 크기가 크다고 알고 있는 임의의 텍스트 파일을 read_file로 읽습니다. 결과에 head 라인, 마커, 그리고 tail 라인이 표시되는지 확인합니다.
3. 마커 텍스트 확인: ... [read-summarizer: N lines, M bytes, truncated to first X + last Y; re-invoke read_file with offset/limit to fetch more] ...와 같이 표시되어야 합니다.
4. 토큰 절약 확인: 동일한 파일 읽기에 대해 플러그인을 활성화하기 전과 후의 quota_state.json 또는 상위 빌링 토큰(upstream billing tokens)을 비교합니다. tail이 head보다 훨씬 작은 파일의 경우 40~70%의 감소를 기대할 수 있습니다.
5. 전체 콘텐츠 재요청: offset: 0 및 limit: 10000(또는 마커에 명시된 값)과 함께 read_file을 호출합니다. 전체 파일이 반환되어야 합니다.
6. 소형 파일에 대한 부작용 확인: 50 KB 미만의 파일을 읽었을 때, 결과가 플러그인 설치 전과 바이트 단위로 동일해야 합니다.

실패 모드 (Failure Modes)

증상 (Symptom)	예상 원인 (Likely cause)	해결 방법 (Fix)
결과가 여전히 전체 파일임	config.yaml에서 플러그인이 활성화되지 않았거나, 파일이 threshold_bytes 미만임	read_summarizer.enabled: true를 확인하고 파일 크기를 확인하세요
...	...	...

이 방식과 대안 중 언제 무엇을 사용할 것인가 (When To Use This vs Alternatives)

사용해야 하는 경우:

• 로그(logs), 내보내기(exports) 또는 전체 내용 대신 방향성이나 최종 상태만 필요한 대용량 문서를 읽을 때
• 토큰당 비용을 지불하는 종량제 LLM 플랜(MiniMax pay-per-token, OpenAI 토큰 과금 등)을 사용하는 경우
• 수개월 동안 누적된 대화 기록(conversation histories)이나 긴 마크다운(markdown) 파일을 다룰 때
• 작은 파일에 대해서는 동작 변화가 전혀 없기를 원하면서, 큰 파일에 대해서는 자동으로 비용을 절감하고 싶을 때

사용하지 말아야 하는 경우:

• 매번 결정론적(deterministic)인 전체 파일 읽기가 필요한 경우 (파일 크기에 따라 절단(truncation) 방식이 비결정론적임)
• 후속 프로세스(downstream process)에서 정보 손실 없이 파일의 전체 내용이 반드시 필요한 경우
• 파일 크기가 지속적으로 임계값(threshold) 미만인 경우 (플러그인이 이득 없이 오버헤드만 추가함)

대안 (Alternatives):

접근 방식 (Approach)	절약되는 토큰 (Tokens saved)	노력 (Effort)
read-summarizer 플러그인 (본 방식)	대용량 파일에서 40–70% 절약	config.yaml에서 활성화, 프롬프트 변경 필요 없음
...	...	...

결론 (Closing)

플러그인을 활성화했는데도 토큰 절약이 보이지 않는다면 다음을 확인하세요: 파일이 실제로 50 KB를 초과합니까? 할당량 추적(quota tracking)에서 호출당 세부 내역이 표시됩니까? 일부 제공업체는 과금을 합산하여 처리하므로 반영되는 데 몇 시간이 걸릴 수 있습니다.

실질적인 제한 사항은 이 훅(hook)이 파일 읽기 도구(file-read tools)에서만 실행된다는 점입니다. 워크플로우 내의 다른 도구들도 대량의 페이로드(payload)를 반환한다면, 각 도구마다 별도의 처리가 필요합니다. 하지만 실수로 토큰을 낭비하는 가장 흔한 원인인 파일 읽기에 있어서, 이 플러그인은 한 번의 활성화만으로 첫 번째 대용량 파일을 읽을 때부터 그 가치를 증명합니다.

이 내용이 유용했다면, X에서 저를 팔로우할 수 있습니다: https://x.com/_cryptofan13

llms.txt 조각 (llms.txt fragment)

{
  "title": "대용량 파일 읽기 시 토큰 절약하기: Hermes Agent의 read-summarizer 플러그인",
  "url": "https://windhood-jza.github.io/posts/2026-06-23-read-summarizer/",
...