TL;DR

Khi làm việc với dự án có hàng trăm file, AI agent thường bị lạc - đọc file này không biết liên quan file kia. graphify giải quyết bằng cách biến toàn bộ codebase thành knowledge graph có thể query. 53.3k GitHub stars, giảm 71.5 lần token so với đọc thô. Cài một lệnh, chạy /graphify . là xong.

Khi Agent Bị Lạc Trong Dự Án Của Bạn

Bạn có một dự án lớn: vài trăm file .py, .ts, một đống SQL schema, docs PDF, config YAML. Bạn nhờ Hermes - hay Claude Code, Cursor, bất kỳ AI agent nào - giúp phân tích.

Agent rất cố gắng. Đọc vài file, search keyword, chạy vài lệnh. Nhưng vấn đề lộ ra:

  • Nó thấy file X tồn tại nhưng không biết X liên quan module Y như thế nào
  • Nó hiểu logic một function nhưng không nối được function đó với database, config, và API interface
  • Nó đọc README nhưng bỏ qua kiến trúc chi tiết trong docs/

Đây không phải lỗi của riêng Hermes. Tất cả agent tool, nếu không được cung cấp "bản đồ dự án" từ trước, đều rơi vào trạng thái tìm kiếm mù - vừa đọc vừa đoán, tốn token, hay nhầm.

graphify: Vẽ Bản Đồ Trước Khi Agent Bước Vào

graphify (53.3k GitHub stars, MIT license) là một AI coding assistant skill. Bạn cài một lần, dùng trong mọi agent tool hỗ trợ skill. Khi chạy lệnh /graphify ., nó quét toàn bộ folder và xây dựng knowledge graph có thể query.

Output gồm 3 file:

  • graphify-out/graph.html - Biểu đồ tương tác, mở trong trình duyệt, click và tìm kiếm được
  • graphify-out/GRAPH_REPORT.md - Báo cáo text: node trung tâm, kết nối bất ngờ, câu hỏi gợi ý
  • graphify-out/graph.json - Dữ liệu đầy đủ để query nhiều lần sau
Workflow của graphify: từ codebase tới 3 output files
graphify quét codebase và tạo ra 3 output - graph.html, GRAPH_REPORT.md, và graph.json

Cách graphify Xây Knowledge Graph

graphify kết hợp 2 phương pháp:

  • Code: Tree-sitter phân tích AST và call graph cục bộ, không gửi source code ra ngoài. Hỗ trợ 31 ngôn ngữ lập trình.
  • Docs, PDF, ảnh: Gửi qua LLM và vision model để trích xuất semantic concept.

Sau đó dùng thuật toán Leiden (không cần vector embedding) để phân cụm graph topology và tìm ra "god nodes" - những concept kết nối nhiều nhất trong dự án, và các kết nối bất ngờ xuyên module.

Hiệu quả đo được: trên corpus ~92k words (52 files), graphify tạo 285 nodes, 340 edges, 53 communities - mỗi query tốn ~1,700 tokens thay vì ~123,000 tokens nếu đọc thô. Tương đương 71.5 lần tiết kiệm token. Trên codebase ~500k words, con số này vẫn giữ được: ~2,000 tokens/query vs ~670,000 naive.

Dùng graphify Với Hermes và Các Agent Khác

Sau khi cài và chạy /graphify ., quy trình tối ưu là:

  1. Để graphify tạo xong GRAPH_REPORT.md
  2. Mở session với Hermes, bắt đầu bằng: "Hãy đọc graphify-out/GRAPH_REPORT.md trước. Không sửa file nào. Cho tôi biết 5 module quan trọng nhất và 5 câu hỏi bạn gợi ý nên tìm hiểu."
  3. Sau đó mới hỏi cụ thể: "Luồng đăng nhập liên quan những file nào?", "Sửa logic phân quyền sẽ ảnh hưởng module nào?"

graphify hoạt động trên Claude Code, Codex, OpenCode, Cursor, Gemini CLI, Hermes, Kimi Code, GitHub Copilot CLI và 10+ tool khác.

Những Cạm Bẫy Cần Tránh

  • Tên package PyPI là graphifyy (2 chữ y), nhưng lệnh CLI vẫn là graphify (1 chữ y). Cài nhầm package là không chạy được.
  • Đừng scan toàn bộ workdir lần đầu. Dự án lớn tạo graph khổng lồ, load chậm, agent đọc mất thời gian dài. Chạy từng project folder, đúng scope cần dùng.
  • Tạo .graphifyignore trước, loại trừ node_modules/, dist/, build/, .env. Vừa tiết kiệm thời gian vừa bảo vệ dữ liệu nhạy cảm.
  • Docs, PDF, ảnh được gửi lên LLM API để trích xuất semantic - khác với code được xử lý local bằng Tree-sitter. Cần đánh giá privacy với tài liệu nội bộ.

Cài Đặt Nhanh

# Cài graphify (package PyPI: graphifyy, CLI: graphify)
uv tool install graphifyy && graphify install

# Cài cho Hermes
graphify install --platform hermes

# Chạy trong dự án
cd your-project
/graphify .

Cần Python 3.10+. uv là cách cài ít lỗi nhất, nhưng pipx hoặc pip cũng được.

Kết

graphify giải quyết vấn đề cơ bản nhất khi dùng AI agent với codebase lớn: agent cần hiểu cấu trúc tổng thể trước khi làm việc cụ thể. Thay vì để agent mò mẫm từng file, bạn cho nó một bản đồ từ đầu - tiết kiệm token, tránh nhầm module, làm việc nhanh hơn.

Nhưng ngay cả khi agent đã có bản đồ, vẫn còn vấn đề khác: mỗi session mới là trang giấy trắng. Mọi quyết định, mọi bug đã fix, mọi convention bạn thống nhất hôm qua - đều biến mất. Phần 2 giải quyết đúng vấn đề này với agentmemory và graphiti.

via GitHub safishamsi/graphify