Graphify는 폴더를 지식 그래프로 바꾼다, 71.5x에는 조건이 있다

Graphify가 이번 주에만 스타 약 7,300개를 얻으며 GitHub 주간 트렌드 상위권에 올랐고, 누적 스타는 137,000을 넘어섰다. 홍보 문구는 한 줄이다. 코딩 에이전트에게 폴더를 가리키고 /graphify .를 입력하면, 그 안에 있는 모든 것의 지식 그래프가 돌아온다.

흥미로운 것은 그래프 자체가 아니다. 그래프 옆에 붙은 숫자다. 원본 파일을 읽는 방식과 비교해 쿼리당 토큰이 71.5x 적게 든다. 이게 일반적으로 성립한다면, 이것은 곁들일 만한 편의 도구가 아니라 에이전트가 얼마나 많은 컨텍스트를 들고 있어야 하는지에 대한 변화다.

어디서 나왔나

저자 safishamsi는 이 프로젝트를 Andrej Karpathy의 특정한 습관에 대한 답으로 설명한다. 논문, 트윗, 스크린샷, 메모를 /raw 폴더에 계속 밀어 넣고는 나중에 아무것도 찾지 못하는 그 습관이다. 공감 가는 문제이고, 대부분의 사연보다 정직한 기원이기도 하다. 시장이 아니라 실패 유형을 말하고 있기 때문이다.

내세우는 목표는 "내 문서를 검색한다"보다 좁다. 세션 사이에서 살아남는 지속적인 무언가를 만들고, 무엇을 추론했고 무엇을 추출했는지 분명히 밝히는 것. 그래프의 모든 엣지에는 EXTRACTED, INFERRED, AMBIGUOUS 중 하나가 붙는다. 흔치 않은 설계 선택이고, 내가 보기에는 이 전체에서 가장 값진 부분이다.

실제로 하는 일

설치는 명령 두 개다. 그렇다, PyPI 패키지 이름은 당분간 틀려 있다:

pip install graphifyy && graphify install

Y가 두 번 겹치는 것은 오타가 아니라 이름 분쟁의 결과다. CLI와 skill 명령은 여전히 둘 다 graphify다. 윈도우에서 설치 후 명령이 인식되지 않는다면 Python의 Scripts 폴더를 PATH에 넣거나, pipx install graphifyy를 써서 문제 자체를 건너뛰면 된다.

그다음 Claude Code 안에서, 아무 디렉터리에서나:

/graphify .
/graphify ./raw --mode deep
/graphify query "what connects attention to the optimizer?"
/graphify path "DigestAuth" "Response"
/graphify explain "SwinTransformer"

결과물은 graphify-out/에 떨어진다. 눌러 가며 볼 수 있는 인터랙티브 graph.html, vault로 열리는 obsidian/ 폴더, 몇 주 뒤에 질의해도 아무것도 다시 읽지 않아도 되는 영속적인 graph.json, SHA256을 키로 삼아 바뀐 파일만 처리하는 cache/, 그리고 god nodes라 부르는 최고 차수 개념들과 복합 점수로 줄 세운 "의외의 연결"을 담은 GRAPH_REPORT.md가 있다. 이 점수에서 코드에서 논문으로 가는 엣지는 코드에서 코드로 가는 엣지보다 무겁게 계산된다.

멀티모달 부분은 마케팅이 아니라 실제 구현이다. 코드 파일은 tree-sitter로 AST를 파싱하고 호출 그래프를 한 번 더 훑는다. Markdown, PDF, 이미지는 Claude를 거친다. 산문에서 개념과 관계를, 논문에서 인용을 캐내고, 스크린샷과 도해, 화이트보드 사진, 다른 언어로 된 이미지에는 시각 능력을 쓴다.

이 도구 안에서 살고 싶지 않은 사람에게 중요한 내보내기 형식도 있다. --svg, Gephi나 yEd용 --graphml, 그리고 --neo4j는 돌아가는 데이터베이스를 요구하는 대신 cypher.txt를 만들어 준다. 스택은 NetworkX, graspologic을 통한 Leiden 클러스터링, tree-sitter, vis.js다. 서버는 없다. Claude 호출을 빼면 아무것도 기계 밖으로 나가지 않는다.

71.5x라는 숫자 뜯어보기

벤치마크 코퍼스는 파일 52개다. Karpathy의 저장소, 논문 다섯 편, 이미지 네 장. 결과는 원본 파일을 읽는 것과 비교해 쿼리당 토큰이 71.5x 적다는 것이다.

이 저장소는 이 수치가 규모에 따라 어떻게 달라지는지에 대해 유난히 정직하다. 그 정직함이 드물어서 요점을 인용할 만하다. 토큰 절감은 코퍼스가 커질수록 늘어난다. 반면 파일이 여섯 개일 때 그래프의 가치는 압축이 아니라 구조의 명료함이다. 여섯 개면 어차피 컨텍스트 윈도에 들어가기 때문이다. 이들이 graphify 소스와 Transformer 논문으로 직접 든 예시는 5.4x다. 합성 라이브러리 파일 여섯 개에서는 대략 1x다.

이 모양이 맞다. 코퍼스가 이미 컨텍스트 윈도 안에 들어온다면, 아끼는 것은 토큰이 아니라 지도를 사는 것이다. 서로 다른 유형이 섞인 파일 50개라면 절감은 실재하고 크다. 대안이 파일을 한 번 읽는 것이 아니라, 여러 턴에 걸쳐 반복해서 읽는 일이기 때문이다. 에이전트는 그때마다 자기가 어디쯤인지 잃는다.

이 비교는 한쪽으로는 graphify에 조금 후하고, 다른 쪽으로는 과소평가다. 원본 파일 읽기는 최악의 기준선이고, 잘 다듬은 검색 인덱스라면 원본 파일보다 비교적 좋아 보일 것이다. 하지만 검색 인덱스가 돌려주는 것은 구절이고, graphify가 돌려주는 것은 관계다. "어텐션과 옵티마이저를 잇는 것은 무엇인가"의 답은 구절이 아니라 경로다. 서로 다른 종류의 질의이고, 벡터 스토어가 감당할 수 있는 것은 그중 하나뿐이다.

"벡터 스토어 없음"은 진짜 아키텍처 입장이다

대부분의 검색 시스템은 텍스트를 잘라 임베딩하고 최근접 이웃 탐색을 한다. Graphify는 그 전부를 건너뛴다. 코드는 로컬에서 결정적으로 AST를 파싱하고, 산문과 이미지는 LLM으로 추출한 뒤 그래프를 만든다. 임베딩 단계도, 유사도 검색도 없다.

대신 얻는 것은 설명 가능성이다. 두 가지가 왜 연결되어 있는지 물으면 엣지가 돌아온다. 각 엣지에는 원문에서 추출한 것인지 모델이 추론한 것인지가 적혀 있다. 벡터 인덱스는 그런 말을 못 한다. 코사인 거리가 작았다는 것까지만 알려줄 수 있다.

대가는 커버리지다. 그래프는 추출기가 찾은 것만 안다. 추출 단계가 관계 하나를 놓쳤다면 어떤 쿼리도 그것을 끌어올리지 못하고, 흐릿한 대체 경로도 없다. AMBIGUOUS 태그는 그 사실을 정직하게 인정한 것이고, --mode deep 플래그가 존재하는 이유는 기본 단계가 엣지 추론에 보수적이기 때문이다.

어디서 제값을 하는가

이런 도구에 대한 내 경험으로는 두 가지 워크플로다.

첫째는 낯선 코드베이스에 올라타는 일이다. "함수 X가 어디 있나"가 아니다. 그건 grep이면 된다. "여기서 구조를 떠받치는 개념은 무엇이고, 그중 어느 것이 과금 코드를 건드리는가"다. 이건 그래프 질문이고, god nodes 보고서는 2분이면 읽을 수 있는 형태로 답한다.

둘째는 멀티 에이전트 상황이다. 여러 에이전트가 병렬로 코드를 쓸 때, 저장소에 대한 각자의 모델은 몇 분 안에 낡는다. 커밋마다 다시 만드는 그래프(graphify hook install이 post-commit 훅을 설치한다)나 파일 저장 시점에 다시 만드는 그래프(--watch)는, 서로 어긋난 다섯 개의 추측 대신 같은 최신 지도를 모든 에이전트에게 준다.

분명한 한계도 있다. 이것은 우선 Claude Code의 skill로 만들어졌다. 수동 설치 경로는 SKILL.md를 ~/.claude/skills/graphify/에 넣고 CLAUDE.md에 한 줄을 추가한다. 다른 클라이언트가 쓸 수 있는 MCP 서버 모드(--mcp)도 있지만, 사용성은 분명 하나의 생태계에 맞춰 최적화되어 있다. 그리고 Claude 의존성은 큰 코퍼스에서 추출 단계에 실제 비용이 든다는 뜻이다.

정직한 결론

Graphify는 검색 엔진이 아니고, 검색 엔진으로 평가해서도 안 된다. 이것은 폴더 안에 무엇이 있는지에 대한, 지속적이고 검사 가능한 모델이며, 어디를 추측했는지 알려준다는 특이한 성질을 갖고 있다. 스타 137,000개를 모으고 일주일 내내 트렌드에 머문 프로젝트에서 흥미로운 질문은 이 그래프가 대단한가가 아니다. 추론에 태그를 붙이는 습관이, 그냥 답만 원하는 사용자들과 부딪혀 살아남는가다.

내 짐작으로는 대부분 query만 쓰고, 엣지 라벨은 무시하고, graph.json은 열어 보지도 않을 것이다. 계속 쓰는 사람은 답안지가 아니라 지도가 필요했던 사람들이다.