Graphify: Biến thư mục bất kỳ thành knowledge graph

Graphify là một "skill" dành cho các AI coding assistant như Claude Code, Cursor hay Codex, biến toàn bộ mã nguồn, tài liệu, hình ảnh và video của một dự án thành đồ thị tri thức (knowledge graph). Thay vì bắt AI tìm kiếm từ khóa (grep) hay so khớp vector (RAG) một cách mù mờ, Graphify đưa cho nó một "bản đồ cấu trúc": module này gọi module kia ra sao, vì sao lại viết như vậy, và các thành phần liên kết với nhau thế nào.

Nói ngắn gọn: bạn ném cho AI một mớ hỗn độn, Graphify giúp nó hiểu hệ thống nhanh hơn, trả lời chính xác hơn, với chi phí token rẻ hơn đáng kể.

Graphify là gì?

Đừng nhầm Graphify với một vector index thông thường. Vector index chỉ giỏi tìm những đoạn văn bản "trông có vẻ giống nhau"; Graphify phân tích cấu trúc thực tế của hệ thống. Nó dùng hơn 36 bộ ngữ pháp tree-sitter để mổ xẻ logic mã nguồn, từ class, function cho đến các luồng import phức tạp — chạy local, không cần gọi LLM, nên tuyệt đối bảo mật cho code của bạn.

Khi chạy xong, Graphify nhả kết quả vào thư mục graphify-out/ gồm ba thành phần:

• graph.json: dữ liệu thô cho máy đọc và truy vấn tự động.
• GRAPH_REPORT.md: báo cáo kiến trúc cho người (và AI) đọc, liệt kê các "god node" (node quan trọng nhất) cùng những kết nối bất ngờ.
• graph.html: giao diện trực quan hóa; bạn nhấp vào từng node để xem quan hệ phụ thuộc, rất tiện khi cần nắm nhanh một codebase lạ.

Cấu trúc thay vì độ tương đồng: vấn đề Graphify giải quyết

Ai từng làm RAG truyền thống (dựa trên embedding và cosine similarity) chắc đã "đụng tường": bạn hỏi về quan hệ giữa Module A và Module B, AI trả về hai đoạn text rời rạc của từng module nhưng không giải thích được chúng liên kết ra sao. Lý do là từ vựng trong hai file có thể khác nhau hoàn toàn, khiến phép đo độ tương đồng lệch hướng. Đó không phải lỗi cách đặt prompt, mà là giới hạn của bản thân độ tương đồng.

Graphify giải quyết bằng topology (hình thái học đồ thị): nó bám theo call graph và dependency chain thực tế. Benchmark trên bộ code nanoGPT và micrograd cho thấy một truy vấn cấu trúc qua Graphify chỉ ngốn khoảng 1.700 token, trong khi bắt AI đọc mớ file thô tốn tới 123.000 token — giảm 71,5 lần. Con số đó không chỉ là tiết kiệm tiền, mà còn giúp AI khỏi "ngộp" vì tràn context window.

Cách Graphify dựng knowledge graph

Quy trình trích xuất chia làm ba giai đoạn (pass), mỗi giai đoạn một mức chi phí:

1. Pass 1 (AST Extraction): phần lõi, hoàn toàn miễn phí và chạy local. Nó dùng tree-sitter để hiểu cấu trúc code. Giai đoạn này deterministic (xác định), không dùng LLM, đảm bảo độ chính xác và bảo mật.
2. Pass 2 (Local Transcription): nếu dự án có file audio/video hoặc link YouTube, Graphify dùng faster-whisper để phiên âm ngay tại máy bạn.
3. Pass 3 (Semantic Pass): đây là lúc các LLM subagent vào cuộc để xử lý PDF, ảnh bảng trắng hay tài liệu phi cấu trúc. Đây là giai đoạn duy nhất tốn phí API, nhưng nó nối những thứ "không phải code" vào sơ đồ tổng thể.

Cuối cùng, thuật toán Leiden tự động phát hiện các "cộng đồng" (community) trong dự án. Thay vì nhìn một mớ file rời rạc, AI thấy các phân hệ logic (ví dụ cụm auth, cụm database), nhờ đó xử lý tác vụ gọn hơn hẳn. Mỗi quan hệ còn được gắn tag EXTRACTED (lấy trực tiếp từ code) hay INFERRED (suy luận, kèm điểm tin cậy), để bạn biết đâu là dữ kiện, đâu là phỏng đoán.

Cài đặt và chạy Graphify

Lưu ý tên gói trên PyPI là graphifyy (hai chữ 'y'), còn lệnh gọi vẫn là graphify. Nên dùng uv để quản lý môi trường cho sạch:

# Cài đặt bằng uv (khuyên dùng) hoặc pip
uv tool install graphifyy
 
# Cài skill cho trợ lý AI (ví dụ Claude Code)
graphify install

Muốn dùng cho nền tảng khác:

• graphify cursor install (cho Cursor)
• graphify codex install (cho Codex)

Bạn có thể tạo file .graphifyignore (cú pháp giống .gitignore) để loại trừ những gì không muốn đưa vào đồ thị; Graphify cũng tôn trọng .gitignore sẵn có. Nếu chạy trên CI hay môi trường headless, nhớ thiết lập các biến môi trường như ANTHROPIC_API_KEY hoặc OPENAI_API_KEY để Pass 3 hoạt động.

Truy vấn đồ thị và tích hợp vào coding assistant

Tính năng đáng giá nhất là PreToolUse hook. Khi tích hợp vào Claude Code, hook này "chặn" AI lại trước khi nó định chạy những lệnh grep hay glob tốn kém, buộc nó nhìn vào GRAPH_REPORT.md hoặc truy vấn đồ thị trước để có cái nhìn tổng quan rồi mới thu hẹp phạm vi tìm kiếm.

Bạn cũng có thể gõ lệnh trực tiếp để tra cứu:

graphify query "luồng xử lý auth nối với database thế nào?"
graphify path "AuthService" "PostgresAdapter"
graphify explain "ten_ham_x"

Ngoài ra, Graphify chạy được như một MCP server hoặc HTTP server dùng chung (cờ --transport http), phơi ra các công cụ như query_graph, get_neighbors và shortest_path. Cả team có thể dùng chung một graph server thay vì mỗi người tự dựng bản local — rất tiện khi làm việc nhóm.

Khi nào nên dùng Graphify (và khi nào không)

Nên dùng khi:

• Tiếp nhận một codebase khổng lồ, lạ hoắc.
• Cần tìm các phụ thuộc ẩn (hidden dependency) xuyên file và thư mục.
• Phát hiện "technical drift" — code cũ vẫn dùng pattern lỗi thời dù đã có chuẩn mới.
• Muốn tối ưu chi phí token cho AI agent.

Chưa cần đến khi:

• Dự án chỉ có vài file text đơn giản, gần như không có cấu trúc.
• Bạn chỉ cần tìm kiếm văn bản thuần túy — lúc này vector RAG vẫn có ưu thế hơn.

Lời khuyên thực tế: kết hợp cả hai. Dùng Graphify để nắm bộ khung và mối quan hệ, dùng vector search để tìm các chi tiết nhỏ trong tài liệu.

Tài liệu tham khảo

• GitHub — Graphify-Labs/graphify
• Graphify: Navigate Our Codebase by Structure, Not Similarity — Pankaj
• How to Improve AI-Assisted Coding with a Knowledge Graph — Umair Ali Khan
• Graphify + Obsidian + Claude Code = CHEAT CODE (YouTube)
• This Open Source Repo Just Solved Claude Code's #1 Problem (YouTube)