<p align="center">
<img
src="https://raw.githubusercontent.com/lyonzin/knowledge-rag/HEAD/assets/knowledge-rag-banner.png"
alt="knowledge-rag 배너: MCP를 위한 로컬 하이브리드 RAG. 문서는 수집(파싱, 청킹, 임베딩, 인덱싱)을 거쳐 하이브리드 검색 (FTS5, BM25, 의미론적), cross-encoder 재순위화 과정을 거쳐 LLM으로 전달됩니다."
width="100%"
/>
</p>
knowledge-rag: Claude Code, Cursor 및 기타 MCP 클라이언트를 위한 로컬 RAG 서버
knowledge-rag은 Model Context Protocol (MCP)을 위한 로컬 검색 증강 생성(RAG) 서버입니다. 사용자의 장치에 있는 문서와 코드를 인덱싱하며, 기본적으로 하이브리드 검색(BM25 키워드와 벡터 유사도 결합)과 cross-encoder 재순위화를 사용하여 Claude Code, Cursor, VS Code 및 기타 MCP 클라이언트에게 13가지 도구를 제공합니다. 모든 것은 ChromaDB 임베디드 및 FastEmbed ONNX 모델을 사용하는 단일 Python 프로세스에서 실행됩니다: Docker가 필요 없고, 데이터베이스 서버도 필요 없으며, API 키도 필요 없습니다. 모델이 캐시되면 인덱싱과 검색은 오프라인으로 작동합니다.
<div align="center">
PyPI
NPM
PyPI Downloads
Python
License
Platform
GPU
CodeQL
Quality Gate
Glama Score
OpenSSF Best Practices
</div>
- 11.1 ms의 CPU에서 캐시되지 않은 하이브리드 쿼리 중앙값(median) 성능, CUDA에서는 6.1 ms: Windows 호스트 한 대에서 149개의 청크를 대상으로 36개 쿼리를 실행했으며, 리랭커(reranker)는 비활성화 상태입니다 (audit)
- 캐시에서 제공되는 반복 쿼리의 중앙값은 0.03 ms이며, 동일한 워크로드를 사용했습니다 (audit)
- 5,889개의 문서에서 가져온 75,016개 청크: 프로덕션 재현 환경에서 전체 재구축이 완료되었습니다 (v4.8.3)
- 9개 OS × Python CI 셀 각각에서 1,500개 이상의 테스트를 수집했습니다 (플랫폼별 테스트 제외). 기준치(floor) 80% 대비 84%의 라인 커버리지를 달성했습니다 (CI run, 2026-11-06)
Claude Code에 설치 및 등록하기 (Python 3.11+ 및 Node.js 16+ 필요):
npx -y knowledge-rag --install-only
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag -- npx -y knowledge-rag
파일을 ~/knowledge-rag/documents/에 넣고 에이전트에게 검색하도록 요청하세요. 이 폴더는 첫 시작 시 생성되며, 새 파일과 변경된 파일은 자동으로 인덱싱되고, 모델(약 150 MB)은 필요할 때 처음 다운로드됩니다.
설치 · 결과 · 작동 방식 · 도구 · 에이전트 기능 · 비교 · FAQ · 문서
스타 히스토리 (Star history)
<p align="center">
<a href="https://www.star-history.com/?repos=lyonzin%2Fknowledge-rag&type=date&legend=top-left">
<img alt="지식 기반 RAG(knowledge-rag)의 시간 경과에 따른 GitHub 스타 라인 차트" src="https://raw.githubusercontent.com/lyonzin/knowledge-rag/HEAD/docs/star-history.svg" width="720" />
</a>
</p>
<p align="center"><sub style="font-size: 0.9em;">스타 히스토리 워크플로우에 의해 매일 업데이트됩니다. (<a href="./.github/workflows/update-star-history.yml">star-history workflow</a>).</sub></p>
측정된 결과 (Measured results)
프로젝트 자체 감사(audit)를 통해 얻은 측정값입니다. 이 값들은 단일 호스트와 소규모 코퍼스에서 나온 것이므로, 계획 수립 시 보장치라기보다는 크기의 순서(orders of magnitude)로 간주해 주십시오.
| Measurement | CPU | NVIDIA CUDA |
|---|
| Hybrid query, uncached, median | 11.13 ms | 6.10 ms |
| ... | | |
워크로드: scripts/audit_retrieval.py를 사용하여 7개의 공개 저장소 문서(149 청크)를 임시 ChromaDB 및 FTS5 인덱스에 색인화했습니다. 36개의 캐시 미사용 질의가 사용되었으며, 검색만 격리하기 위해 cross-encoder는 비활성화되었습니다. 환경: Windows 11, RTX 3080 Ti, Python 3.12.7, FastEmbed 0.8.1, ChromaDB 1.5.9, 모델 BAAI/bge-small-en-v1.5, Hugging Face 오프라인 모드. 출처: audit 2026-10-03. | | |
| Retrieval check | Result | Workload and source |
|---|
| Expected source in the top 5 | 12 of 12 questions; MRR@5 0.875 (English), 0.792 (Portuguese) | 149 청크에 걸친 동일한 영어 및 포르투갈어 질문 6개씩을 사용했으며, 기본 영어 모델이 적용되었습니다. 이는 일반적인 품질 주장이라기보다는 소규모 테스트(smoke test)입니다 (audit). |
| ... | | |
<details>
<summary>추가 측정값: 메모리, 모델 비교, 과거 기준선</summary>
- BM25 메모리: 토큰 풀(token pool)이 v4.10.0에 추가된 후, 10,000개의 문서 / 199만 개의 토큰에 대한 유지되는 Python 메모리가 120.7 MB에서 26.9 MB로 감소했습니다 (−77.75%) (audit).
- 메트릭스 메모리: 100,001개의 메트릭 관측값(metric observations)이 3,201,024 바이트 대신 328바이트만 유지했습니다 (audit).
- 다국어 모델: 비공개된 약 70,000 청크(chunk) 코퍼스에 대한 60문항 진단 세트에서,
intfloat/multilingual-e5-large는 기본값인 BAAI/bge-small-en-v1.5가 37개 질문 중 36개의 예상 출처를 찾은 것과 비교하여 성능을 보였습니다. CUDA 환경에서 70,083 청크를 재임베딩(re-embedding)하는 데는 1,186.58초가 소요되었습니다 (audit 2026-10-04).
- 과거 기준선(Historical baseline): v4.7.1 마이크로벤치마크 및 CPU 환경에서의 100개 문서 재구축 결과 (perf-baseline-v4.7.1). 이 비율은 해당 워크로드에만 적용됩니다.
- 실시간 대시보드(Live dashboard): 벤치마크 대시보드는 CI 마이크로벤치마크를 추적합니다. 여기서는 모의 저장소(mocked storage)와 모델을 사용하므로, 위에 제시된 실제 모델 수치와는 다른 질문에 답합니다.
작동 방식 (How it works)
- 데이터 수집(Ingest).
documents/ 폴더 아래의 파일들은 형식별로 구문 분석됩니다: 코드 파일은 함수, 클래스 및 import 이름을 메타데이터로 얻고, 노트북은 마크다운과 코드 셀만 유지하며, PDF는 텍스트를 기여합니다. 마크다운(Markdown)은 ##/### 섹션에서 분할되며; 다른 모든 형식은 200자 오버랩을 가진 1,000자 청크로 잘립니다. 청크들은 SHA-256으로 중복 제거되고 FastEmbed (기본값: BAAI/bge-small-en-v1.5, 384 차원)를 사용하여 임베딩된 후 ChromaDB에 저장됩니다.
- 감시(Watch). 서버가 실행되는 동안, 감시자(watcher)는 변경 사항이 없으면 10초 후에 변경된 파일을 재인덱싱합니다. 전체 재구축은 스테이징 컬렉션(staging collection)을 채우고 유효성 검사 후 이를 교체하므로 검색은 현재 인덱스를 계속 사용합니다.
- 검색(Search).
search_knowledge는 쿼리 캐시(100개 항목, 5분 TTL)를 확인하고, 역인덱스(inverted index)와 벡터 검색을 통해 BM25를 실행하며, 두 순위를 가중 역순위 융합(weighted reciprocal rank fusion)(hybrid_alpha, 기본값 0.3, 키워드 쪽으로 기울임)으로 융합한 후 Xenova/ms-marco-MiniLM-L-6-v2 크로스 인코더를 사용하여 상위 후보들을 재순위화합니다. 옵트인 FTS5 빠른 경로가 있는 경우, CVE ID, 티켓 키 및 해시와 같은 식별자형 쿼리는 먼저 SQLite FTS5로 전송됩니다.
- 답변(Answer). 결과는 파일 경로, 청크 인덱스, 스니펫 및 점수와 함께 MCP 클라이언트로 반환됩니다. 답변을 작성하는 것은 클라이언트의 모델이며, knowledge-rag는 절대 LLM을 호출하지 않습니다.
- 서비스 제공(Serve). 하나의 클라이언트를 위해 stdio를 통해, 또는 여러 클라이언트를 위한 Streamable HTTP 또는 SSE 서버로 작동합니다. HTTP 모드는 먼저 상태 확인 프로브(health probes)를 처리한 다음, 베어러 토큰(bearer token)을 확인합니다. 모든 도구 호출은 선택적 속도 제한기(rate limiter)와 메트릭을 거칩니다.
config.yaml과 다섯 가지 프리셋이 이 모든 것을 구성합니다.
flowchart TB
subgraph CLIENTS["MCP 클라이언트"]
direction LR
...
컴포넌트 소유권, 메모리 및 동시성 경계와 hybrid_alpha 가중치: docs/ARCHITECTURE.md.
설치
아래의 모든 경로는 동일한 서버를 실행합니다. 각 claude mcp add는 config.yaml, documents/, data/, models_cache/가 포함된 폴더인 KNOWLEDGE_RAG_DIR을 설정합니다. 이것이 없으면, 서버는 설치 위치와 클라이언트가 시작하는 작업 디렉토리에서 폴더를 가져오게 되는데, 이는 의도하지 않은 프로젝트일 수 있습니다 (config.py).
npx 런처를 사용한 Claude Code
npx -y knowledge-rag --install-only
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag -- npx -y knowledge-rag
이 npm 패키지는 런처 역할을 합니다. Python 3.11 이상 버전(python3/python, 또는 Windows에서는 python/py -3)을 찾아 ~/.knowledge-rag/venv에 가상 환경(virtual environment)을 생성하고, PyPI에서 일치하는 knowledge-rag 버전을 설치한 후 stdio를 통해 서버를 시작합니다. --install-only는 사전에 한 번 설치를 완료하므로, 클라이언트의 첫 시작 시 pip를 기다릴 필요가 없습니다. 새로운 npm 버전은 다음 시작 시 패키지를 재설치합니다. 네이티브 Windows에서 클라이언트가 npx 실행에 실패하는 경우, 대신 cmd /c npx -y knowledge-rag를 등록하십시오.
가상 환경 내의 pip
python3 -m venv ~/knowledge-rag/venv
~/knowledge-rag/venv/bin/python -m pip install knowledge-rag
claude mcp add knowledge-rag -s user --env KNOWLEDGE_RAG_DIR=~/knowledge-rag \
...
Windows(PowerShell)에서는 python3 및 ~/knowledge-rag/venv/bin/python 대신 python과 $HOME\knowledge-rag\venv\Scripts\python.exe를 사용하십시오.
선택 사항: 가상 환경이 활성화된 상태에서 ~/knowledge-rag 내부에서 knowledge-rag init을 실행하면, config.example.yaml과 다섯 가지 프리셋(presets)을 복사하고 documents/를 생성합니다. 이 명령어는 config.yaml을 생성하거나 서버를 등록하지 않습니다. 템플릿이나 프리셋을 직접 config.yaml로 복사해야 합니다. config.yaml이 없으면, 모든 33가지 기본 파일 유형을 포함하여 기본 설정(defaults)이 적용됩니다.
Docker
이미지는 linux/amd64 및 linux/arm64용으로 게시되었습니다. stdio의 경우, 클라이언트는 세션당 하나의 컨테이너를 시작합니다:
이미지는 python -m mcp_server.server를 실행하며, 이는 /app/config.yaml을 읽고 기본적으로 127.0.0.1의 stdio에 연결됩니다. 컨테이너에서 HTTP 서비스를 제공하려면 모든 컨테이너 인터페이스에서 수신하는 설정을 마운트하고 --transport 플래그를 전달해야 합니다:
mkdir -p ~/knowledge-rag
cat > ~/knowledge-rag/config.yaml <<'EOF'
server:
...
EOF
이미지는 모델 복사본을 FastEmbed의 기본 캐시에 빌드하지만, 서버는 /app/models_cache를 읽기 때문에 필요한 첫 번째 시점에 모델이 다시 다운로드됩니다. knowledge-rag-models 볼륨은 이들을 컨테이너 간에 유지합니다.
여러 클라이언트를 위한 공유 HTTP 서버
stdio는 하나의 프로세스를 소유하는 단일 클라이언트에게 적합합니다. 여러 클라이언트가 하나의 인덱스(Claude Code, Cursor, LM Studio, 더 많은 터미널)를 사용하는 경우, 하나의 Streamable HTTP 서버를 실행하고 모든 클라이언트를 이 서버에 연결해야 합니다 (#217, #223):
server:
transport: "streamable-http"
...
KNOWLEDGE_RAG_DIR=~/knowledge-rag knowledge-rag
curl http://127.0.0.1:8179/health
claude mcp add --transport http knowledge-rag http://127.0.0.1:8179/mcp \
...
