AI 에이전트에게 "이걸 바꾸면 무엇이 망가지나요?"라고 물을 수 있는 로컬 지식 그래프(Knowledge Graph)를 구축했습니다

새로운 AI 코딩 세션을 시작할 때마다 매번 똑같은 일이 발생합니다. 제 아키텍처, 컨벤션(Conventions), 서비스 의존성(Service dependencies)을 다시 설명해야 합니다. AI는 기억하지 못합니다. store.py가 다른 8개의 모듈에 의해 임포트(Import)된다는 사실도, Milenko가 인증(Auth) 서비스를 담당하고 있다는 점도, postgres가 단일 장애점(Single point of failure)이라는 사실도 알지 못합니다.

그래서 저는 AI 에이전트에게 코드베이스에 대한 영구적인 메모리를 제공하는 로컬 지식 그래프(Knowledge Graph)인 Knowledge Master를 구축했습니다.

"그저 그런 RAG"와 무엇이 다른가

대부분의 RAG(Retrieval-Augmented Generation) 도구는 코드를 벡터(Vectors)로 임베딩(Embedding)하고 "유사한 청크(Chunks)"를 반환합니다. 그것은 그럴싸한 grep일 뿐입니다. 관계(Relationships)를 이해하지 못합니다.

Knowledge Master는 실제 **그래프(Graph)**를 구축합니다:

Repo → USES_TECH → Python, FastAPI, Docker
Repo → DEFINES_SERVICE → auth-service → DEPENDS_ON → postgres
Person → AUTHORED → Document → IMPORTS → Document
...

이를 통해 평면적인 검색(Flat search)으로는 답할 수 없는 질문에 답할 수 있습니다:

"이걸 바꾸면 무엇이 망가지나요?"

$ km blast-radius store.py
💥 Blast radius: store.py
├── Definite impact
...

이것은 텍스트 유사성이 아니라, 실제 임포트 의존성(Import dependencies)을 추적하기 위해 실제 정적 분석(Static analysis) — Python AST, TypeScript/Go/Rust/Java/C#을 위한 tree-sitter — 를 사용합니다.

"이걸 건드려도 안전할까요?"

$ km safe-to-change auth/service.py
Risk: RISKY
├── Blast radius: 12 entities
...

폭발 반경(Blast radius)과 테스트 커버리지(Test coverage) 탐지를 결합하여 위험 점수(Risk score)를 산출합니다: safe / risky / dangerous.

"이 코드의 소유자는 누구인가요?"

$ km who-owns src/payments/stripe.py
Owner: Alex (weight: 0.85)

최신성(Recency)에 따라 가중치를 둔 Git blame — 오래된 기록보다 최근의 변경 사항이 더 높은 비중을 차지합니다.

작동 원리

Your repos
    ↓ km index
┌─────────────────────────────┐
...

모든 것은 로컬에서 실행됩니다:

• FalkorDB — 벡터 검색 (vector search) 기능이 내장된 그래프 데이터베이스 (graph database) (단일 Docker 컨테이너)
• Ollama — 로컬 임베딩 (local embeddings) (nomic-embed-text, 274MB)
• Tree-sitter — 7개 언어에 대한 구조적 코드 파싱 (structural code parsing)
• 클라우드 없음, API 키 없음, 데이터가 기기를 떠나지 않음

지원되는 7개 언어

언어	정적 분석 (Static Analysis)
Python	AST 임포트 그래프 (import graph), 함수/클래스 추출
...

MCP 서버 — AI 에이전트가 직접 사용

Knowledge Master는 모델 컨텍스트 프로토콜 (Model Context Protocol, MCP)을 통해 8가지 도구를 제공합니다:

도구	AI 에이전트가 할 수 있는 일
search	재순위화 (re-ranking)를 포함한 의미론적 검색 (semantic search)
...

어떤 AI 도구든 설정은 명령어 하나로 완료됩니다:

km setup cursor    # 또는 claude, kiro, copilot, amazonq

사용해보기

pipx install knowledge-master
km start
km index ~/your-project
...

링크

• GitHub: github.com/subzone/knowledge-master
• PyPI: pipx install knowledge-master
• Docs: subzone.github.io/knowledge-master

피드백을 환영합니다 — 특히 다음 사항에 대해 궁금합니다:

• 다음에 어떤 언어/프레임워크를 우선적으로 지원해야 할까요?
• 더 깊은 호출 그래프 (call-graph) 분석을 원하시나요, 아니면 더 많은 커넥터 (Slack, Jira 등)를 원하시나요?
• MCP 통합이 올바른 방향일까요, 아니면 VS Code 확장 프로그램이 더 유용할까요?

MIT 라이선스, 오픈 소스이며, AI에게 코드베이스를 매번 다시 설명하는 것에 지친 개발자들을 위해 만들어졌습니다.