gbrain - AI 에이전트 지식그래프 엔진 오픈소스 기여

gbrain 오픈소스 컨트리뷰터 등재 - 2 commits, 388 추가 / 25 삭제

gbrain 은 코드·문서·이슈를 하나의 지식그래프로 엮어 AI 에이전트에게 검색·합성 능력을 제공하는 오픈소스 엔진입니다(TypeScript, GitHub Star 27,000+). MCP(Model Context Protocol) 서버로 동작해 Claude Code 같은 AI 코딩 에이전트가 사내 지식을 직접 조회할 수 있게 해줍니다.

사내에 이 엔진을 셀프호스팅으로 구축·운영하면서 발견한 결함 2건을 직접 수정해 본가 저장소에 PR로 제출했고, 두 건 모두 머지되어 컨트리뷰터로 등재되었습니다. 단순 오타 수정이 아니라, 실제 운영 환경에서만 드러나는 엔진 레벨의 결함을 원인 분석부터 테스트까지 갖춰 기여했다는 점에 의미가 있습니다.

기여 내역

1. Kotlin 코드 호출그래프 추출 지원

garrytan/gbrain#2574 · feat(code-graph)

기존 엔진은 코드 호출그래프를 TypeScript/JavaScript와 Java·Go·Rust에서만 추출했고, Kotlin은 지원하지 않아 백엔드 코드에서 “이 함수를 호출하는 곳이 어디인가”라는 질의가 항상 빈 결과를 반환했습니다. Kotlin 기반 서비스가 많은 환경에서는 영향 범위 분석 기능이 사실상 동작하지 않는 상태였습니다.

  • 기존 Java/Go/Rust와 동일한 bare-token 방식으로 Kotlin 호출 엣지 추출 구현
  • 언어별 추출기 간 동작 일관성(parity) 확보
  • 회귀 방지를 위한 단위 테스트 추가

2. 무상태 컨테이너 환경의 동기화 상태 오탐 수정

garrytan/gbrain#2908 · fix(doctor)

컨테이너 기반 배포(Docker on AWS Elastic Beanstalk / Kubernetes 등)에서 재시작 때마다 정상적인 소스가 “동기화 실패”로 잘못 판정되어 모니터링 경고가 반복 발생하는 문제를 발견했습니다.

원인은 진단 로직이 상태를 판별하는 방식에 있었습니다. 재시작으로 로컬 클론이 사라지면 git HEAD를 조회할 수 없는데, 이때 마지막 동기화 시각(wall-clock)으로 폴백하지만 변경이 없는 동기화는 이 시각을 갱신하지 않기 때문에, 조용한 저장소일수록 오래된 것으로 오판되는 구조였습니다. 실제 운영 환경(소스 16개)에서 재시작 후 12개 클론이 미복구 상태가 되며 건강 점수가 70점에서 25~35점까지 떨어지고 경고가 연쇄 발생했습니다.

  • git 프로브 결과를 unchanged / changed / unavailable 3-상태로 분리해 “판별 불가”와 “실제 변경 있음”을 구분
  • 판별 불가 상태에서는 DB에 저장된 콘텐츠 시각 기준으로 폴백해 오탐 제거
  • 실제로 밀린 작업은 여전히 정상 감지되도록 보수적으로 설계
  • 기존 계약 유지를 검증하는 테스트 13종 추가

성과

  • 머지된 PR 2건 (2026-07-28)
  • 변경량 +388 / −25 (테스트 코드 277줄 포함)
  • 전체 컨트리뷰터 120명 중 한 명으로 등재

사용 기술

  • TypeScript (엔진 본체)
  • Kotlin (호출그래프 추출 대상 언어)
  • Git / GitHub PR 워크플로
  • MCP (Model Context Protocol)
  • Bun · Zod · PostgreSQL(pgvector)

링크