뜯어본 것공개

Headroom

도입 검토였는데, 제 환경을 실제로 재보니 이 도구가 줄여 줄 대상이 존재하지 않았습니다.

도구도 기법도 안 가져왔고, 남은 건 규약 한 건입니다. 간판 수치 “6095% 압축”은 JSON 배열 기준이고 코딩 작업은 1520%이며, 소스 코드는 애초에 압축 대상이 아닙니다(설계상 통과시킵니다). 그리고 제 환경을 직접 재보니 캐시 재사용률이 이미 92.5~96.3%라 이 도구의 주 이득이 들어올 자리가 없었고, 압축할 대형 페이로드가 LLM 경로에 아예 없었습니다. 이 조사는 결론이 두 번 뒤집힌 뒤에야 끝났습니다.

에이전트 — Claude Code · Cursor · Codex · 내 코드 프롬프트 · 툴 출력 로그 · 검색 결과 · 파일 Headroom — 로컬 실행 데이터가 밖으로 안 나간다 LLM 프로바이더 압축된 프롬프트 + 원본 조회 도구 종류를 판정해 다른 압축기로 보낸다 구조화 데이터 통계 요약 + 이상치 보존 산문 별도 모델로 축약 소스 코드 통과 — 압축 안 함 검색 문서 통과 — 압축 안 함 핵심은 되돌릴 수 있다는 것 — 원본을 로컬에 두고, 모델이 필요하면 조회 도구로 다시 꺼낸다
라이브러리 · 프록시 · 에이전트 래핑 · MCP 서버 네 가지 모드로 붙일 수 있다. 파이썬과 러스트, Apache-2.0, 로컬 우선.

무엇을 하는 도구인가

에이전트와 LLM 사이에 끼어 앉아, 올려보내는 컨텍스트를 콘텐츠 종류별로 다른 압축기에 태우는 계층이다. 툴 출력, 로그, 검색 결과, 파일이 대상이다.

설계에서 제일 영리한 건 되돌릴 수 있다는 것이다. 압축하되 원본을 로컬에 캐시해 두고, 모델이 필요하다 판단하면 조회 도구로 다시 꺼낸다. 손실이 무섭지 않게 만드는 구조다.

붙이는 방법이 넷인데 성격이 아주 다르다.

모드 성격
라이브러리 내 코드에 직접 삽입. 통제권 최대
프록시 코드 수정 0. 다만 모든 트래픽이 여길 통과 → 단일 장애점
에이전트 래핑 프록시 기동 + 설정 주입까지 한 방에
MCP 서버 필요할 때만 호출. 가장 안전한 시작점

규모는 스타 63,331 / 포크 4,807이고 개설 6개월이다. 포크 비율이 13 대 1이라 구경꾼이 아니라 실제로 클론해서 쓰는 사람이 붙어 있다는 뜻이다. 다만 열린 이슈가 592건인데 라벨이 붙은 건 115건뿐이라 트리아지가 유입을 못 따라간다.

간판 수치와 내 작업 사이의 간격

의외로 공식 한계 문서가 정직하다. README보다 훨씬 믿을 만한 자료가 거기 있다.

콘텐츠 종류별 압축률 — 공식 한계 문서의 값 JSON dict 배열 86–100% 구조화 로그 82–95% 긴 에이전트 대화 56–81% 평문 · 문서 43–46% 짧은 대화 중앙값 4.8% — 사실상 무의미 소스 코드 통과 — 압축하지 않는다 (설계상 의도) 간판 “60–95%”는 맨 위 두 줄이다. 코드를 읽고 고치는 세션은 맨 아래 두 줄에 있다
같은 도구가 콘텐츠 종류에 따라 100%에서 0%까지 간다. 어느 줄에 있는지가 도입 판정의 전부다.

코드가 통과되는 건 버그가 아니라 의도다. 코드 압축기가 있지만 삼중 안전장치에 막혀 실전에서 거의 발동하지 않는다 — 짧으면 조용히 넘기고, 최근 몇 개 메시지의 코드는 절대 건드리지 않고, 직전 사용자 메시지에 “분석·리뷰·수정·디버그” 같은 단어가 있으면 대화 전체의 코드를 보호한다.

“코드 읽고 고쳐 줘” 세션은 압축이 거의 0이다. 문서 자신도 그렇게 적어 뒀다. 옳은 기본값인데, 간판 수치와 실제 코딩 작업 사이의 간격이 여기서 벌어진다.

깨본 결과 — 압축을 0% 했는데 비용이 7배였다

제3자가 실제 트래픽으로 대조 실험을 돌리고 청구 영수증까지 붙인 보고가 있다. 변수는 프록시를 끼우느냐 마느냐 하나뿐이었다.

호출당 미캐시 입력 총 비용
직결 ~2 $0.46
프록시 경유 ~3,000 $3.19 (6.9배)

그리고 같은 보고에서 절감률이 일곱 번 다 0.00%였다. 압축이 아예 발동하지 않았는데도 비용이 7배다. 즉 과압축이 원인이 아니라 배관이 원인이다.

기전은 이렇다. 프롬프트 캐시는 바이트가 똑같은 앞부분이라야 재사용된다. 앞부분이 매 턴 바뀌면 캐시를 읽는 대신 매번 새로 쓰게 되고, 쓰기가 읽기보다 비싸므로 절감이 아니라 증액이 된다.

더 나쁜 게 하나 있다. 프록시 자체 로그는 캐시 적중을 참으로 찍고 있었다. 청구서와 대시보드가 반대 방향을 가리켰다는 뜻이다.

그래도 “손해 확정”은 아니다. 그 측정은 한 버전에서만 나왔고 그 뒤 캐시 관련 결함 하나가 닫혔는데, 현행 버전은 아무도 재측정하지 않았다. 정확한 상태는 “이득도 손해도 미측정”이고, 이 구분을 뭉개면 안 된다.

반대 방향 발견도 하나 있다. 압축 엔진 자체는 코드를 뒤져 보면 난수가 0개다 — 같은 입력에 같은 출력이 나온다. 문제가 된 무시드 난수는 벤치마크 하네스 쪽이지 엔진이 아니다. 이 둘을 구분해 주지 않으면 “엔진도 못 믿을 것”으로 읽힌다.

그리고 제 1차 분석이 깨졌습니다

이 조사에서 제일 값나가는 부분이 여기다. 1차 분석은 단 하나도 직접 측정하지 않았다. 레포의 자기 문서와 제3자 이슈 보고를 읽고 옮긴 것뿐이었다. 재현 근거 없는 주장을 비판하면서, 제 분석 자체가 재현 안 된 주장 위에 서 있었다.

  • 기전을 틀리게 지목했다. “재직렬화가 캐시를 깬다”는 제 추론이었는데, 그 결함은 보고자 버전보다 18일 먼저 닫혀 있었다. 검증하지 않고 그럴듯한 기전을 붙인 것 — 제가 이 레포에 대해 지적한 것과 똑같은 종류의 잘못이다
  • “2~7배”를 현행 상태로 제시했다. 단일 버전 단일 보고인데 결론에 크기를 그대로 실었다
  • “두 명이 재확인”은 다른 증상의 확인이었다. 증거를 실제보다 두텁게 보이도록 뭉갰다
  • 이슈를 개수로 겁줬다. 중복·전언·리포트를 빼면 실제로 유효한 건 두 계열이었다
  • 불신을 한쪽에만 적용했다. 벤더의 유리한 표는 재현이 없다고 깎으면서, 같은 벤더가 말한 불리한 수치는 그대로 인용했다. 둘 다 출처가 같으니 함께 의심해야 맞다

마지막 항목이 제일 아팠다. 어느 쪽을 의심할지 고르는 순간, 나는 이미 결론을 정해 놓은 것이다.

실측이 조사를 끝냈다

1·2차는 전부 남의 수치였다. 3차에서 제 환경을 직접 쟀고, 그 결과 이 도구를 검토할 이유 자체가 사라졌다.

캐시가 이미 만점이었다. 세션 로그에 호출마다 캐시 읽기·쓰기·미캐시 입력이 남는다 — 새로 돌릴 필요 없이 과거 런의 영수증이 이미 디스크에 있었다.

세션 호출 미캐시 입력/콜 재사용률
메인 116 1.8 92.5%
대형(119MB) 5,388 300.7 95.9%
서브에이전트 3종 98~121 2.0 96.0~96.3%

위 대조 실험이 “정상”으로 제시한 직결 대조군이 호출당 ~2 토큰이었다. 제 파이프라인도 ~2다. 캐시 정렬로 가져올 이득이 0이고, 제가 “1순위·이득 최대”라고 적었던 항목은 이미 통과돼 있었다.

그리고 압축할 표적이 없었다. 큰 로그와 데이터 파일은 있는데 전부 코드가 먼저 축약해서 올린다 — LLM 경로에 대형 페이로드가 들어가는 지점이 존재하지 않았다.

판정 — 도구 0, 기법 0, 규약 1

도입도 기법 수확도 불필요. 채택된 건 규약 한 건이다.

못 재는 값은 지어내지 않는다. 추정치에는 신뢰구간과 [estimated] 라벨을 붙이고, 진짜로 재려면 10%를 손대지 않은 대조군으로 남긴다.

이 규약이 이 레포에서 나온 게 아이러니다. 이 레포는 반사실 절감을 신뢰구간까지 붙여 정직하게 보고하는 설계를 갖춰 놓고도, 정작 자기 간판 표는 재현 근거가 없고 대시보드는 청구서와 반대를 가리켰다. 측정 설계를 갖는 것과 그것을 자기 간판에 적용하는 것은 별개다 — 그리고 이 분석의 1차본이 정확히 같은 함정에 빠졌다.

재개 조건도 적어 뒀다. LLM에 대형 페이로드를 통째로 넣는 지점이 새로 생기거나, 현행 버전의 재측정이 나올 때. 조건 없는 기각은 반년 뒤 같은 조사를 반복하게 만든다.