Personal open source work · built on my own time, not company work

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 호출 엣지 추출
  • 언어별 추출기 동작 통일
  • 회귀 방지 단위 테스트 추가

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)

링크