Graphify-Labs/graphify

Turn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.

Graphify – 코드베이스를 검색 가능한 지식 그래프로 전환

무엇인가요 – Graphify는 프로젝트(소스 코드, 문서, PDF, 이미지, 비디오/오디오)를 분석하고 발견한 개념의 지식 그래프를 생성하는 파이썬 기반 CLI입니다. 그래프는 graph.json으로 저장되며, 인터랙티브한 graph.html로 시각화됩니다. 이후 LLM 기반 개발 보조 도구(Claude, Copilot, Cursor, Gemini 등)에 이 그래프를 쿼리하여 파일을 grep하는 대신 질문에 답하거나 연결을 추적하거나 심볼을 설명하도록 요청할 수 있습니다.

핵심 아이디어

LLM 없는 코드 분석 – Tree-sitter AST를 40개 이상의 언어에서 사용하므로 임베딩이나 벡터 저장소가 생성되지 않으며, 데이터는 당신의 기계에서 외부로 나가지 않습니다.
명시적 vs 추론된 엣지 – 모든 링크는 EXTRACTED(직접 소스에서 읽은) 또는 INFERRED(Graphify의 리졸버가 도출한)로 태그되며, 원시 코드인지 추론된 정보인지 명확히 알 수 있습니다.
코드를 넘어서 – 문서, PDF, 이미지, 비디오/오디오를 추가할 수 있으며, 그 의미 분석은 설정한 LLM(OpenAI, Anthropic, Gemini, Ollama 등)이 수행합니다.
로컬 우선 – 옵션의 의미 분석을 제외하고는 외부 모델에 접근하지 않으며, 중량 작업(AST 추출, 커뮤니티 탐지, 그래프 구축)은 모두 당신의 컴퓨터에서 실행됩니다.
풍부한 쿼리 – graphify query "<질문>", graphify explain "<심볼>", graphify path A B를 통해 하위 그래프를 가져오거나, 노드에 대한 간결한 설명을 얻거나, 두 개념 간의 최단 연결을 확인할 수 있습니다.

빠른 시작 (약 30초)

# CLI 설치 (권장: 격리된 도구)
uv tool install graphifyy   # 또는: pipx install graphifyy

# 개발 보조 도구에 스킬 등록
graphify install

이제 지원되는 어떤 보조 도구나 열고 다음을 입력하세요:

/graphify .

graphify-out/에 다음 세 파일이 생성됩니다:

graph.html – 브라우저에서 열 수 있는 인터랙티브 시각화.
GRAPH_REPORT.md – 고수준 요약, 주요 개념, 제안된 질문.
graph.json – 사용자 정의 쿼리용 완전한 기계가 읽을 수 있는 그래프.

주요 기능

기능	얻을 수 있는 것
고드 노드	가장 연결이 많은 개념 – 코드베이스의 "허브".
커뮤니티	자동 Leiden 클러스터링으로 관련된 하위 시스템을 그룹화. LLM 없이 레이블링.
파일 간 링크	Tree-sitter를 통해 여러 언어에 걸쳐 `calls`, `imports`, `inherits`, `mixes_in`을 해결.
이유 노드	`# NOTE:` / `# WHY:` 주석과 ADR/RFC 인용이 코드에 연결된 일급 노드로 처리됨.
다중미디어	문서, PDF, 이미지, 비디오/오디오를 동일한 그래프에 추가 (적절한 옵션 확장 필요).
로컬 우선 분석	임베딩도 벡터 저장소도 생성하지 않음. 비코드 자산을 위한 옵션 LLM 호출만 있음.
쿼리 언어	평문 질문(`graphify query`), 경로 추적(`graphify path A B`), 노드 설명(`graphify explain`).

설치 세부 사항

단계	명령어	비고
패키지	`uv tool install graphifyy` (또는 `pipx install graphifyy`)	PyPI 이름은 `graphifyy` (이중 y).
스킬 등록	`graphify install [--platform <assistant>] [--project]`	각 보조 도구가 읽는 작은 스킬 파일을 작성. `--project`로 현재 리포지토리에 한정 가능.
옵션 확장	`uv tool install "graphifyy[pdf]"`, `... [neo4j]`, `... [all]` 등	PDF 추출, Neo4j 전송, 비디오 음성 인식, 언어별 파서 등 추가.
사전 요구 사항	Python 3.10+, `uv` (권장) 또는 `pipx`.	macOS: `brew install python@3.12 uv`; Windows: `winget install astral-sh.uv`; Linux: apt 또는 curl 스크립트로 설치.

내부 동작 방식

AST 추출 – Tree-sitter가 각 소스 파일을 분석하여 결정론적 추상 구문 트리를 생성합니다.
엣지 생성 – 명시적 관계(임포트, 호출, 상속)는 EXTRACTED 엣지가 됩니다. Graphify는 추가 연결(예: 클래스가 사용하는 함수)을 해결하고 INFERRED로 표시합니다.
커뮤니티 탐지 – (옵션) Leiden 알고리즘으로 노드를 하위 시스템으로 그룹화합니다.
비코드용 의미 분석 – PDF, 비디오, 사무용 확장을 활성화하면 선택한 LLM이 해당 파일을 처리하고 주변 코드에 연결된 개념 노드를 추가합니다.
내보내기 – 전체 그래프는 JSON으로 저장되며, D3 기반 HTML 뷰어가 인터랙티브하게 렌더링합니다.

벤치마크 (리포지토리에서 보고됨)

LOCOMO (300개 쿼리)에서 Recall@10: 0.497, mem0(0.048) 및 supermemory(0.149)보다 훨씬 높음.
LOCOMO에서 QA 정확도: 45.3% (supermemory 49.7%, mem0 27.3%).
LongMemEval-S (50개 쿼리) QA 정확도: 76% (밀도형 RAG 접근 방식과 동률).
그래프 생성 시 LLM 크레딧: 0 – 핵심 그래프 생성은 LLM을 전혀 호출하지 않습니다.

생태계 및 통합

지원되는 보조 도구 – Claude Code, Cursor, GitHub Copilot CLI, VS Code Copilot Chat, CodeBuddy, Kilo, Aider, OpenClaw, Factory Droid, Trae, Gemini CLI, Hermes, Kimi, Amp, Google Antigravity, 그리고 일반 ~/.agents/skills/ 위치를 읽는 모든 프레임워크.
의미 분석용 백엔드 – OpenAI, Anthropic, Gemini, Azure OpenAI, Ollama, Bedrock 등 (--backend 및 적절한 확장으로 선택).
그래프 싱크 – 그래프를 Neo4j 또는 FalkorDB로 전송하거나 SVG로 내보내기.
후크 – graphify hook install로 Git post-commit 후크를 추가하여 인터프리터 경로를 기록. CI 또는 GUI Git 클라이언트에서도 스킬이 작동하도록 보장.

필요하지 않을 경우

단순한 키워드 검색(grep)이나 전통적인 벡터 스토어 RAG 파이프라인만 필요할 경우, Graphify의 그래프 중심 접근은 과도할 수 있습니다.
PDF/이미지/비디오의 의미 분석에는 외부 LLM API 키가 필요합니다. 없으면 코드만 포함된 그래프만 생성됩니다.

TL;DR

Graphify를 사용하면 어떤 프로젝트도 결정론적이고 로컬에서 생성된 지식 그래프로 변환할 수 있으며, AI 개발 보조 도구가 원시 파일을 스캔하는 대신 이 그래프를 쿼리할 수 있습니다. 빠르고 코드에 대해서는 오프라인으로 작동하며, 대부분의 현대적인 AI 지원 개발 도구와 통합됩니다.