원문: HyunjunJeon/jev-context · 수집일: 2026-09-30 · Stars 3 · Forks 0 · JavaScript · 저장소 생성 2026-09-29, 커밋 4건 — 수집 기준 하루 된 프로젝트라 실사용 데이터가 아직 없다.

개요

Claude Code와 Codex에서 도는 컨텍스트 관리 플러그인이다. 목표는 두 가지다 — 압축이 최대한 늦게 오게 하고, 압축이 와도 다음 단계에 필요한 원문이 살아남게 한다. 판단이 필요한 몇 곳에서만 TypeSafe의 Jev 모델을 호출한다.

fast-jev-compaction과 같은 문제를 다루지만 접근이 정반대다. 앞선 프로젝트는 압축 자체를 Jev 판정으로 대체했고, 이 저장소는 압축은 호스트에 맡기고 압축 전후의 창 관리(읽기·출력·서브에이전트 보고·캐시 타이밍)를 규칙과 소량의 Jev 판단으로 처리한다. 기본 설정에서 Jev 호출은 압축마다 최대 1회다.

설계 원칙은 세 가지다.

  1. 들어오는 순간에 한 번 정하고, 그 뒤로는 고치지 않는다. 이미 보낸 기록을 고치면 프롬프트 캐시가 깨지고, Opus 5.5·Sonnet 5.5에서는 뒤따르는 thinking 블록까지 무효가 된다(preserved thinking).
  2. 숨기기 전에 원문을 먼저 저장한다. 줄인 결과에는 항상 원문 경로가 붙는다.
  3. Jev는 기본으로 켜 두되 필요할 때만 부른다. 규칙으로 정할 수 없고 Jev의 답이 결과를 바꿀 수 있는 곳에서만 요청을 보낸다.

프로젝트의 목적

실제 설계의 중심은 Jev를 많이 쓰는 것이 아니라 Jev 호출 횟수를 억제하는 것이다. 기본 설정에서 압축마다 Jev 요청은 많아야 1번이다. 판단 로그(logs/decisions.jsonl)의 carryAsked·carried·carryScores·callsAsked·callsTooSmall·jevRequests로 무엇을 물었고 무엇을 건너뛰었는지 남긴다.

여기서 얻은 경험칙이 노트의 가장 재사용 가치 높은 부분이다 — Jev는 “답의 근거가 대화 안에 있는 질문”에서만 잘 판단한다. 근거가 보일 때는 읽기 게이트 순위 일치도가 0.75였고(목적이 안 보이는 경우 0.46–0.57), 다음에 편집할 파일 점수는 0.38–0.55(로그는 0.11 이하), 사용자가 닫은 주제는 0.87–0.94(넘어가기만 한 주제 0.50–0.57)로 갈렸다. 반면 “나중에 필요할까”처럼 미래를 예측하게 하는 질문에서는 점수가 한쪽으로 몰렸고, retain hybrid·jev와 prune의 Jev 단계는 값 청크를 가려내지 못해 기본값에서 꺼 두었다.

실제 용도

모듈 6종이 각각 다른 훅 이벤트를 붙든다.

모듈하는 일Claude Code 2.1.284Codex 0.158.0
읽기 게이트오케스트레이터가 100줄 이상 한 번에 읽으려 할 때 Jev가 “이번 단계에 전체가 필요한가”를 판단. 불필요하면 줄 번호가 달린 개요와 함께 한 번 되돌려 좁혀 읽게 한다. 같은 읽기를 다시 요청하면 통과PreToolUse(Bash|Read) 거부PreToolUse(Bash) 거부
prune도구 출력이 들어올 때 반복 줄을 규칙으로 접고 원문 경로를 남김PostToolUse(Bash) updatedToolOutput실행기 감싸기(옵트인)
report서브에이전트에게 Summary/Details 분리를 지시하고 오케스트레이터에는 Summary와 파일 경로만 전달PreToolUse(Agent|Task|SubagentHandback)SubagentStop에서 한 번 되돌림
retain압축은 호스트 요약이 하고, 옆에 원문을 덧붙임. 규칙으로 튀는 줄을 고르고 Jev 1회로 “다음 단계가 편집할 출력”을 통째로 붙임PreCompact → SessionStart(compact)같음
timing프롬프트 캐시가 식었을 때만 압축을 권하고, 재개로 압축이 되돌려진 걸 감지SessionStart(resume)·UserPromptSubmit없음
verbatim (옵트인)요약 없이 원문만 유지하는 압축. 옛 결과와 닫은 주제를 지우고 글은 그대로 둠function hook session.compact없음

Codex에는 두 가지 구조적 제약이 있다. 셸 출력을 훅에서 바꿀 수 없어 prune은 JEV_CONTEXT_CODEX_WRAP=on으로 bin/codex-run.mjs 실행기를 감싸는 방식으로만 작동하고(감싼 명령은 승인을 건너뛴다 — 그래서 기본값이 off), report 분리는 미구현이다. Codex 서브에이전트의 지시문이 암호화되어 훅이 읽거나 덧붙일 수 없고, SubagentStop은 결과 전체를 받지만 전달 본문을 바꿀 수 없기 때문이다.

retain: 이 저장소의 핵심 발견

retain의 효과는 셸로 읽은 파일에서 드러났다. “다음 단계가 편집할 출력”을 Jev 1회로 골라 원문 그대로 붙이는 것이 핵심이다.

셸로 읽은 파일을 압축 뒤 다시 읽지 않고 다섯 줄 인용하게 한 실험(저자 라이브 측정, Claude Code 2.1.284 / Codex 0.158.0)에서, 규칙만 쓰면 1/5였고 Jev 1회를 더한 기본 설정은 5/5였다(Claude Code·Codex 각 2회 모두). Jev 점수는 다음에 편집할 파일 0.38–0.55, 로그 0.11 이하로 갈려 임계 0.3이면 분리된다. 도구 출력에만 있던 해시를 묻는 시험에서도 내장 요약만으로는 1/3, 규칙 retain은 2/2였다(Sonnet 5.5, 173k 토큰 세션).

Codex 포크 파싱도 이 저장소에서 고친 실제 버그다. Codex 0.158의 codex exec fork는 부모 대화를 복사하지 않고 참조만 남기는데(session_meta.history_base), 초기 구현은 이 참조를 따라가지 않아 포크 세션의 PreCompact가 물려받은 도구 출력을 하나도 못 봤다(nothing_to_ask). 지금 파서는 부모 rollout을 찾아 그 번호까지의 줄을 앞에 붙인다.

verbatim: 압축은 0.3초, 값 보존은 동등

fast-jev-compaction 구조(호출 짝짓기·고정·state 맞춤)를 그대로 쓰되 질문과 고정 범위를 측정에 맞춰 바꾼 버전이다. Claude Code early-access function hook이라 JEV_CONTEXT_COMPACT=verbatim CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 플래그가 필요하다. 요약 모델 호출 없이 0.3초에 끝난다.

Sonnet 5.5가 7턴 동안 ledger-tool 명령 14개를 실행한 173k 토큰 세션을 방식별로 fork해 비교한 결과다.

방식값(5개 중)압축 시간압축 후 토큰다음 요청
내장 요약 + retain(규칙)5, 523.9–28.0초3,370–3,69820.5k–21.0k
원본 fast-jev-compaction4, 40.23–0.27초17,055–17,06548.8k
verbatim 1차(원본 고정 범위·질문)5, 5, 50.32–0.35초18,295–18,36251.1k–51.3k
verbatim (현재)5, 5, 50.30–0.34초6,531–7,18328.1k–29.0k

원본의 고정 범위와 질문을 그대로 쓴 1차 버전은 값은 지켰지만 압축 후 토큰이 18k로 원본만큼 남았다. 고정 범위와 질문을 측정에 맞춰 바꾼 현재 버전이 이를 6.5k–7.2k로 줄였다. 같은 입력이면 결과도 같다(두 번째 실행의 첫 요청이 28,998토큰을 캐시에서 읽고 쓰기 0). 내장 요약은 실행마다 글이 달라 이런 캐시 재사용이 없다.

주제 폐기 판단은 질문 설계가 결과를 갈랐다. 여러 주제가 섞인 77k 토큰 세션에서:

  • “남은 작업이 이 주제로 돌아오나”(0.5 미만이면 지움) → 닫지 않은 주제까지 지워 RELEASE ID를 잃었다(0/2).
  • “사용자가 이 주제를 닫았나”(0.8 이상이면 지움) → 닫은 주제만 지워 답 5개 전부 유지, 다음 요청 25.8k로 가장 낮음.

“닫았나” 질문에서 닫은 주제는 0.87–0.94, 넘어가기만 한 주제는 0.50–0.57로 갈려 0.8 기준이 둘을 나눈다. 미래를 예측하게 하는 질문보다 대화에 근거가 있는 질문이 잘 갈린다는 앞의 경험칙이 여기서도 확인된다.

읽기 게이트: 효과와 실패 지표

실제 과제에서는 쓸 만했지만 기록 재생에서는 약했다. 저자가 실패를 가늠할 지표까지 스스로 제시한 점이 눈에 띈다.

  • 실제 과제 A/B(과제 4개, Sonnet 1회·Opus 2회, 끔 대 켬): 정답률 12/12 대 12/12로 동일. 게이트는 6번 발동해 특정 내용을 찾는 읽기 3건은 막고(p 0.07–0.16) 전체 요약이 필요한 읽기 3건은 통과시켰다(p 0.78–0.82). Jev 지연 0.23–0.30초. Opus 한 과제에서 도구 결과가 24,216자에서 4,018자로 줄었다.
  • 다만 원래 좁혀 읽는 Sonnet에서는 같은 거부가 +567자 손해였다.
  • 실제 기록 재생에서는 판정이 약했다. 28건 중 57%를 되돌렸고 사후 미사용 비율은 되돌린 쪽 24%, 통과 쪽 35% — 순위 일치도 0.56은 우연 수준. 원인은 긴 세션에서 읽기 직전 목적이 기록에 거의 남지 않는다는 것(thinking은 기록되지 않는다).
  • 저자가 제안한 관찰 지표: 로그의 denied 대비 repeated(같은 읽기를 다시 요청해 통과한 수). 이게 높으면 문턱을 올리거나 게이트를 끄라고 한다.

report: 크기는 줄지만 판단은 그대로

Summary/Details 분리 A/B(과제 3개 × 2회):

분리 끔분리 켬
오케스트레이터 도착 보고53,964자12,913자
정답 판정5/65/6
비용$1.18$1.14

Summary 예산 800/1,500/3,000자 비교에서는 3,000자만 6/6이었지만 비용이 $1.29로 올랐고, 반복 2회라 근거가 부족해 기본값은 1,500자로 두었다. 긴 세션 테스트에서는 보고 1건이 약 80% 줄었지만 위임 1회당 컨텍스트 증가량은 10%만 줄었다(3,172 → 2,839토큰, 조건별 1회라 방향만 참고).

저자가 검토하다 보류한 것이 더 흥미롭다. 보고가 지시에 제대로 답했는지 Jev로 검사하는 단계(0단계)를 구상하고 실제 멀티에이전트 세션의 후속 지시 31건을 분석했는데, 보고가 지시에 답하지 않은 경우가 0건이었다. 잡을 몫이 없어 hook에 연결하지 않았다. 저자의 결론은 이렇다. “이 워크플로에서 보고 채널의 문제는 품질이 아니라 크기다.”

기술 구조와 운영 경계

  • Node .mjs 모듈 구성: 이벤트별 처리는 src/handlers/(prune·readgate·report·retain·timing·wrap), 규칙과 Jev 판단은 src/core/(reduce·prune·retain·carry·verbatim·readgate·jev·config·budget·acceptance 등), 대화 기록 파싱은 src/transcript/(claude·codex)에 있다.
  • 외부 의존성은 두 저장소뿐: jev-pruner(070d4af)와 fast-jev-compaction(e3f262a)를 npm run setup이 고정 커밋으로 받아 vendor/에 빌드한다.
  • 설치는 저장소가 아니라 package/jev-context/에서 한다. 마켓플레이스가 폴더를 통째로 복사해 vendor/*/node_modules 169MB와 logs/ 평가 데이터가 딸려가고, git에서 바로 받으면 vendor/가 없어 훅이 import 단계에서 실패한다. npm run package가 약 0.7MB 설치 폴더를 만든다.
  • Jev로 나가는 데이터: Jev는 셸에 TYPESAFE_API_KEY가 있으면 켜진다. 판단 로그에는 키·프롬프트·출력 내용을 남기지 않지만, 대화 내용은 Jev로 간다. 읽기 게이트는 대화 일부와 파일 개요를, retain·verbatim은 대화 전체(도구 결과는 크기만)와 도구 호출 입력을 보낸다. 비밀처럼 보이는 출력은 원문 경로를 인용하지 않는다.
  • 테스트: npm test는 오프라인 44개(README) — docs/verification.md는 42개라고 쓴다(불일치). 실제 기록 재생(replay)·읽기 게이트 평가(eval-readgate)·압축/보고 A/B(e2e-compact·ab-report) 스크립트가 별도로 있다.

알려진 한계 (저자가 직접 적은 것)

  • 압축 요약 자체는 호스트 것이고 hook은 바꿀 수 없다. retain은 요약 옆에 원문을 덧붙일 뿐이다. verbatim은 early-access function hook에 기대며, 로드됐는지는 debug 로그의 hooks module jev-context@… loaded로만 확인된다. 모듈은 $.env.get에 리터럴 이름만 쓸 수 있다.
  • verbatim은 --resume하면 사라진다. 남긴 tool_result가 압축 전 부모를 가리켜 컨텍스트가 205k 토큰으로 되돌아가기 때문이다. timing이 감지해 다시 압축하게 하지만(가드를 켠 재개에서 205k → 37k 토큰, 값 5/5), JEV_CONTEXT_RESUME=off면 재개한 첫 요청이 압축 전 전체를 다시 보낸다.
  • --fork-session 직후 바로 압축하면 retain이 빈손이다. fork의 기록 파일이 아직 없다(no_transcript).
  • Codex 감싸기는 승인을 대신한다. 파이프·연결·리다이렉션 없는 단일 명령만 감싼다.
  • Claude Code 내부 동작에 기대는 부분이 있다(2.1.284 실측, 공식 문서 없음). 버전을 올리면 테스트와 e2e를 다시 돌린다.
  • 기준선(0.3·0.8·1,000자·1,500자)은 작은 표본에서 나왔다. 다른 작업에서는 판단 로그의 점수를 보고 다시 맞춘다.
  • 라이선스 불일치: GitHub API license는 null이고 LICENSE 파일도 없지만 package.json과 플러그인 매니페스트는 MIT이라고 적는다.
  • report는 서브에이전트를 한 번 더 일하게 만든다. 추가 턴은 서브에이전트 창에서만 생기지만, 요약된 보고로 오케스트레이터의 판단이 나빠지는지는 평가하지 않았다.

판단 메모

  • 이 저장소의 가치는 아이디어(Jev 호출 억제 설계, fast-jev-compaction에서 가져온 verbatim 압축)보다 계측과 실패 보고에 있다. 잘 된 장면과 안 된 장면을 같은 표에 적고, 파일을 읽은 뒤 여러 턴이 지난 실험 1에서는 내장 요약도 통과해 verbatim의 이점이 정답률이 아니라 압축 시간뿐이었다고 스스로 인정한다.
  • 2026-09-20-sac-y-jev-cu·2026-09-27-dzhng-jevgrep 같은 Jev 응용 노트와 달리, 이 프로젝트는 Jev를 호스트 판단 게이트로 배치한다. 컨텍스트 관리 문제에 Jev를 쓰겠다는 발상이 이 저장소의 핵심 제안이고, 위키 작업 자체에도 그대로 적용 가능한 착상이다.
  • 단, Star 3·커밋 4건·저자 단독 실측이라 지금은 참고용이다. 모든 수치는 저자의 2026-09-29 라이브 측정(대부분 2~4회 반복)이고, 이 노트는 README와 docs/verification.md를 읽은 것이다(소스 코드는 미수집).

관련 노트