Graphify Knowledge Integration

Graphify GitHub repository report

원본 Markdown source의 핵심 내용을 브라우저에서 읽기 위한 HTML counterpart입니다.

Source role

Technical implementation and operational evidence

Graphify GitHub 저장소 분석 보고서

Executive summary

Graphify GitHub 저장소(https://github.com/safishamsi/graphify)는 AI coding assistant가 저장소 전체를 매번 읽거나 검색하지 않고, 사전에 생성된 knowledge graph를 질의하도록 만드는 Python 기반 CLI/스킬 프로젝트로 공개되어 있다. 공개 README 기준 지원 대상은 Claude Code, Codex, OpenCode, Cursor, Gemini CLI 등 여러 assistant이며, 입력 범위는 코드뿐 아니라 문서, PDF, 이미지, 비디오/오디오, SQL schema, Terraform/HCL 등으로 확장된다.

도입 관점에서 가장 중요한 기능은 세 가지다. 첫째, /graphify . 또는 플랫폼별 명령으로 현재 폴더를 분석해 graphify-out/graph.html, GRAPH_REPORT.md, graph.json을 만든다. 둘째, graphify query, path, explain, MCP server를 통해 assistant가 원본 파일 전체 대신 그래프 부분집합을 조회할 수 있게 한다. 셋째, graphify hook install과 always-on assistant 설정으로 commit 이후 graph 갱신과 query-first 워크플로를 유도한다.

저장소는 활발히 움직이는 신호가 있다. GitHub 공개 페이지는 v8 브랜치, 659 commits, docs/, graphify/, tests/, tools/ 등의 구조를 보여준다. CHANGELOG.md에는 2026-06-06 0.8.33까지 릴리스 내역이 있으며, 최근 항목은 Python import edge, annotation noise 제거, ghost duplicate node 병합, Terraform/HCL 지원, hook hardening, query logging, progressive-disclosure skill 등을 다룬다. 다만 GitHub UI에서 표시되는 star/fork/issue/PR 수와 제3자 페이지의 수치가 서로 달라 인기도 지표는 별도 확인이 필요하다.

결론적으로 Graphify는 Claude/Codex류 도구의 저장소 기억 문제를 줄이려는 실험적이지만 꽤 구체적인 구현체다. 대형 저장소에서 반복적인 구조 질문이 많고, generated graph의 보안/갱신/충돌 관리를 감당할 수 있는 팀에는 파일럿 가치가 있다. 반대로 작은 저장소, 단발성 작업, 민감 코드 구조를 산출물로 남기기 어려운 환경에서는 기본 검색과 명시적 컨텍스트 관리가 더 단순할 수 있다.

Source profile

  • 대상 URL: https://github.com/safishamsi/graphify
  • 저장소 유형: 공개 GitHub 저장소, Python 패키지/CLI/assistant skill 프로젝트
  • 기본 공개 브랜치로 보이는 브랜치: GitHub 페이지에서 v8로 표시됨
  • 라이선스: 공개 페이지와 pyproject.toml 기준 MIT license
  • 패키지명: graphifyy, CLI 명령은 graphify
  • Python 요구사항: >=3.10
  • 핵심 런타임 의존성: networkx, datasketch, rapidfuzz, 다수의 tree-sitter-* grammar
  • 선택 의존성: mcp, neo4j, pdf, office, google, video, postgres, terraform, openai, anthropic, gemini, ollama, bedrock, sql, chinese, dm 등
  • 공개 저장소 구조: .github/, docs/, graphify/, tests/, tools/, worked/, README.md, ARCHITECTURE.md, CHANGELOG.md, SECURITY.md, Dockerfile, pyproject.toml, uv.lock
  • 확인한 공개 소스: GitHub 저장소 페이지, README 렌더링, pyproject.toml, ARCHITECTURE.md, SECURITY.md, CHANGELOG.md, 기존 Graphify 영상 분석 보고서

접근 제한은 없었다. 다만 이 보고서는 저장소 전체 clone 및 전체 소스 정적 분석이 아니라 공개 웹에서 접근 가능한 GitHub 렌더링과 일부 raw 문서를 근거로 한다.

Key claims or offerings

확인 가능한 공개 정보

  • Graphify는 폴더 안의 코드, 문서, PDF, 이미지, 비디오 등을 knowledge graph로 변환한다고 설명한다.
  • 기본 사용 흐름은 설치 후 assistant에서 /graphify .를 실행하는 방식이다. Codex는 README 기준 $graphify를 사용하고, ~/.codex/config.toml에 multi_agent = true 설정을 추가하라는 안내가 있다.
  • 생성 산출물은 graphify-out/graph.html, GRAPH_REPORT.md, graph.json이다.
  • graphify export callflow-html은 Mermaid 기반 architecture/call-flow HTML을 생성한다고 설명한다.
  • graphify query, graphify path, graphify explain은 그래프를 직접 질의하는 명령이다.
  • graphify hook install은 post-commit/post-checkout hook을 설치해 graph 자동 갱신을 돕는 기능으로 설명된다.
  • graphify install --project는 .claude/skills/, .agents/skills/ 등 현재 저장소 안에 project-scoped skill 파일을 설치할 수 있다고 설명한다.
  • README는 code extraction은 tree-sitter 기반 로컬 처리이며, docs/PDF/images 등은 assistant 모델 API를 통해 semantic extraction된다고 설명한다.
  • MCP stdio 또는 HTTP server로 query_graph, get_node, get_neighbors, shortest_path, PR 관련 도구를 노출할 수 있다고 설명한다.
  • SECURITY.md는 URL fetch, oversized download, path traversal, XSS, prompt injection, YAML frontmatter injection, symlink traversal 등 위협과 완화책을 문서화한다.

작성자 추론

Graphify의 제품 포지션은 단순 시각화 도구라기보다 AI assistant용 저장소 메모리 계층에 가깝다. graph.html은 사람이 확인하는 UI이고, 실무적 핵심은 graph.json, GRAPH_REPORT.md, query/MCP 인터페이스, assistant 설치 파일이다. 즉 사람이 그래프를 구경하는 것보다, assistant가 코드베이스 질문에서 graph를 먼저 쓰도록 만드는 것이 중심 설계다.

검증 필요 주장

  • README가 암시하는 토큰 절감, 검색 효율, 대형 저장소 효과는 저장소별 벤치마크가 필요하다.
  • GitHub star/fork 수와 외부 popularity 지표는 공개 페이지 간 불일치가 있어 단정하지 않는 것이 좋다.
  • 지원 assistant 목록은 넓지만, 각 플랫폼 통합의 실제 안정성은 플랫폼별 버전, hook 지원 여부, project-scoped install 동작에 따라 따로 검증해야 한다.

Technical or workflow implications

저장소 구조와 아키텍처

ARCHITECTURE.md는 파이프라인을 detect() -> extract() -> build_graph() -> cluster() -> analyze() -> report() -> export()로 설명한다. 각 단계는 독립 모듈 함수로 분리되고, plain Python dict와 NetworkX graph를 주고받으며, graphify-out/ 외부에는 부작용을 만들지 않는다는 설계를 내세운다.

모듈 책임은 다음처럼 나뉜다.

  • detect.py: 분석 대상 파일 수집과 필터링
  • extract.py: 파일별 node/edge 추출
  • build.py: 추출 결과를 NetworkX graph로 구성
  • cluster.py: community 속성 부여
  • analyze.py: god nodes, surprising connections, suggested questions 등 분석
  • report.py: GRAPH_REPORT.md 렌더링
  • export.py: Obsidian vault, JSON, HTML, SVG 등 내보내기
  • callflow_html.py: architecture/call-flow HTML 생성
  • ingest.py: URL을 corpus로 추가
  • security.py: URL/path/label 검증
  • serve.py: MCP server
  • watch.py: 파일 변경 감지
  • benchmark.py: corpus vs subgraph token 비교

이 구조는 기능 확장을 위한 분리도가 비교적 명확하다. 새 언어 extractor를 추가하려면 tree-sitter parse, suffix dispatch, watched extensions, dependency, fixture/test를 함께 추가하라는 절차가 문서화되어 있다.

사용법과 팀 워크플로

실무 팀에서의 기본 실험 흐름은 다음과 같이 잡을 수 있다.

  • uv tool install graphifyy 또는 pipx install graphifyy로 CLI를 설치한다.
  • graphify install --project --platform codex처럼 대상 assistant와 저장소 범위를 명시해 skill을 설치한다.
  • 대표 저장소에서 /graphify . 또는 Codex의 $graphify .로 그래프를 생성한다.
  • 생성된 graphify-out/의 graph.html, GRAPH_REPORT.md, graph.json을 확인한다.
  • 동일 질문 세트를 Graphify 미사용/사용 조건으로 반복해 정답성, 근거 정확도, 토큰, 시간, rebuild 비용을 비교한다.
  • hook은 초기 생성 결과와 보안 검토 후 graphify hook install로 제한적으로 켠다.
  • graphify-out/cost.json, cache, query log, graph artifact를 git에 포함할지 정책화한다.

README는 graphify-out/을 commit해서 팀원이 같은 지도를 공유하는 방식을 권한다. 이 선택은 onboarding에는 유리하지만, 저장소 크기 증가, merge conflict, 민감 구조 노출, 오래된 graph 사용 문제를 함께 만든다. Graphify는 merge driver와 hook을 제공한다고 설명하지만, 실제 팀 브랜치 전략에서 충돌이 사라지는지는 파일럿에서 확인해야 한다.

보안/운영 관점

긍정적 신호는 SECURITY.md와 changelog에 보안 관련 설계가 공개되어 있다는 점이다. URL fetch 검증, private/loopback/link-local 차단, 다운로드 크기 제한, graph path 제한, label escaping, symlink 미추적, shell=True 미사용 등의 문서화는 개발 도구로서 필요한 기본 위협 모델을 갖추려는 신호다.

동시에 운영 리스크도 뚜렷하다. graphify query와 MCP query는 기본적으로 ~/.cache/graphify-queries.log에 질문, corpus, 반환 node 수, duration 등을 JSONL로 남긴다고 README가 설명한다. 응답 전문은 기본 저장하지 않는다고 하지만, 질문 자체에 민감한 모듈명이나 고객명이 들어갈 수 있다. 팀 도입 전 query log 비활성화 또는 위치 정책이 필요하다.

Relation to Graphify / Claude Code memory problem

기존 Graphify 영상 보고서는 Graphify를 Claude Code/Codex류 coding assistant의 저장소 기억 지도라고 해석했다. 이번 GitHub 저장소 분석은 그 해석을 대체로 강화한다. README와 아키텍처 문서는 Graphify가 단순한 문서 요약기가 아니라, assistant가 codebase 질문에서 grep이나 무차별 파일 읽기 대신 queryable graph를 먼저 보도록 만드는 도구임을 명확히 보여준다.

기존 보고서에서 핵심 문제는 assistant가 대형 저장소를 매번 새로 탐색하면서 토큰과 시간이 늘어난다는 점이었다. GitHub README의 Make your assistant always use the graph 섹션은 이 문제를 직접 겨냥한다. Claude Code나 Gemini CLI처럼 hook이 가능한 플랫폼에서는 검색/읽기 도구 호출 전에 graph 경로를 권장하고, Codex/OpenCode/Cursor 등에서는 persistent instruction file로 query-first 지침을 주는 방식이다.

다만 저장소 자료는 영상의 토큰 절감 주장을 그대로 입증하지 않는다. 저장소는 메커니즘과 사용법, 최근 개선 내역을 보여주지만, 특정 저장소에서 70x 또는 그에 준하는 절감을 일반화할 근거는 별도 benchmark 없이는 부족하다. 도입 판단에서는 Graphify가 기억 문제를 줄일 가능성이 있는 구조적 장치를 제공한다는 점과, 실제 비용 절감률은 팀 내부 실험으로만 확정해야 한다는 점을 분리해야 한다.

Adoption value and risks

도입 가치

  • 대형 저장소의 architecture, call flow, module responsibility 질문을 반복하는 팀에는 저장소 지도 역할을 할 수 있다.
  • 신규 팀원 onboarding, legacy code 파악, PR 영향 범위 조사, auth/database/agent pipeline 같은 cross-cutting flow 탐색에 적합하다.
  • code-only corpus는 README 기준 tree-sitter 로컬 처리이므로 API key 없이 오프라인 실행 가능한 범위가 있다.
  • docs, PDFs, images, videos까지 포함하면 코드와 설계 문서 사이의 관계를 assistant 질의에 반영할 수 있다.
  • graph.json과 MCP server를 통해 agent가 구조화된 subgraph를 반복 조회할 수 있다.
  • changelog가 촘촘하고 최근 릴리스가 많아 유지관리 활동 신호가 있다.

주요 리스크

  • Graph drift: 코드 변경 후 graph가 갱신되지 않으면 assistant가 오래된 구조로 판단한다.
  • Generated artifact 정책: graphify-out/을 commit하면 저장소 크기, 리뷰 노이즈, merge 정책, 보안 노출 문제가 생긴다.
  • Hook friction: post-commit/post-checkout hook이 느리거나 불안정하면 개발자 경험을 해친다.
  • Query logging: 질문 로그가 로컬 cache에 남으므로 민감 정보 취급 정책이 필요하다.
  • Semantic extraction 비용: docs/PDF/images는 모델 API를 사용하므로 비용, 데이터 반출, provider 선택, 재현성 문제가 생긴다.
  • Platform sprawl: 지원 assistant가 많아 보이는 것은 장점이지만, 각 플랫폼별 install/hook 동작은 작은 호환성 문제가 자주 생길 수 있다. 실제로 changelog에는 여러 플랫폼 설치 경로와 hook 관련 fix가 반복된다.
  • Open-source maturity: 활발한 변경은 긍정적이지만, 빠른 릴리스와 많은 fix는 API/동작 안정성이 아직 변할 수 있다는 뜻이기도 하다.
  • 인기도 수치 불일치: GitHub 렌더링과 외부 페이지의 star/commit 수치가 달라, popularity를 도입 근거로 쓰기 전 원본 GitHub API 또는 직접 페이지 확인이 필요하다.

팀 파일럿 체크리스트

  • 대표 질문 20개 이상을 만든다: architecture flow, impact analysis, ownership, dependency path, docs rationale, PR risk를 분리한다.
  • Graphify 미사용 baseline과 사용 조건의 답변 정확도, 근거 파일 정확도, 토큰, latency를 기록한다.
  • graphify-out/에 민감 경로, 주석, 내부 시스템명, 고객명, secret-like string이 포함되는지 검사한다.
  • GRAPHIFY_QUERY_LOG_DISABLE=1 또는 log 경로 정책을 정한다.
  • graphify hook install을 켜기 전 commit 시간 증가와 dirty tree loop 가능성을 측정한다.
  • graph artifact를 git에 포함할지, CI artifact로 둘지, developer-local cache로 둘지 결정한다.
  • 문서/PDF/image 처리가 필요한 경우 backend와 data residency 요구사항을 먼저 정한다.
  • Codex에서는 $graphify 사용 방식과 multi_agent = true 설정이 실제 환경에서 맞는지 확인한다.

What needs independent verification

  • 실제 저장소 clone 후 pytest tests/ -q가 통과하는지 확인해야 한다. 이 보고서는 테스트를 실행하지 않았다.
  • uv tool install graphifyy, pipx install graphifyy, graphify install --project --platform codex가 현재 OS와 Python 버전에서 정상 동작하는지 확인해야 한다.
  • README의 code-only offline claim과 docs/PDF/images API 사용 경계가 실제 실행 로그와 네트워크 관찰에서 맞는지 확인해야 한다.
  • GitHub star/fork/open issue/open PR 수는 공개 페이지마다 수치가 다르게 관찰되어 원본 GitHub API 또는 로그인 상태의 GitHub UI에서 재확인해야 한다.
  • graphify-out/ commit, merge driver, hook rebuild가 실제 팀 브랜치 전략에서 충돌 없이 동작하는지 검증해야 한다.
  • MCP HTTP server를 공유 호스트에 노출할 경우 --api-key, bind host, network ACL, log 정책, graph 파일 접근권한을 별도 보안 리뷰해야 한다.
  • semantic extraction 결과의 INFERRED, AMBIGUOUS edge가 실제 코드/문서 근거와 맞는지 표본 감사를 해야 한다.
  • 영상에서 언급된 토큰 절감 수치는 GitHub 저장소 자료만으로는 입증되지 않는다. 내부 benchmark 없이는 비용 절감률을 도입 근거로 쓰면 안 된다.

Source note

  • 사용 URL: https://github.com/safishamsi/graphify
  • 추가 확인 URL: https://raw.githubusercontent.com/safishamsi/graphify/v8/pyproject.toml
  • 추가 확인 URL: https://raw.githubusercontent.com/safishamsi/graphify/v8/ARCHITECTURE.md
  • 추가 확인 URL: https://raw.githubusercontent.com/safishamsi/graphify/v8/SECURITY.md
  • 추가 확인 URL: https://raw.githubusercontent.com/safishamsi/graphify/v8/CHANGELOG.md
  • 기존 맥락 파일: data/runtime/write-agents/AI engineering video analyses collection/md/graphify-claude-code-memory-problem-report.md
  • 접근 가능 범위: 공개 GitHub 저장소 페이지, README 렌더링, 일부 raw Markdown/TOML 파일, 기존 로컬 보고서
  • 수집 시점: 2026-06-07 Asia/Seoul 기준
  • 수집 한계: 저장소 전체 clone, 전체 코드 리뷰, 패키지 설치, 테스트 실행, 실제 Graphify graph 생성은 수행하지 않았다. GitHub UI 일부 영역은 로딩 오류 문구를 포함했고, popularity/최근성 수치는 공개 페이지와 검색 결과 간 불일치가 있어 보수적으로 해석했다.