개요

tamaratran/fast-jev-compaction은 Claude Code의 컨텍스트 압축(compaction) 시 기본으로 쓰는 “LLM이 오래된 턴을 요약”하는 방식 대신, TypeSafe Jev(형식화 판정 모델)에게 각 도구 호출·결과를 유지할지 묻고 그 답에 따라 그대로 삭제하거나 원문 그대로 남기는 npm 라이브러리 + Claude Code function-hook 플러그인이다. 요약이 아니므로 파일 경로·정확한 에러 메시지·제약 조건 같은 디테일이 재작성 과정에서 사라지지 않는다는 것이 핵심 주장.

한 줄 핵심: 대화를 다시 쓰지 않고 지우기만 한다 — Jev가 “이 도구 호출/결과가 아직 필요한가”를 판정하고, 남기기로 한 것은 100% 원문 그대로 둔다.

배경

Claude Code의 기본 compaction은 오래된 턴을 LLM 요약으로 대체하는데, 요약은 본질적으로 손실이 있다 — 나중에 중요해질 수 있는 파일 경로·정확한 에러 문구·명령어가 요약 과정에서 빠질 수 있다. 이 저장소는 요약을 아예 하지 않고, Jev가 불필요하다고 판단한 도구 호출/결과만 삭제하는 방식으로 이 손실을 없애려 한다. src/는 순수 npm 라이브러리이고 저장소 루트 자체가 이를 사용하는 Claude Code 플러그인(hooks/, .claude-plugin/)이다.

동작 원리

  1. 페어링·핀 고정: 모든 tool_use는 tool_use_id로 tool_result와 페어링된다. 첫 메시지와 최신 preserveRecentMessages개 메시지의 호출은 고정되어 절대 건드리지 않는다.
  2. state 구성: Jev에게 보내는 state는 대화 전체(오래된 순)이며, 모든 도구 결과는 ok, 4213 chars (omitted) 같은 짧은 메모로 치환된다. 도구 입력과 텍스트는 그대로 포함되고 요약되지 않는다.
  3. 토큰 맞추기(단계적): maxStateTokens(기본 25k)에 맞을 때까지 단계적으로 압축 — 도구 입력 1000→200→60자 절단 → 긴 텍스트 머리·꼬리만 남기기(오래된 비고정 메시지부터) → 오래된 비고정 메시지를 [… N chars omitted …] 메모로 축약 → 오래된 도구 호출을 한 줄(t12 Read file_path=src/a.ts → ok 480ch)로 축약 → 호출 없는 오래된 메시지 제거 → 호출만 있는 연속 구간을 한 항목으로 병합. 그래도 안 맞으면 compaction이 예외를 던진다. 토큰은 토크나이저 없이 추정(6글자당 1토큰, 숫자는 0.5토큰 등)한다.
  4. 질문: 고정되지 않은 각 호출마다 Jev에게 두 개의 noul(이진) 질문을 던진다 — 호출 자체를 남길지, 결과를 원문 그대로 남길지.
  5. 요청 분할: state+질문이 maxRequestTokens(기본 30k, Jev의 32k 요청 한도 아래)를 넘지 않도록 질문을 여러 요청으로 나눈다. 같은 전체 state가 매 요청에 반복 전송되며, 요청은 동시 실행 후 병합된다.
  6. 판정 규칙(keepThreshold 기본 0.5): keepResult ≥ threshold면 호출+결과 유지, 아니면 keepCall ≥ threshold면 호출만 유지하고 결과는 truncateHeadChars(기본 300자)만 남긴 뒤 한 줄 메모 추가, 둘 다 아니면 호출+결과를 통째로 제거.
  7. 메시지 목록을 재구성 — 콘텐츠가 모두 사라진 메시지는 제거되고, 손대지 않은 메시지는 동일 객체로 반환되며, 결과만 남고 호출이 없는 경우는 없다.

Jev 실패, 형식이 어긋난 응답, API 키 누락, 맞출 수 없는 히스토리는 모두 예외를 던진다 — 폴백은 호출자(또는 Claude Code 훅)의 책임이다.

사용법

라이브러리

npm install fast-jev-compaction
export TYPESAFE_API_KEY=...
import { compactMessages, reductionRatio, type Message } from 'fast-jev-compaction';
 
const result = await compactMessages(transcript, { preserveRecentMessages: 4 });
if (reductionRatio(result) < 0.25) {
  // 줄어든 게 별로 없으면: 원본 유지 또는 다른 요약 방식 사용
}

Message는 Claude Code SessionMessage의 부분집합이라 세션 트랜스크립트를 그대로 넣을 수 있다. 자체 전송 계층을 붙이려면 JevAsker(ask(state, questions) 메서드 1개)를 구현해 compact(messages, asker, options)를 호출하면 된다. buildJevRequest, parseJevResponse, collectToolCalls, fitState, batchCalls, decideCall, applyDecisions 등 내부 빌딩 블록도 모두 export된다.

Claude Code 플러그인

저장소 루트 자체가 Claude Code function-hook 플러그인이다(hooks/fast-jev.ts가 session.compact 트랜스크립트를 src/로 넘기고, 에러/부족한 축소율 시 Claude Code 기본 요약으로 폴백). Function hooks는 Claude Code 2.1.274+의 얼리 액세스 기능이라 ~/.claude/settings.json에 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS: "1" opt-in이 필요하다.

claude plugin marketplace add tamaratran/fast-jev-compaction
claude plugin install fast-jev-compaction@fast-jev-compaction

설치 후 /compact(및 자동 압축)가 Jev를 거친다 — 토스트가 fast-jev-compaction: kept N/M messages, no summary (…)(요약 대신 pruned 히스토리 사용)이거나 fallback to built-in summary (…)(짧은 세션이거나 Jev 실패 시)로 표시된다.

옵션

옵션기본값설명
apiKeyTYPESAFE_API_KEYTypeSafe API 키
modeljev-latestJev 모델명
baseUrlhttps://api.typesafe.ai/v1/systemoneSystem One 엔드포인트
goal최근 사용자 프롬프트 3개state에 포함되는 진행 중인 작업 설명
keepThreshold0.5호출/결과 유지 최소 확률
preserveRecentMessages6절대 건드리지 않는 최신 메시지 수
maxStateTokens25000state 추정 토큰 상한
maxRequestTokens30000state+질문 배치 추정 상한
truncateHeadChars300삭제된 결과 중 메모 앞에 남기는 문자 수

한계

  • 텍스트 메시지 자체는 출력에서 제거·축소되지 않는다(Jev가 보는 state에서만 축약됨) — 삭제 후보는 도구 호출·결과뿐이다.
  • 토큰 크기는 토크나이저가 아닌 문자 수 추정치.
  • 보정은 요청 단위이며, 확률이 “삭제해도 안전하다”는 증명은 아니다 — 에이전트는 언제든 도구를 다시 실행할 수 있다는 전제.
  • 매 요청마다 전체 state를 다시 보내므로, state 상한 근처의 히스토리는 질문 몇 개당 요청 1개씩 비용이 든다.
  • 외부 의존성: TypeSafe(api.typesafe.ai)의 유료 Jev API 키가 필수이며, Claude Code function hooks 자체가 2.1.274+ 얼리 액세스 기능(opt-in 플래그 필요)이라 실험적 단계로 다뤄야 한다.

관계

  • 기반 모델: TypeSafe Jev — System One 결정 모델, /v1/systemone 프로토콜로 형식화된 Choice/Noul/Score 질문에 확률로 응답. 같은 API를 쓰는 다른 사례는 2026-09-19-awesome-jev 참조.
  • 호스트 플랫폼: moc-claude-code — Claude Code function-hook 생태계의 일부.
  • 후속·파생: 2026-09-30-github-hyunjunjeon-jev-context — 이 저장소의 구조(호출 짝짓기·고정·state 맞춤)를 그대로 가져와 verbatim 압축 모듈로 재구현하고, 같은 압축 문제를 창 관리(read gate·prune·report·retain·timing)까지 넓혔다.
  • 참조 저장소: tamaratran/jev-pruner (MIT) — Jev 클라이언트·청크 트리머·보존 규칙. jev-context가 070d4af 고정 커밋으로 가져온다.
  • 관련 위키 페이지: 2026-09-19-awesome-jev (Jev 기반 오픈소스 64개 디렉토리 — 이 저장소도 “통합” 카테고리에 등재), moc-ai-coding

참고

  • 저장소: https://github.com/tamaratran/fast-jev-compaction
  • 라이선스: MIT
  • 별 6,995 · 주 언어: TypeScript
  • 생성: 2026-09-17, 최근 푸시: 2026-09-18
  • 소유자: tamaratran
  • 한국어 소개: @nangman_muk Threads (2026-09-25) — 압축 요약의 손실(파일 경로·정확한 에러 문구 유실) 문제와 설치 2단계(claude plugin marketplace add tamaratran/fast-jev-compaction → claude plugin install)를 소개했다. 게시 시점 별 6,740개. 댓글에서는 할 일과 완료 확인 명령을 디스크의 파일에 적어 두고 압축 직후 그 파일부터 다시 읽게 하는 운용을 함께 쓰라는 조언이 나왔다. 이 플러그인은 특정 기록을 우대하는 규칙이 없어서, 그 파일을 읽어 온 도구 결과도 지난 것으로 판정되면 빠질 수 있기 때문이다.