Graphify는 마크다운도 된다 — 그래도 안 쓴 이유

개인 위키를 구축하는 사람이 늘면서, 방법론도 다양해지고 있다.

그 중에서 최근 주목받는 흐름이 있다. 마크다운 파일을 그래프 DB로 변환해서 관계를 시각화하고 쿼리하는 방식이다. 파일이 수십 개를 넘어가면 index.md나 텍스트 검색만으로는 연결 구조를 파악하기 어려워진다. 어떤 개념이 어떤 주제와 얼마나 연결돼 있는지, 단순 목록으로는 보이지 않는다. 그래프 DB는 이 문제를 명시적으로 푼다.

Graphify는 이 수요를 겨냥해서 나온 도구다. PKM(개인 지식 관리) 커뮤니티에서 추천이 늘고 있고, "위키가 커지면 Graphify 써봐라"는 이야기를 심심찮게 만난다.

나도 궁금해서 직접 써봤다. 처음엔 "안 되는 도구"라고 결론냈다. 그런데 그 결론이 틀렸다.

---

raw/ 계층에 Web Clipper를 연결했다

Graphify를 만나게 된 건 Obsidian Web Clipper 세팅을 마친 직후였다.

이날 저장소 구조를 4계층으로 정리한 다음, 수집 파이프라인을 붙이기로 했다. 자료가 raw/로 들어오는 경로를 명확히 하는 게 목표였다. 템플릿 10종을 설계해서 Obsidian Web Clipper에 등록했다.

raw/articles/  ← 아티클 클리핑
raw/videos/    ← 영상 트랜스크립트
raw/books/     ← 책 챕터 노트
raw/journals/  ← 대화 백업, 인사이트
raw/podcasts/  ← 팟캐스트 에피소드

각 템플릿에는 Why This Matters, Summary Seed, Extraction Priorities 같은 힌트 섹션을 넣었다. /wiki:ingest가 수집된 자료의 분석 방향을 빠르게 잡을 수 있도록 하는 구조다.

세팅 중 문제가 하나 나왔다. fallback 템플릿의 https://* 전역 트리거가 모든 URL을 가로챘다. 해결은 간단했다. 범용 템플릿은 트리거를 비우고 수동 선택 전용으로 운용했다.

---

첫 클리핑, 그리고 한 가지 질문

파이프라인이 준비되자 첫 자료를 수집했다.

마침 Graphify에 관심이 생긴 시점이었다. 위키가 계속 커지고 있었고, 관계 구조를 더 잘 볼 수 있는 방법이 없을까 찾아보던 중이었다. graphify.net/kr/에 있는 "AI 코딩 어시스턴트를 위한 지식 그래프 스킬" 아티클이 눈에 띄었다. Web Clipper 첫 번째 클리핑 대상으로 골랐다.

템플릿 구조는 잘 동작했다. Why This Matters, Summary Seed 섹션이 채워졌다. 그런데 아티클을 읽다가 한 가지 질문이 생겼다.

이걸 우리 위키에 넣으면 어떨까?

그래서 직접 설치해보기로 했다.

---

graphify update를 돌렸는데 안 됐다 — 성급한 결론이었다

pip install graphifyy

graphifyy 0.4.23이 설치됐다. 위키 디렉토리를 대상으로 바로 테스트했다.

graphify update wiki
# → No code files found
# → Nothing to update

graphify wiki
# → unknown command 'wiki'

두 번 실패했다. 그리고 여기서 성급한 결론을 냈다.

"Graphify는 소스 코드 파일(.py, .js, .ts)을 스캔하는 도구다. 마크다운은 처리 대상이 아니다."

이렇게 쓰고 pip uninstall했다. 블로그 초안에도 "코드 인덱서였다"고 적었다.

그런데 이 결론은 틀렸다. graphify update가 코드 전용 서브커맨드였고, 올바른 명령을 한 번도 테스트하지 않았다.

---

한 발 물러서 문서를 다시 읽었다

이 포스트를 쓰기 전에 graphify.net 공식 문서를 다시 확인했다.

올바른 명령은 이거였다.

graphify .          # 현재 디렉토리 전체 처리
graphify ./wiki     # wiki/ 폴더만 처리

이 명령은 현재 디렉토리의 모든 마크다운 파일, 코드, 이미지를 분석하여 그래프로 변환한다. graphify update는 이미 처리된 코드 파일의 증분 갱신 전용이었다. 처음 인제스트는 graphify .이다.

Graphify의 실제 처리 방식을 정리하면 이렇다.

파일 유형	확장자	처리 방식
코드	.py .ts .js .go 등	tree-sitter AST 파싱 (LLM 없음)
문서	.md .mdx .html .txt	Claude LLM 기반 개념·관계 추출
PDF	.pdf	인용 채굴 + 개념 추출
이미지	.png .jpg .webp	Claude 비전 분석

마크다운 파일은 Claude가 직접 읽고 개념과 관계를 추출한다. 출력은 graphify-out/에 생성된다.

graphify-out/
├── graph.html        ← 인터랙티브 시각화
├── GRAPH_REPORT.md   ← 구조 리포트 (허브 노드, 커뮤니티, 고아 페이지)
├── graph.json        ← 그래프 데이터
└── obsidian/         ← Obsidian vault 내보내기

추가로 --mcp 플래그를 쓰면 MCP 서버가 뜨고, Claude Code에서 그래프 쿼리 인터페이스를 쓸 수 있다.

처음 평가에서 테스트하지 않은 것들이 많았다.

---

그러면 써야 하나? 다시 따져봤다

"Graphify가 마크다운을 처리할 수 있다"는 사실이 달라졌으니, 채택 판단을 다시 해야 한다.

이 위키의 운영 원칙에는 이런 말이 있다. "그래프 계층이 필요해지더라도 wiki/에서 파생되는 분석 레이어로 다룬다." Graphify는 그 역할을 할 수 있다. wiki/ 구조를 바꾸지 않고 graphify ./wiki를 돌리면 파생 그래프가 생성된다. 원칙과 충돌하지 않는 방식으로 쓸 수 있다.

그러면 써야 하나?

쓰면 생기는 것	쓰면 생기는 비용
GRAPH_REPORT.md로 허브 노드, 고아 페이지 가시화	Claude API 호출 비용 (LLM 기반 추출)
graph.html로 위키 연결 구조 시각적 탐색	추가 의존성과 빌드 스텝
--mcp로 Claude에 그래프 쿼리 인터페이스 추가	그래프가 또 다른 유지보수 대상
Obsidian vault 내보내기 호환

현재 위키는 84페이지다. LLM Wiki Pattern이 제시하는 50~200페이지 sweet spot 안에 있다. 이 규모에서는 wiki lint가 고아 페이지를 잡아주고, index.md가 검색 인덱스 역할을 하고, Claude가 마크다운을 직접 읽는다. 그래프 도구가 해결해줄 병목이 아직 없다.

더 솔직히 말하면, 84페이지에서 Graphify를 쓰는 비용은 "그래프가 필요해서"가 아니라 "그래프가 있으면 멋있을 것 같아서"에 가깝다. 그건 좋은 채택 이유가 아니다.

---

결론: 지금은 아니다, 나중에는 모른다

pip uninstall -y graphifyy

이번 결론도 같다. 하지만 이유가 다르다.

기존 결론: "Graphify는 마크다운을 처리하지 못한다 → 안 쓴다" 새로운 결론: "Graphify는 마크다운을 처리할 수 있다 → 그런데 지금은 필요 없다"

두 결론의 방향은 같지만, 두 번째가 훨씬 정확하다. 도구의 한계가 아니라 프로젝트의 현재 상태가 기준이다.

이 위키의 로드맵에는 이렇게 적혀 있다. "graph DB는 필요가 생긴 뒤 파생 실험으로 검토한다." 그 조건이 생길 때가 있다면:

• 위키가 200페이지를 넘어서 index.md 탐색이 느려질 때
• Claude Code에서 MCP 쿼리 인터페이스가 실질적으로 필요해질 때
• GRAPH_REPORT.md가 줄 수 없는 wiki lint의 맹점이 발견될 때

그 시점이 오면, graphify ./wiki를 돌려볼 것이다. wiki/ 구조를 바꾸지 않아도 되니까.

---

정리

Graphify를 평가하면서 두 가지 실수가 있었다.

첫 번째는 기술적 실수다. 잘못된 서브커맨드(graphify update)를 테스트해놓고, 올바른 명령(graphify .)을 한 번도 시도하지 않았다. 두 번의 실패만으로 도구의 능력을 판단했다.

두 번째는 평가 순서의 실수다. "이 도구가 무엇을 할 수 있는가"를 먼저 정확히 확인하지 않고, "이 도구가 필요한가"로 바로 넘어갔다.

도구 평가의 올바른 순서는 이렇다.

1. 도구가 실제로 무엇을 하는지 공식 문서로 확인한다
2. 올바른 명령을 찾아서 테스트한다
3. 그 위에서 "내 프로젝트에 필요한가"를 판단한다

도구가 할 수 있는 것과, 내 프로젝트가 지금 필요한 것은 다른 질문이다.

Graphify는 좋은 도구다. 이 위키에 지금 안 쓰는 건, Graphify가 못해서가 아니다. 이 위키가 아직 그 단계가 아니어서다.

---