AI 튜토리얼

fast-jev-compaction으로 Claude Code 컨텍스트를 정확하게 보존하기

fast-jev-compaction을 npm 라이브러리 또는 Claude Code 플러그인으로 설치하고 사용하는 방법을 알아보세요. 이 튜토리얼에서는 Jev 기반 결정 방식, 구성 옵션, 사용자 지정 전송 지원, 오류 처리 동작과 중요한 텍스트를 원문 그대로 보존하면서 긴 대화 기록을 안전하게 줄이는 기법을 설명합니다.

2026년 9월 18일약 14분 소요

fast-jev-compaction으로 Claude Code 컨텍스트 정확하게 보존하기

fast-jev-compaction의 기능

fast-jev-compaction은 긴 에이전트 트랜스크립트를 요약문으로 다시 작성하지 않고 축약하는 npm 라이브러리이자 Claude Code 플러그인입니다. 대신 Jev 모델에 이전 도구 호출과 도구 결과를 평가하도록 요청한 다음, 구성 가능한 임계값에 따라 해당 항목을 유지하거나, 잘라내거나, 제거합니다.

사용자 및 어시스턴트 텍스트는 원문 그대로 원래 순서로 유지됩니다. 제거 대상이 되는 것은 도구 호출과 그에 대응하는 결과뿐입니다. 따라서 일반적인 요약 과정에서 정확한 제약 조건, 파일 경로, 명령어, 오류 메시지가 손실되는 일을 방지할 수 있습니다.

저장소에는 src/ 아래의 재사용 가능한 패키지와 hooks/ 및 .claude-plugin/ 아래의 Claude Code 함수 훅 플러그인이 모두 포함되어 있습니다.

축약 작동 방식

각 tool_use는 tool_use_id를 통해 해당하는 tool_result와 연결됩니다.
첫 번째 메시지의 호출과 최신 preserveRecentMessages개 메시지의 호출은 고정되므로 수정되지 않습니다.
전체 대화가 가장 오래된 항목부터 최신 항목 순서로 Jev에 전달됩니다. 이 판단 상태에서는 도구 결과 내용이 ok, 4213 chars (omitted)와 같은 짧은 메모로 대체되지만, 도구 입력과 텍스트는 계속 사용할 수 있습니다.
고정되지 않은 각 호출에 대해 Jev는 두 가지 질문에 답합니다. 해당 호출에 대한 지식이 여전히 중요한지, 그리고 전체 결과를 원문 그대로 계속 사용할 수 있어야 하는지입니다.
반환된 확률을 keepThreshold와 비교합니다.
고아 상태로 남는 결과가 없도록 트랜스크립트를 다시 구성합니다.

판정 결과

결과 점수가 임계값 이상이면 호출과 전체 결과를 모두 유지합니다.
호출 점수만 임계값 이상이면 호출은 유지하고, 결과는 앞부분의 truncateHeadChars개 문자와 메모리를 남기는 방식으로 축약합니다.
두 점수 모두 임계값 미만이면 호출과 그 결과를 함께 제거합니다.

비어 있는 메시지는 제거됩니다. 변경할 필요가 없는 메시지는 동일한 객체로 반환됩니다.

대규모 기록을 Jev 요청에 맞추기

판단 상태의 기본 한도는 예상 토큰 25000개입니다. 원래 상태가 너무 크면 라이브러리는 Jev에 표시되는 표현을 단계적으로 축약합니다. 도구 입력을 잘라내고, 긴 텍스트를 앞부분과 뒷부분으로 줄이며, 오래된 메시지를 합치고, 오래된 호출을 한 줄 기록으로 줄이고, 호출이 없는 오래된 메시지를 생략하며, 호출만 포함된 오래된 메시지가 연속되는 구간을 하나로 합칩니다.

이러한 변환은 최종 트랜스크립트에 보존되는 텍스트가 아니라 점수 계산에 사용하는 상태에 적용됩니다. 그래도 상태를 맞출 수 없으면 축약 과정에서 오류가 발생합니다.

각 상태와 질문을 합친 요청이 기본값 30000인 maxRequestTokens 미만으로 유지되도록 질문도 여러 배치로 나눕니다. 요청은 동시에 실행되며 판정 결과는 병합됩니다.

npm 라이브러리 설치

패키지를 설치하고 환경 변수를 통해 TypeSafe API 키를 제공합니다.

npm install fast-jev-compaction
export TYPESAFE_API_KEY=...

API 키를 커밋하거나 소스 파일에 직접 입력하지 마세요.

기본 클라이언트는 process.env.TYPESAFE_API_KEY를 읽습니다. API 호출 시 apiKey 옵션을 제공할 수도 있습니다.

트랜스크립트 축약

compactMessages를 가져오고 트랜스크립트를 준비한 다음, 기본값과 다른 옵션을 전달합니다.

import {
  compactMessages,
  reductionRatio,
  type Message,
} from 'fast-jev-compaction';

const transcript: Message[] = [
  {
    role: 'user',
    text: 'Fix the failing test. Never edit src/generated.',
    toolUses: [],
  },
  {
    role: 'assistant',
    text: '',
    toolUses: [
      {
        tool_use_id: 'toolu_1',
        tool: 'Read',
        input: { file_path: 'src/a.ts' },
      },
    ],
  },
  {
    role: 'user',
    text: '',
    toolUses: [],
    toolResults: [
      { tool_use_id: 'toolu_1', text: '…file contents…' },
    ],
  },
];

const result = await compactMessages(transcript, {
  preserveRecentMessages: 4,
});

console.log(result.messages);
console.log(result.decisions);
console.log(result.stats);

내보내는 Message 타입은 Claude Code의 SessionMessage 일부를 따르므로 Claude Code 세션 트랜스크립트를 패키지에 직접 전달할 수 있습니다.

축약이 유용했는지 확인

이 패키지는 reductionRatio를 내보냅니다. 이를 사용하면 애플리케이션에서 축약된 기록을 사용할지 결정할 수 있습니다.

const result = await compactMessages(transcript);

if (reductionRatio(result) < 0.25) {
  // Keep the original transcript or use another fallback.
} else {
  // Continue with result.messages.
}

결과 통계에는 축약 전후의 메시지 및 문자 수, 이유별로 그룹화된 판정 수, 예상 상태 크기, 사용된 맞춤 단계, Jev 요청 수가 포함됩니다.

축약 동작 구성

주요 옵션은 다음과 같습니다.

apiKey: TypeSafe API 키입니다. 기본값은 TYPESAFE_API_KEY입니다.
model: Jev 모델 이름입니다. 기본값은 jev-latest입니다.
baseUrl: System One 엔드포인트입니다. 기본값은 https://api.typesafe.ai/v1/systemone입니다.
fetch: 주입 가능한 fetch 구현으로, 특히 테스트에 유용합니다.
goal: 상태에 포함되는 진행 중인 작업 설명입니다. 기본적으로 최근 사용자 프롬프트 3개를 사용합니다.
keepThreshold: 호출 또는 전체 결과를 유지하는 데 필요한 최소 확률입니다. 기본값은 0.5입니다.
preserveRecentMessages: 수정할 수 없는 최신 메시지 수입니다. 기본값은 6이며, 첫 번째 메시지도 항상 보존됩니다.
maxStateTokens: 의사 결정 상태에 대한 추정 토큰 상한입니다. 기본값은 25000입니다.
maxRequestTokens: 한 요청에서 상태와 질문을 합친 추정 상한입니다. 기본값은 30000입니다.
truncateHeadChars: 결과를 잘라낼 때 유지할 앞부분 문자 수입니다. 기본값은 300입니다.

const result = await compactMessages(transcript, {
  goal: 'Fix the test without editing generated files',
  keepThreshold: 0.6,
  preserveRecentMessages: 8,
  truncateHeadChars: 500,
});

더 높은 keepThreshold를 설정하면 더 높은 유지 확률이 필요하므로 더 많은 도구 활동이 제거될 수 있습니다. 확률은 삭제가 안전하다는 증거가 아니므로, 대표적인 트랜스크립트를 기준으로 임계값 변경을 평가하세요.

사용자 지정 Jev 전송 방식 사용

기본 제공 TypeSafe 클라이언트가 환경에 맞지 않는 경우, 내보내기된 JevAsker 인터페이스를 구현하세요. 이 인터페이스에는 ask(state, questions) 메서드가 필요합니다. 그런 다음 compactMessages 대신 compact(messages, asker, options)를 호출하세요.

이 패키지는 HTTP 요청 본문을 구성하는 buildJevRequest와 응답을 검증하는 parseJevResponse도 내보냅니다. 더 전문화된 통합을 위한 저수준 구성 요소도 제공됩니다.

collectToolCalls는 호출과 그 결과를 연결합니다.
fitState는 구성된 크기 상한에 맞는 상태를 준비합니다.
batchCalls는 여러 요청에 걸쳐 질문을 나눕니다.
decideCall은 점수를 유지, 잘라내기 또는 제거 결정으로 변환합니다.
applyDecisions는 메시지 기록을 다시 구성합니다.

Claude Code 플러그인 설치

이 플러그인에는 Claude Code 2.1.274 이상이 필요합니다. 함수 훅은 얼리 액세스 기능이므로 Claude Code가 실행되는 모든 환경에서 활성화하세요. 예를 들어 ~/.claude/settings.json에 환경 설정을 추가합니다.

{
  "env": {
    "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1",
    "TYPESAFE_API_KEY": "<your key>"
  }
}

저장소를 플러그인 마켓플레이스로 추가한 다음 플러그인을 설치하세요.

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

설치 프로그램에서 임계값과 truncateHeadChars 등의 옵션을 묻습니다. 환경 변수의 TYPESAFE_API_KEY를 사용하려면 API 키 옵션을 기본값으로 두세요.

Claude Code를 다시 시작하거나 다음을 실행하세요.

/reload-plugins

활성화되면 /compact와 자동 압축이 모두 Jev 훅을 통해 처리됩니다. 성공적으로 대체되면 fast-jev-compaction: kept N/M messages, no summary (...)와 유사한 토스트가 표시됩니다. Jev가 실패하거나 축소가 충분하지 않으면 훅이 Claude Code의 기본 요약 기능으로 대체됩니다.

체크아웃에서 직접 플러그인 실행

게시하거나 설치하지 않고도 저장소를 테스트할 수 있습니다.

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir .

저장소 루트에서 이 명령을 실행하세요.

고급 사용 팁

활성 작업 보호

최근 도구 출력이 다시 사용될 가능성이 있다면 preserveRecentMessages를 늘리세요. 이러한 메시지의 호출은 고정되어 제거하거나 잘라낼 수 없습니다.

정확한 목표 제공

기본 목표는 최근 사용자 프롬프트 3개에서 파생됩니다. 세션이 길거나 방향이 바뀌는 경우 goal을 명시적으로 설정하면 Jev가 진행 중인 작업을 더 명확하게 파악할 수 있습니다.

통계를 사용해 대체 정책 정의

압축된 결과를 항상 자동으로 수락하기보다 result.stats와 reductionRatio(result)를 확인하세요. 짧은 세션에서는 원본 트랜스크립트를 대체할 만큼 충분한 축소가 이루어지지 않을 수 있습니다.

오류에 대비

Jev가 실패하거나, 잘못된 데이터를 반환하거나, 필수 키를 누락하거나, 상태 제한 내에 맞출 수 없는 기록을 받으면 압축에서 예외가 발생합니다. 라이브러리 호출을 오류 처리로 감싸고 필요할 때 원본 트랜스크립트를 유지하거나 다른 압축 전략을 호출하세요. Claude Code 훅은 이미 기본 요약 기능으로 대체됩니다.

요청 비용 이해

완전히 맞춰진 상태는 모든 질문 배치에 반복해서 포함됩니다. 따라서 상태 상한에 가까운 기록은 작은 질문 그룹마다 하나의 대규모 요청이 필요할 수 있습니다. 제한을 조정할 때 result.stats의 요청 수를 검토하세요.

네트워크 호출 없이 테스트

저장소의 단위 테스트는 가짜 Jev 구현을 사용하며 TypeSafe에 연결하지 않습니다. 사용자 지정 JevAsker 또는 주입된 fetch 구현을 사용하면 애플리케이션 테스트에서도 동일한 방식을 적용할 수 있습니다.

개발 명령

저장소에서 작업할 때는 종속성을 설치하고 사용 가능한 검사를 실행하세요.

npm install
npm run typecheck
npm test
npm run build
npm run validate:plugin
TYPESAFE_API_KEY="$(cat ~/.typesafe_key)" npm run demo

demo 명령은 실제 네트워크 검사를 수행합니다. 저장소에는 demo/JevDemo 경로에 macOS SwiftUI 애니메이션도 포함되어 있습니다. 이 애니메이션은 미리 준비된 대화 기록으로 압축을 시각적으로 보여 주며 API를 호출하지 않습니다.

demo/JevDemo/build.sh

앱에서 스페이스 키를 누르면 애니메이션을 다시 재생할 수 있습니다.

중요한 제한 사항

제거하거나 잘라낼 수 있는 것은 도구 호출과 결과뿐입니다. 텍스트 메시지는 출력에서 변경되지 않습니다.
토큰 수는 토크나이저가 아닌 문자 패턴을 기반으로 추정됩니다.
Jev의 확률이 결과를 삭제해도 안전하다는 것을 보장하지는 않습니다. 다만 필요한 경우 어시스턴트가 제거된 도구 호출을 다시 실행할 수 있습니다.
모든 요청 배치에는 전체 상태가 반복해서 포함되므로, 설정된 한도에 가까운 대화 기록에서는 비용이 증가할 수 있습니다.

결론

fast-jev-compaction은 오래된 도구 활동을 선택적으로 정리하면서 사용자와 어시스턴트의 텍스트를 보존하여, 정보가 손실되는 대화 요약의 대안을 제공합니다. 애플리케이션 수준에서 제어하려면 npm API를, 자동 통합을 사용하려면 Claude Code 플러그인을 활용하고, 제공되는 임계값, 보존 설정, 통계 및 대체 동작을 조정하여 작업 흐름에 맞게 압축을 설정하세요.