코딩 AI와 오래 일하다 보면 “아까 정한 조건을 다시 설명해야 하나요?”라는 순간이 찾아옵니다. 오류 로그와 코드가 쌓이면 모델이 한 번에 읽을 수 있는 문맥 창, 즉 대화를 담는 공간이 부족해집니다. billion-context는 에이전트와 모델 사이에서 지난 대화 일부를 요약하고, 필요할 때 해당 구간을 다시 펼치는 도구입니다. 긴 세션을 이어가는 개발자에게 흥미로운 선택이지만, 현재는 모델 전환 관련 오류의 수정 상태를 더 확인한 뒤 도입하는 편을 권합니다.

대화를 접었다가 다시 펼치는 방식입니다

프록시는 요청을 중간에서 받아 전달하는 프로그램입니다. billion-context는 코딩 에이전트가 보내는 대화를 받아 오래된 구간을 계층적인 요약으로 바꾸고 모델 제공자에게 전달합니다. 모델이 작업하면서 압축할 범위를 고를 수 있도록 다음 도구를 대화에 제공합니다. README의 작동 방식

도구 대화에서 하는 일
compress 메시지 구간을 요약으로 접습니다.
decompress 정확한 내용이 필요해진 압축 구간을 복원합니다.
search_context 요약과 현재 보이는 메시지에서 키워드를 찾습니다.
acp_status 문맥 사용량과 압축할 수 있는 구간을 확인합니다.

예를 들어 처음에는 결제 오류를 분석하고, 이후에는 화면과 테스트를 고쳤다고 가정합니다. 결제 분석 대화를 요약해 두었다가 예전 오류 코드의 정확한 문구가 다시 필요해지면 그 구간을 찾아 복원하는 흐름입니다. README는 이런 압축·검색·복원을 설명합니다. 복원한 내용이 다시 문맥 공간을 차지하므로, 모든 과거 대화를 항상 원문으로 펼쳐 둔 채 한도를 없애는 방식과는 차이가 있습니다.

프로젝트는 클라이언트의 내장 요약 기능과 비교해 작은 구간별 압축, 복원, 프롬프트 앞부분의 캐시 유지를 차별점으로 내세웁니다. 이미 내장 요약과 세션 분리로 충분히 일하고 있다면 추가 프록시를 운영할 필요성은 낮습니다. 세션을 넘나드는 작업 기억이 필요하다면 claude-mem의 기억 저장 방식도 함께 살펴볼 수 있습니다. 오래된 대화를 현재 요청에서 줄이는 문제와 다음 세션에 기억을 전달하는 문제를 구분하면 선택이 쉬워집니다.

결제 오류를 오래 추적하는 작업에 적용해 봅니다

다음은 공식 연결 절차에 맞춰 구성한 활용 예시입니다. 입력은 결제 실패 로그, 관련 코드, “중복 결제를 막는 기존 조건을 유지합니다”라는 요구사항입니다. 기대하는 결과는 오래된 분석 구간을 요약하면서 작업을 이어가고, 이전 조건의 원문을 찾아 테스트와 대조하는 것입니다.

  1. 중요하지 않은 별도 작업 폴더와 새 세션을 준비합니다. 기존에 쓰는 Codex CLI와 모델 로그인 또는 API 연결이 필요합니다.

  2. Node.js 20 이상 환경에서 패키지를 설치합니다. README는 Windows의 기본 npm 설치 경로와 Linux·macOS의 사용자 설치 경로를 각각 안내합니다. Node 조건 · 설치 안내

    Windows에서는 다음 명령을 안내합니다.

    npm install -g billion-context

    Linux·macOS에서는 다음 사용자 경로 설치를 안내합니다.

    npm install -g billion-context --prefix=~/.local

    후자는 ~/.local/bin이 PATH에 있어야 bili를 찾을 수 있습니다. nvm·Homebrew처럼 기본 설치 경로가 사용자 소유인 환경에서는 README가 일반 전역 설치도 허용합니다.

  3. bili codex로 프록시와 Codex를 함께 시작하고, 평소처럼 결제 로그와 수정 요청을 전달합니다. 압축할 구간의 선택은 모델이 제공된 도구로 수행합니다. 클라이언트 선택과 시작

    bili codex

  4. 대화가 길어진 뒤에는 모델에게 acp_status로 상태를 확인하고, search_context로 “중복 결제” 조건을 찾아 달라고 요청합니다. 원문이 필요한 구간은 decompress로 복원하도록 요청한 뒤 실제 코드와 테스트에 그 조건이 남아 있는지 대조합니다. 이는 도구 활용을 위한 예시 요청이며, 특정 문장만 입력하면 정확한 복원이 보장된다는 시험 결과는 없습니다.

도입 시험에서는 단순히 대화가 계속되는지보다 옛 요구사항의 정확한 문구를 다시 찾을 수 있는지, 요약 이후 테스트가 그 조건을 지키는지 확인하는 편이 유용합니다. 문맥 사용량과 모델 제공자의 실제 사용량도 함께 기록해야 비용 판단이 가능합니다.

Codex에서는 플러그인 설치와 연결이 다릅니다

README의 클라이언트 표는 bili codex를 프록시까지 연결하는 실행 방식으로 설명합니다. 반면 bili plugin install codex는 MCP 도구를 추가하는 방식이며, 이것만으로 Codex의 모델 요청이 프록시를 통과하지 않습니다. 도구 이름이 목록에 보여도 실제 대화 압축까지 동작하는지 확인해야 합니다. Codex 연결 상세

Codex 실행 방식은 HTTPS_PROXY와 SSL_CERT_FILE을 이용하는 로컬 인증서 기반 프록시 연결을 사용합니다. 플러그인 설치는 ~/.codex/config.toml에 [mcp_servers.bili]를 추가합니다. 클라이언트마다 연결 지점이 다르므로 Claude Code 등의 이름만 바꿔 같은 설정 파일을 쓰면 안 맞을 수 있습니다. 해당 클라이언트의 안내를 먼저 읽습니다.

README는 실행 방식이 실제 클라이언트 설정 파일을 건드리지 않는다고 설명합니다. 그래도 모델 요청을 읽고 다시 작성하는 프로그램이 하나 추가되며, 원래 클라이언트가 승인받아 수행하는 파일 수정·명령 실행은 그대로 작업에 영향을 줍니다. 프록시를 설치했다고 에이전트의 코드 수정이나 실행 권한이 줄어들지는 않습니다.

수동 bili start는 8787 포트를 사용하고, 자동으로 시작되는 실행·플러그인 경로는 18787부터 별도로 관리하며 충돌 시 이동한다고 README는 설명합니다. 따라서 bili codex를 실행하면서 고정 8787 주소를 수동으로 입력하는 절차를 덧붙일 필요가 없습니다. 포트와 연결 방식

무료 패키지여도 모델 비용과 데이터 경로는 확인합니다

2026년 10월 13일 확인한 자료에서 패키지의 별도 소프트웨어 이용료는 확인되지 않았습니다. 기존 모델 이용 조건은 유지되며, 요약 관련 호출에도 모델 비용이 발생할 수 있습니다. README의 “토큰 5배 절감”과 “압축 비용 2% 이하”는 프로젝트 측 주장입니다. 실제 결제액은 선택한 모델, 입력·출력과 캐시 가격, 복원 빈도에 따라 달라지므로 이 숫자를 예산에 그대로 적용하기는 어렵습니다.

설정 문서의 별도 요약 서비스 compress.externalSummary는 enabled: true일 때만 켜집니다. 사용하려면 제공자·모델을 targets로 지정하며, 요약할 내용이 그 제공자에게 전송되고 별도 자격 증명과 비용이 필요합니다. 사용하지 않으려면 compress.externalSummary.enabled를 false로 둡니다. 외부 요약 서비스 설정

로컬 프록시를 쓰더라도 본래 모델 요청은 선택한 모델 제공자에게 전달됩니다. 회사 코드와 로그를 다루는 경우 기존 제공자의 전송 규칙뿐 아니라 프록시가 대화를 처리하는 경로도 확인합니다. 한국 독자도 README의 OS별 설치 절차를 참고할 수 있으나, 모델 계정의 국내 제공·결제 조건은 사용 중인 제공자를 따릅니다. 한국어 장기 대화의 요약·복원 품질은 이 조사에서 확인하지 않았습니다.

유지보수 설정도 살펴볼 필요가 있습니다. autoUpdate는 기본 true이며 ACP_AUTO_UPDATE=0으로 끌 수 있습니다. 이와 별도로 기본 활성화된 advisoryCheck는 알려진 결함 버전에서 지정 버전으로 강제 설치하며 되돌림도 가능하고, BILI_ADVISORY_CHECK=0으로 끕니다. 자동 재시작 autoRestartOnUpdate의 기본값은 false입니다. 버전을 고정해 비교하려면 업데이트와 결함 알림 경로를 함께 고려합니다. 업데이트 설정

라이선스에는 제품 출처 표시 조건이 더 있습니다

package.json은 MIT로 표시하지만, LICENSE 원문에는 사용자에게 보이는 제품·서비스에 통합할 때 적용하는 추가 출처 표시 조항이 있습니다. 상용과 오픈소스 제품 모두 홈페이지, 문서, About·Credits 페이지 중 한 곳에 billion-context 사용 사실과 저장소 링크를 보이도록 요구합니다. 관련 커널을 포함하면 그 출처도 표시합니다. 사용자 화면이 없는 서버·내장 용도는 배포 문서의 고지로 충족한다고 적혀 있습니다.

개인 코딩 보조와 다른 사람에게 제공하는 제품 통합은 이 조건의 영향을 다르게 받습니다. 배포할 제품에 넣으려면 단순한 MIT 표기보다 원문의 추가 조건까지 검토합니다.

모델을 바꿨을 때 압축 상태가 유지되는지가 관건입니다

2026년 10월 13일 확인한 이슈 #2915는 열림 상태였습니다. dsh라는 코딩 클라이언트에서 모델을 전환한 뒤 도구 호출 식별자가 바뀌어 압축 구간과 원래 대화를 연결하지 못하고, 대화가 다시 커져 502 오류로 세션을 이어가지 못했다는 보고입니다. 작성자는 0.1.193과 0.1.195에서 재현했다고 적었습니다. 이 보고의 조건을 모든 Codex·Claude Code 세션에 그대로 일반화할 수는 없지만, 장기 대화 유지가 도구의 핵심인 만큼 도입 판단에 중요한 사례입니다.

댓글에는 압축 구간의 대응 관계를 복구하는 근본 수정 PR #2939가 연결돼 있습니다. 10월 13일 확인한 이슈 화면에서 이 PR은 아직 열림(병합 전) 상태였고, 리뷰 댓글은 자동 시험이 모두 통과하면 병합할 수 있다고 적었습니다. 병합 여부는 저장소 소유자가 정합니다. 이 수정이 담긴 릴리스는 확인되지 않았으므로, PR 병합과 그 뒤의 릴리스를 함께 확인해야 합니다.

확인 기준 릴리스는 v0.1.195, 커밋 f76ffe9이며 2026년 10월 12일 공개됐습니다. 릴리스와 이슈의 수정 논의에서 관리 활동은 확인되지만, 변경이 활발하다는 사실만으로 해당 오류가 해결됐다고 판단하기는 어렵습니다. 연결·설정 설명은 10월 13일 master 문서도 함께 확인했으므로 설치 시점의 릴리스 문서와 차이를 대조합니다.

도입 판단: 아직 지켜볼 것

긴 세션을 압축하면서 옛 내용을 찾아 복원한다는 용도는 분명합니다. 다만 모델 전환 뒤 압축 상태를 잃었다는 보고가 열려 있고, 확인 시점에 수정 PR이 병합 전이라 현재 권고는 아직 지켜볼 것입니다.

다음 행동은 #2915와 #2939의 상태, 수정이 포함된 릴리스를 확인하는 것입니다. 시험한다면 중요하지 않은 새 세션에서 같은 모델로 먼저 작업하고, 압축 후 요구사항 검색·원문 복원·테스트 결과를 확인합니다. 모델 전환이 필요한 업무라면 그 조건까지 별도로 검증한 뒤 중요한 작업에 연결합니다.

참고한 자료

확인일은 2026년 10월 13일입니다. 조사 범위는 공식 문서·릴리스·공개 이슈이며 외부 프로젝트 설치와 모델 API 시험은 수행하지 않았습니다.

  • 공식 저장소와 README: 기능·설치·클라이언트 선택·프로젝트 측 절감 주장입니다.
  • CLIENTS.md: Codex 실행과 MCP 도구 설치의 차이입니다.
  • CONFIGURATION.md: 외부 요약·업데이트 설정과 기본값입니다.
  • v0.1.195 릴리스: 기준 버전과 변경 기록입니다.
  • 이슈 #2915: 모델 전환 후 압축 상태 소실 보고와 수정 논의입니다.
  • LICENSE: MIT 본문과 제품 출처 표시 추가 조건입니다.
  • package.json: 패키지명·버전·Node.js 조건입니다.