Skip to content

README_ko.md

Latest commit

 

History

History
206 lines (146 loc) · 8.96 KB

README_ko.md

File metadata and controls

206 lines (146 loc) · 8.96 KB

hegwid-cg

hedwig-cg

"With hedwig-cg, your coding agent knows what to read."
빠른 시작 · English · 日本語 · 中文 · Deutsch

CI PyPI License Python 3.10+

왜 hedwig-cg인가?

raw data from a given number of sources is collected, then compiled by an LLM into a .md wiki, then operated on by various CLIs by the LLM to do Q&A and to incrementally enhance the wiki - Andrej Karpathy

hedwig-cg는 10,000개 이상의 파일을 가진 코드베이스와 지식 문서들로부터, 경량 로컬 LLM 모델을 사용하여 질의 가능한 코드 그래프와 지식 베이스를 구축합니다. 서브그래프 응답을 포함한 하이브리드 벡터 + 키워드 검색(벡터 + 키워드 → MST 서브그래프를 통한 RRF 퓨전)으로 코딩 에이전트가 프로젝트 전체를 진정으로 이해할 수 있게 됩니다. 설치하면 Claude Code가 전체 그림을 볼 수 있습니다 — 추가적인 토큰도, 추가적인 명령도 필요 없으며, 모든 것이 100% 로컬에서 실행됩니다.

빠른 시작

pip install hedwig-cg

cd your-project/
hedwig-cg claude install

그리고 Claude Code에게 말하세요:

"이 프로젝트의 코드 그래프를 빌드해"

끝입니다. Claude Code가 그래프를 빌드하고, 이후 모든 검색에서 자동으로 참조합니다. 세션이 끝나면 그래프가 자동으로 리빌드됩니다.

AI 에이전트 통합

hedwig-cg는 주요 AI 코딩 에이전트와 한 명령어로 통합됩니다:

에이전트 설치 설명
Claude Code hedwig-cg claude install Skill + CLAUDE.md + PreToolUse 훅
Codex CLI hedwig-cg codex install AGENTS.md + PreToolUse 훅
Gemini CLI hedwig-cg gemini install GEMINI.md + BeforeTool 훅
Cursor IDE hedwig-cg cursor install .cursor/rules/ 규칙 파일
Windsurf IDE hedwig-cg windsurf install .windsurf/rules/ 규칙 파일
Cline hedwig-cg cline install .clinerules 파일
Aider CLI hedwig-cg aider install CONVENTIONS.md + .aider.conf.yml
MCP 서버 claude mcp add hedwig-cg -- hedwig-cg mcp Model Context Protocol 5개 도구

각 install은 컨텍스트 파일 작성과 (지원하는 플랫폼의 경우) 도구 호출 전 훅 등록을 수행합니다. 제거: hedwig-cg <platform> uninstall.

지원 언어

구조 추출 (20개 이상 언어)

hedwig-cg는 tree-sitter와 네이티브 파서를 사용하여 함수, 클래스, 메서드, 호출, import, 상속을 추출합니다.
Python JavaScript TypeScript Go
Rust Java C C++
C# Ruby Swift Scala
Lua PHP Elixir Kotlin
Objective-C Terraform/HCL

설정 및 문서 포맷도 구조 추출 지원: YAML, JSON, TOML, Markdown, PDF, HTML, CSV, Shell, R 등.

다국어 자연어 지원

텍스트 노드(문서, 주석, 마크다운)는 intfloat/multilingual-e5-small로 임베딩되어 100개 이상의 자연어를 지원합니다 — 한국어, 일본어, 중국어, 독일어, 프랑스어 등. 원하는 언어로 검색하면 모든 언어의 결과를 찾습니다.

기능

자동 리빌드

AI 코딩 에이전트(Claude Code, Codex 등)와 통합 시, hedwig-cg는 코드 변경 시 자동으로 그래프를 리빌드합니다. Stop/SessionEnd 훅이 git diff로 변경된 파일을 감지하고 백그라운드에서 증분 빌드를 실행합니다 — 수동 작업이 필요 없습니다.

스마트 무시

세 가지 소스의 무시 패턴을 지원하며, 모두 완전한 gitignore 스펙(negation !, ** 글로브, 디렉토리 전용 패턴)을 따릅니다:

소스 설명
기본 내장 .git, node_modules, __pycache__, dist, build 등
.gitignore 프로젝트 루트에서 자동 읽기 — 기존 git ignore가 그대로 동작
.hedwig-cg-ignore 코드 그래프 전용 프로젝트별 오버라이드

증분 빌드

파일별 SHA-256 콘텐츠 해싱. 변경된 파일만 재추출 및 재임베딩합니다. 변경되지 않은 파일은 기존 그래프에서 병합 — 일반적으로 전체 빌드 대비 95% 이상 빠릅니다.

메모리 관리

4GB 메모리 예산과 단계별 해제. 파이프라인은 각 단계에서 생성 → 저장 → 해제: 추출 결과는 그래프 빌드 후 해제, 임베딩은 배치 단위로 스트리밍 후 DB 쓰기 후 해제, 전체 그래프는 영속화 후 해제됩니다. GC는 75% 임계값에서 선제적으로 트리거됩니다.

100% 로컬

클라우드 서비스 없음, API 키 없음, 텔레메트리 없음. SQLite + FAISS로 저장, sentence-transformers로 임베딩. 모든 데이터가 로컬에 유지됩니다.

서브그래프 응답을 포함한 하이브리드 검색

모든 쿼리는 시드 노드와 그것들이 어떻게 연결되는지 보여주는 서브그래프를 반환합니다:

검색 파이프라인

신호 찾는 것
벡터 검색 의미적으로 유사한 코드와 문서 (듀얼 모델: 코드 + 텍스트)
키워드 검색 FTS5를 통한 정확한 이름 매칭 (BM25)

결과는 Weighted Reciprocal Rank Fusion (RRF)으로 융합된 후, MST 기반 최단 경로를 통해 연결되어 시드 노드들의 관계를 보여줍니다.

응답 형식

seeds:
hedwig_cg/core/pipeline.py:71
hedwig_cg/query/embeddings.py:70

edges:
hedwig_cg/core/pipeline.py:71 -calls-> hedwig_cg/core/extract.py:747
hedwig_cg/core/pipeline.py:0 -co_change-> hedwig_cg/query/embeddings.py:0
  • seeds: 검색으로 찾은 노드 ID (파일:라인)
  • edges: 최단 경로를 통해 시드 노드를 연결하는 서브그래프 (중간 노드는 엣지에 표시됨)

CLI 레퍼런스

모든 명령은 기본적으로 간결한 텍스트를 출력합니다 (AI 에이전트 소비용으로 설계).

명령 설명
build <dir> 코드 그래프 빌드 (--incremental)
search <query> 서브그래프를 포함한 하이브리드 벡터 + 키워드 검색 (--top-k, --fast)
search-vector <query> 벡터 유사도 전용 검색 (코드 + 텍스트 듀얼 모델)
search-keyword <query> FTS5 키워드 매칭 전용 검색 (BM25 랭킹)
query 대화형 검색 REPL
communities 커뮤니티 목록 및 검색 (--search, --level)
stats 그래프 통계
node <id> 퍼지 매칭으로 노드 상세 정보
export JSON, GraphML, D3.js로 내보내기
visualize 대화형 HTML 시각화
clean .hedwig-cg/ 데이터베이스 삭제
doctor 설치 상태 점검
mcp MCP 서버 시작 (stdio)
claude install|uninstall Claude Code 통합 관리
codex install|uninstall Codex CLI 통합 관리
gemini install|uninstall Gemini CLI 통합 관리
cursor install|uninstall Cursor IDE 통합 관리
windsurf install|uninstall Windsurf IDE 통합 관리
cline install|uninstall Cline 통합 관리
aider install|uninstall Aider CLI 통합 관리

성능

hedwig-cg 자체 코드베이스 기준 벤치마크 (~3,500줄, 90개 파일, 1,300개 노드):

연산 시간
전체 빌드 ~14초
증분 빌드 (변경 있음) ~4초
증분 빌드 (변경 없음) ~0.4초
콜드 검색 (듀얼 모델) ~2.8초
콜드 검색 (--fast) ~0.2초
웜 검색 ~0.08초
캐시 히트 <1ms
  • 임베딩 모델: ~180MB, ~/.hedwig-cg/models/에 한 번만 다운로드
  • 데이터베이스: ~2MB (SQLite + FTS5 + FAISS 인덱스)
  • 증분 빌드: SHA-256 해싱, 전체 빌드 대비 95%+ 빠름

요구사항

  • Python 3.10+
  • 임베딩 모델 ~180MB (첫 사용 시 캐시)
# 선택사항: PDF 추출
pip install hedwig-cg[docs]

개발

pip install -e ".[dev]"
pytest
ruff check hedwig_cg/

라이선스

MIT License. LICENSE 참조.

기여

기여를 환영합니다! CONTRIBUTING.md 참조.