|

billion-context: 긴 세션의 대화 기록을 압축하는 컨텍스트 관리 프록시

Byjw-codex

코딩 에이전트와 모델 API 사이에서 대화 기록을 계층적 요약으로 압축하고 필요할 때 다시 펼치는 컨텍스트 관리 프록시·플러그인이에요. ‘10억 토큰’은 모델의 실제 컨텍스트 창 확장이 아니라 긴 세션의 누적 처리량을 뜻해요.

주요 기능

  • compress·decompress·search_context·acp_status 도구로 대화 구간 요약, 복원, 검색과 사용량 확인을 지원해요.
  • 모델이 압축 시점과 내용을 결정하는 증분·계층적 요약 방식이며 Anthropic/OpenAI 계열 요청과 응답 스트림을 중계해요.
  • 클라이언트별 네이티브 플러그인, bili <client> 실행기, baseURL에 /bili/를 붙이는 범용 연결 경로를 제공해요.
  • 웹 대시보드에서 세션·캐시 적중률·로그·설정을 보고 저장된 세션을 관리해요.

구조

TypeScript CLI(bili, 별칭 bili-proxy)와 acp-kernel 압축 계층, 클라이언트별 어댑터·MCP 도구, 로컬 세션 저장소가 결합된 구조예요. 일부 실행기는 클라이언트 환경변수와 전용 CA를 사용해 허용된 모델 호스트의 TLS를 중간에서 종료하는 MITM 방식으로 작동해요. 기본 수동 프록시 포트는 8787, 자동 관리 경로는 18787대부터 사용해요. 확인한 package.json 버전은 0.1.212예요.

누구에게 쓸모 있나요

긴 AI 코딩 세션의 토큰·캐시 비용을 줄이고 대화 기록을 관리하려는 개발자에게 적합해요. 프록시, 모델 인증, 로컬 저장소와 클라이언트별 제한을 이해해야 해요.

설치 전 준비

  • package.json의 Node.js 최소 조건은 >=20예요. 저장소 Docker는 Node 24를 사용하며 내장 node:sqlite 활용에는 Node >=22.5가 필요해요. Node 20도 일부 사전 빌드 대체 경로가 있으나 README의 Docker 경고와 구성 문서 설명이 달라 새 설치는 Node 24 기준 검토가 안전해요.
  • 별도로 설치한 지원 코딩 클라이언트와 사용 권한이 있는 모델 계정/API, 인터넷 연결이 필요해요.
  • 세션 원문·요약·이미지 및 SQLite 데이터를 보관할 로컬 디스크가 필요해요. 런타임에 SQLite 엔진을 자동 다운로드하는 경로가 있으며 해당 설정과 배포 정책을 확인해야 해요.
  • Windows·macOS·Linux의 Node.js CLI; Linux/macOS는 사용자 소유 npm prefix 설치 안내.
  • Claude Code·Codex·pi·OpenCode·dsh·Kimi·Hermes 등 클라이언트별 지원 방식이 다름. 이름이 목록에 있다고 모든 모드가 지원되는 것은 아님.
  • Docker 서비스 방식 지원. Claude Desktop의 Code 탭은 현재 README에 별도 미지원 경로·압축 우회 제한이 명시됨.

설치 방법

Linux·macOS npm 설치

공식 README의 사용자 권한 설치 예시예요. ~/.local/bin이 PATH에 있어야 해요. 이 조사에서 실행하지 않았어요.

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

공식 자료 확인

Windows 또는 사용자 소유 기본 prefix

Windows 기본 npm prefix와 nvm/Homebrew 등 사용자 소유 prefix에서는 일반 전역 설치를 안내해요. 설치 후 사용할 클라이언트를 별도로 준비해요.

npm install -g billion-context

공식 자료 확인

클라이언트 실행기 예

Codex 모델 트래픽까지 연결하려면 실행기 방식이 간단해요. 프록시·인증서 신뢰·환경변수 동작을 검토한 뒤 사용해요. 단순 Codex MCP 플러그인 설치만으로 모델 트래픽이 중계되지는 않습니다.

bili codex

공식 자료 확인

선택적 네이티브 플러그인 예

pi의 실제 설정을 수정하는 설치 명령이에요. 기존 billion-context-pi 같은 독립 확장과 동시에 사용하면 이중 압축이 발생할 수 있으므로 한 방식만 선택해요.

bili plugin install pi

공식 자료 확인

사용 방법

  • 직접 프록시를 시작하려면 bili를 실행하고 기본 http://localhost:8787 관리 화면을 엽니다. 연결 후 /__bili/health와 /__bili/stats, 요청 로그로 실제 중계 여부를 확인해요.
  • 범용 URL 방식은 기존 https://api.openai.com/v1 앞에 http://localhost:8787/bili/를 붙이에요. 선택한 공급자의 인증·요금은 그대로 적용돼요.
  • 지원 클라이언트의 /acp·/acp-cache 또는 웹 대시보드에서 압축·캐시 비용을 확인해요. 모든 클라이언트가 같은 명령을 지원하지 않습니다.
  • Codex는 bili codex 실행기가 완전한 연결 경로예요. bili plugin install codex는 MCP 도구만 등록하므로 별도 프록시 시작과 모델 트래픽 라우팅 없이는 압축되지 않습니다.
  • 중요한 대화는 원본·백업과 비교하고 필요할 때 decompress로 세부 정보를 복원해요. 플러그인 제거, 실행기 사용 중단 또는 baseURL 복원으로 중계 경로를 해제해요.

비용과 API 키

코드 사용료는 명시되지 않았지만 모델/API·구독·호스팅·디스크 비용은 별도예요. ‘5배 적은 토큰’, ‘100K로 충분’, 장기 세션·캐시 적중률 수치는 프로젝트 주장과 특정 평가 결과이며 이 조사에서 재현하지 않았어요. 압축·캐시 유지 요청 자체도 모델 사용량과 비용을 만들 수 있어요.

라이선스

루트 LICENSE는 MIT 본문에 ‘Additional Term — Attribution on Product Surfaces’를 추가한 형태예요. 단순 표준 MIT로 분류하면 안 돼요. 저작권·허가 고지를 보존하고, 이 소프트웨어를 사용하는 제품·서비스는 홈페이지·문서·About/Credits 중 한 곳에 billion-context(해당 시 acp-kernel) 사용 사실과 각 저장소 링크를 명시해야 해요. 순수 서버·임베디드 용도는 배포 문서로 충족해요. package.json은 MIT라고만 쓰지만 실제 LICENSE 추가 조건이 우선 확인 대상이에요.

주의사항과 알려진 이슈

  • 기본 프록시는 127.0.0.1에 바인딩되지만 인증 기능은 없어요. –host 0.0.0.0이나 Docker의 포트 게시를 인터넷에 공개하지 말고 접근 제어를 별도로 검토해야 해요. security.adminRelay를 켜면 호스트 웹 진입점에 관리·설정·자격증명 쓰기 권한까지 노출될 수 있어요.
  • 일부 클라이언트의 MITM 경로는 모델 트래픽을 복호화·재작성해요. 프롬프트·키를 처리하는 신뢰 지점이 추가되므로 인증서 범위, 공급자 약관, 조직 보안 정책을 확인해야 해요.
  • 세션과 로그가 로컬에 지속 저장돼요. 개인정보·비밀 코드·첨부 이미지의 보관·백업·삭제 정책을 정해야 하며 압축은 정보 손실 위험이나 프롬프트 주입을 제거하지 않습니다.
  • 자동 업데이트가 기본 동작이에요. ACP_AUTO_UPDATE=0과 별개로 advisoryCheck는 결함 버전의 강제 업그레이드·롤백을 수행하며 BILI_ADVISORY_CHECK=0으로 따로 제어해요. 런타임 SQLite 다운로드와 문서 갱신 등 추가 네트워크 동작도 존재해요.
  • Claude Desktop Code 탭은 managed ANTHROPIC_BASE_URL을 덮어써 프록시를 우회하면서 기본 auto-compaction까지 꺼질 수 있어요. 터미널 Claude Code와 혼동하지 않아야 해요.
  • 한 대화의 압축 상태는 단일 인스턴스에 묶이며 자동 복제·장애조치 저장소가 아니에요. 여러 인스턴스의 공유 RWX/NFS 저장소는 손상 위험이 있고, 같은 세션을 동시에 처리하는 구성을 피해야 해요.
  • master는 개발 브랜치로 README가 파손 가능성을 경고해요. README에 장기 실측 결과와 동시에 ‘Early, mock tests; real-model testing next’ 문구도 남아 있어 문서의 성숙도 설명이 일관되지 않습니다. 설치본 버전과 해당 클라이언트 실제 동작을 별도로 검증해야 해요.

#2290 Claude Desktop Code 탭 라우팅 제한

확인 시 closed 상태지만 고정 README는 여전히 Desktop의 URL 덮어쓰기·압축 우회 제한을 명시해요. 이슈가 닫혔다는 이유로 현재 Desktop 호환성이 해결되었다고 판단하지 않았어요.

확인 범위

확인 날짜: 2026-11-05

확인 커밋: 8de4c37f8fc066bda11430718e9c208f0d324e77

확인한 범위: 공식 GitHub API로 canonical ranxianglei/billion-context, 공개·비보관 상태와 기본 master 브랜치를 확인했어요. 해당 커밋에 고정한 README·LICENSE·package.json·CONFIGURATION.md 및 #2290 공개 이슈를 읽었습니다.

확인 한계: 대상 패키지 설치·실행·빌드·모델 호출·성능 측정·보안 감사는 수행하지 않았어요. npm 배포본과 GitHub 개발 커밋의 일치 여부, 각 클라이언트 최신 버전 호환성은 미검증이에요.

출처

Similar Posts

답글 남기기

이메일 주소는 공개되지 않습니다. 필수 필드는 *로 표시됩니다