<div align="center">
<img src="https://raw.githubusercontent.com/linqiu919/better-context-engine/HEAD/.github/assets/bce-logo.png" alt="Better Context Engine" width="128" />
Better Context Engine
ACE 호환 코드 컨텍스트 엔진: AI 코딩 어시스턴트를 위한 실시간 인덱싱 및 저지연, 고관련성 검색.
Go Docker PostgreSQL License
English · 简体中文
<sub>Friends · <a href="https://linux.do">🐧 LinuxDO</a></sub>
Features · How it works · Screenshots · Models · Quick start · Clients · Configuration
</div>
Better Context Engine (BCE)는 Go로 작성되었습니다. 이는 코드베이스를 실시간으로 인덱싱하고, 5초의 지연 시간(latency) 예산 내에서 AI 코딩 어시스턴트에게 컨텍스트를 제공합니다. 필요한 의존성은 PostgreSQL (pgvector 포함)과 하나의 모델 엔드포인트뿐이며, 별도의 벡터 데이터베이스나 메시지 큐는 필요하지 않습니다.
[!NOTE]
업로드된 소스는 AES-256-GCM으로 저장 시 암호화됩니다. Blob은 콘텐츠 주소 지정 및 중복 제거가 이루어지므로, 하나의 리포지토리의 브랜치와 작업 트리(worktrees)는 오직 그 차이점(diff)에 대한 비용만 발생합니다.
<div align="center">
<img src="https://raw.githubusercontent.com/linqiu919/better-context-engine/HEAD/.github/assets/bce-landing.png" alt="Landing page" width="100%" />
</div>
Features
검색(Retrieval)
- 3가지 방식의 검색(Three-way recall) – BM25 어휘 검색(지속적 역색인(inverted index), camelCase/snake_case 분할) + 경로/심볼 구조 점수(structural scoring) + 의미론적 벡터(semantic vectors)를 RRF로 융합.
- 재순위화 및 큐레이션(Rerank & curation) – 크로스 인코더 재순위화(cross-encoder reranking), 이후 파일별 캡(caps), 인접 단편 병합(adjacent-fragment merging) 및 소규모 단편 확장(small-fragment expansion).
- 항상 사용 가능(Always available) – 의미론적 점수 계산은 pgvector를 통해 PostgreSQL 내부에서 실행됩니다. 각 모델 경로는 쿨다운(cooldown)과 함께 독립적으로 성능이 저하되므로, 어휘/구조 검색 기능이 중단되는 일이 없습니다.
인덱싱(Indexing)
• AST 청킹 (AST chunking) – tree-sitter 구조적 청크(8개 언어 문법, 메서드 레벨)를 사용하며, 정규 표현식 및 슬라이딩 윈도우 폴백을 제공합니다.
• 콘텐츠 주소 지정 (Content addressing) – sha256(경로+콘텐츠) 블롭과 불변 스냅샷, 결정론적 체크포인트 ID를 사용하여 사용자 간 중복을 제거합니다 (deduplicated).
• 모델 격리 (Model isolation) – 벡터는 모델 ID별로 저장되며, 모델 전환 시 누락된 임베딩이 자동으로 채워집니다 (backfills).
통합 및 보안 (Integration & security)
• ACE 엔드포인트 (ACE endpoints) – /batch-upload, /agents/codebase-retrieval (알 수 없는 체크포인트의 경우 410), /prompt-enhancer. ace-tool-rs 스타일 클라이언트와 호환됩니다.
• 토큰 및 할당량 (Tokens & quotas) – 전역 토큰과 개인 토큰(SHA-256으로 저장), 사용자별 RPM, 일일 허용량 및 스토리지 상한선.
• 강화 (Hardening) – Argon2id 비밀번호, CSRF 보호, RBAC(역할 기반 접근 제어), 감사 로그.
콘솔 (Console)
• 작업 공간 (Workspace) – 개요 / 내 프로젝트 / 검색 디버거(프래그먼트 속성 지정, 평가 사례) / MCP 사용량 / 계정 설정.
• 관리자 (Admin) – 사용자 / 모든 프로젝트 / 시스템 설정(모델 및 등록) / 할당량 / 공지사항 / 감사 로그.
• 단일 바이너리 (Single binary) – 영어 및 중국어 지원, 라이트/다크 테마 제공; 프런트엔드는 go:embed를 통해 임베드됩니다.
개요 (Overview)
| 항목 | 값 |
|---|
| 서버 | Go 1.26 (CGO, tree-sitter) + React 17 콘솔 |
| ... | |
작동 방식 (How it works)
sequenceDiagram
participant C as bce-tool (MCP / CLI)
participant S as BCE server
...
- 클라이언트는 작업 공간을 해시하고 서버가 이미 보유하지 않은 블롭만 업로드합니다.
- 렉시컬 포스팅(Lexical postings)은 수집 시 작성되므로 프로젝트는 즉시 검색 가능하며, 벡터는 백그라운드에서 채워집니다.
- 검색 과정은 렉시컬(lexical), 구조적(structural), 의미론적(semantic) 회상을 통합하고, 후보들을 재순위화하며 발췌문을 선별합니다.
- 약한 첫 번째 통과 일치(weak first-pass match)는 광범위 모드(broad mode)로 전환됩니다: LLM 하위 쿼리 분해, 매니페스트 사전 정보(manifest priors), 골격 발췌문.
[!중요]
모든 검색(retrieval)은 5초의 예산 내에서 실행됩니다. 이 시간을 초과하는 단계들(쿼리 확장(query expansion), 재순위 지정(reranking), 인라인 임베딩(inline embedding))은 요청 실패 대신 성능 저하를 일으킵니다.
스크린샷
| Index 개요 | 내 프로젝트 |
|---|
| Index overview | My projects |
| 검색 검사(Search inspect) | MCP 사용량 (MCP usage) |
|---|
| Search inspect | MCP usage |
<div align="center">
<img src="https://raw.githubusercontent.com/linqiu919/better-context-engine/HEAD/.github/assets/bce-account.png" alt="계정 설정" width="100%" />
</div>
모델 구성 (Model configuration)
기본값 (Out-of-the-box defaults)
| 경로 (Path) | 기본 모델 (Default model) | 참고 사항 (Notes) |
|---|
| Embedding | Qwen/Qwen3-Embedding-8B | 4096 차원 |
| ... | | |
The default endpoint는 SiliconFlow (api.siliconflow.cn/v1)이며, 단일 MODEL_API_KEY가 세 경로 모두를 커버합니다. 모든 것은 환경 변수 또는 관리자 콘솔을 통해 로컬 서비스(ollama/vLLM)로 전환할 수 있습니다. 모델이 구성되지 않으면 검색은 어휘적/구조적 경로에서만 실행됩니다.
권장 설정 (호스팅 인스턴스가 사용하는 방식)
| 경로 (Path) | 모델 (Model) | 제공업체 (Provider) |
|---|
| Embedding | voyage-code-4 (1024 차원) | Voyage AI |
| ... | | |
Voyage의 코드 특화 모델은 코드 검색에 눈에 띄게 더 나은 성능을 보입니다. 임베딩(Embedding)과 재순위 지정기(reranker)는 https://api.voyageai.com/v1 엔드포인트와 키를 공유하며, 질의/문서 비대칭성(query/document asymmetry)은 input_type을 통해 자동으로 처리됩니다. 향상기(enhancer)/요약 경로(summary path)는 자체 제공업체를 사용하며, 이는 시스템 설정 → 검색 구성에서 설정할 수 있습니다. | | |
<details>
<summary><b>향상기 모델 선택</b></summary>
• 하나의 모델로 여러 작업 수행(One model, several jobs) – /prompt-enhancer를 통한 재작성 외에도 스페이슬리스(spaceless) 스크립트(예: 중국어) 쿼리 및 광범위 쿼리 분해를 위한 용어 확장을 구동합니다. 요약 모델은 엔드포인트와 키를 공유하므로, 둘 다 동일한 플랫폼에 존재해야 합니다.
• 속도보다 정확성(Accuracy over speed) – 개선 사항이 단순히 확인할 항목을 나열하는 것이 아니라 실제 원인(특정 상수, 페이지 크기, 호출 위치 등)을 명시할 때만 유용합니다. 여러 빠르고 저렴한 모델들이 특정 것처럼 보이는 재작성 내용을 생성했지만 근본 원인을 놓쳤습니다. gemini-3.8-flash는 (약 5~10초로) 느리지만 비교에서 근본 원인을 지목하는 능력이 더 좋았습니다.
• 답을 아는 질문으로 평가하기(Evaluate with questions whose answer you know) – 여러 개의 질문과 각 질문에 대한 여러 번의 실행을 통해 개선 내용이 단순히 코드를 인용하는지 여부가 아니라 근본 원인을 건드리는지 확인합니다.
• 필수 추론 모델도 작동함(Mandatory-reasoning models work too) – OpenRouter를 통해 호출할 경우 추론 기능이 꺼집니다. 만약 모델이 이를 거부하는 경우(예: Gemini 3.x), 서버는 최소한의 추론을 사용하여 한 번 재시도합니다.
빠른 시작하기 (Quick start)
Docker Compose (권장)
cp .env.example .env
docker compose up -d
http://localhost:18181에 접속하여 admin으로 로그인합니다 (비밀번호는 .env 파일의 BOOTSTRAP_ADMIN_PASSWORD).
[!TIP]
로컬 ollama를 함께 사용하는 경우: docker compose --profile models up -d.
로컬 개발(Local development)
npm install --prefix ui
npm run build --prefix ui
...
BCE_DATABASE_URL이 없으면 서버는 인메모리(in-memory) 스토어를 사용합니다.
클라이언트 연결하기 (Connecting a client)
MCP 클라이언트(Cursor, Claude Code 등)에서 bce-tool (또는 모든 ace-tool-rs-스타일의 클라이언트)를 구성하고 기본 URL을 BCE 배포 지점으로 지정합니다. 첫 번째 검색 시 프로젝트가 자동으로 업로드 및 인덱싱됩니다.
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
| Token | Format | Attribution |
|---|
| Global | ACE_TOKEN | 공유됨; 사용자별 할당량 제외 (Shared; exempt from per-user quotas) |
| Personal | bce_... (account settings page) | 사용량, 할당량 및 향상 컨텍스트는 호출하는 사용자를 따름 (Usage, quotas and enhancement context follow the calling user) |
설정 (Configuration)
| 변수 (Variable) | 기본값 (Default) | 설명 (Description) |
|---|
BCE_ADDR | :18181 | HTTP 리스닝 주소 (HTTP listen address) |
| ... | | |
개발 (Development)
go test ./...
npm run build --prefix ui
프로덕션 컨테이너는 먼저 프런트엔드를 빌드하고 이를 서버에 임베딩합니다. 또한 bce-agent도 배포합니다. bce-server는 tree-sitter AST chunker 때문에 CGO를 사용하여 컴파일됩니다.
라이선스 (License)
PolyForm Noncommercial 1.0.0 — 개인 및 비상업적 사용(연구, 학습, 취미 프로젝트, 비영리 단체, 교육)에 무료입니다.
[!WARNING]
상업적 사용에는 별도의 라이선스가 필요합니다. 이슈를 열거나 @linqiu919에게 문의해 주십시오.
