개요
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/)이다.
동작 원리
- 페어링·핀 고정: 모든
tool_use는tool_use_id로tool_result와 페어링된다. 첫 메시지와 최신preserveRecentMessages개 메시지의 호출은 고정되어 절대 건드리지 않는다. - state 구성: Jev에게 보내는 state는 대화 전체(오래된 순)이며, 모든 도구 결과는
ok, 4213 chars (omitted)같은 짧은 메모로 치환된다. 도구 입력과 텍스트는 그대로 포함되고 요약되지 않는다. - 토큰 맞추기(단계적):
maxStateTokens(기본 25k)에 맞을 때까지 단계적으로 압축 — 도구 입력 1000→200→60자 절단 → 긴 텍스트 머리·꼬리만 남기기(오래된 비고정 메시지부터) → 오래된 비고정 메시지를[… N chars omitted …]메모로 축약 → 오래된 도구 호출을 한 줄(t12 Read file_path=src/a.ts → ok 480ch)로 축약 → 호출 없는 오래된 메시지 제거 → 호출만 있는 연속 구간을 한 항목으로 병합. 그래도 안 맞으면 compaction이 예외를 던진다. 토큰은 토크나이저 없이 추정(6글자당 1토큰, 숫자는 0.5토큰 등)한다. - 질문: 고정되지 않은 각 호출마다 Jev에게 두 개의
noul(이진) 질문을 던진다 — 호출 자체를 남길지, 결과를 원문 그대로 남길지. - 요청 분할: state+질문이
maxRequestTokens(기본 30k, Jev의 32k 요청 한도 아래)를 넘지 않도록 질문을 여러 요청으로 나눈다. 같은 전체 state가 매 요청에 반복 전송되며, 요청은 동시 실행 후 병합된다. - 판정 규칙(
keepThreshold기본 0.5):keepResult ≥ threshold면 호출+결과 유지, 아니면keepCall ≥ threshold면 호출만 유지하고 결과는truncateHeadChars(기본 300자)만 남긴 뒤 한 줄 메모 추가, 둘 다 아니면 호출+결과를 통째로 제거. - 메시지 목록을 재구성 — 콘텐츠가 모두 사라진 메시지는 제거되고, 손대지 않은 메시지는 동일 객체로 반환되며, 결과만 남고 호출이 없는 경우는 없다.
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 실패 시)로 표시된다.
옵션
| 옵션 | 기본값 | 설명 |
|---|---|---|
apiKey | TYPESAFE_API_KEY | TypeSafe API 키 |
model | jev-latest | Jev 모델명 |
baseUrl | https://api.typesafe.ai/v1/systemone | System One 엔드포인트 |
goal | 최근 사용자 프롬프트 3개 | state에 포함되는 진행 중인 작업 설명 |
keepThreshold | 0.5 | 호출/결과 유지 최소 확률 |
preserveRecentMessages | 6 | 절대 건드리지 않는 최신 메시지 수 |
maxStateTokens | 25000 | state 추정 토큰 상한 |
maxRequestTokens | 30000 | state+질문 배치 추정 상한 |
truncateHeadChars | 300 | 삭제된 결과 중 메모 앞에 남기는 문자 수 |
한계
- 텍스트 메시지 자체는 출력에서 제거·축소되지 않는다(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개. 댓글에서는 할 일과 완료 확인 명령을 디스크의 파일에 적어 두고 압축 직후 그 파일부터 다시 읽게 하는 운용을 함께 쓰라는 조언이 나왔다. 이 플러그인은 특정 기록을 우대하는 규칙이 없어서, 그 파일을 읽어 온 도구 결과도 지난 것으로 판정되면 빠질 수 있기 때문이다.