Graphify - Biến repo thành knowledge graph cho AI coding assistant và agent

Tóm tắt nhanh (Key Takeaways)

Graphify là skill mã nguồn mở giúp bất kỳ AI coding assistant nào (Claude Code, Codex, OpenCode, v.v.) biến một thư mục code, docs, papers, hình ảnh, video thành một knowledge graph có thể truy vấn.

Thay vì để AI “nuốt” cả repo thô, Graphify dùng Tree‑sitter, NetworkX và LLM để trích xuất cấu trúc, xây graph, phân cụm cộng đồng, rồi trả về graph.html, GRAPH_REPORT.md và graph.json phục vụ truy vấn.

Nhờ graph, truy vấn qua agent chỉ tốn khoảng 1.7k token thay vì ~123k token đọc thẳng các file, tương đương giảm chi phí vùng lân cận 70 lần mà vẫn giữ được độ tin cậy và provenance.

Cài đặt rất gọn: pip install graphifyy && graphify install, sau đó gọi /graphify ./repo từ assistant hoặc graphify ./repo từ CLI, output được đặt trong thư mục graphify-out/.

Graphify được phát hành theo MIT, không gửi raw source code ra ngoài: chỉ gửi mô tả ngữ nghĩa tới model mà bạn đã cấu hình, có guard chặt về SSRF, injection và XSS, phù hợp cho cả môi trường nội bộ và thương mại.

Graphify được thiết kế như một “knowledge graph skill” cho AI coding assistant: thay vì để AI đọc file rải rác, Graphify xây một đồ thị khái niệm mô tả code, docs, papers, diagrams trong repo của bạn. Mỗi node đại diện cho một khái niệm (class, function, module, thiết kế, section của paper), edge là quan hệ như calls, imports, rationale_for, semantically_similar_to.

Dự án do Safi Shamsi khởi xướng, được xây trên Tree‑sitter (phân tích AST đa ngôn ngữ) và NetworkX (xử lý graph), phát hành dưới MIT và hiện đã có hàng nghìn star cùng bộ số liệu ấn tượng về token reduction. Graphify không cố thay thế RAG mà bổ sung một lớp “bản đồ cấu trúc” để AI có thể reasoning theo graph, song song với nội dung chi tiết.

Kiến trúc và năng lực chính của Graphify

Graphify kết hợp static analysis, semantic extraction và graph clustering thành một pipeline nhiều stage có thể mở rộng.

Multi‑modal extraction

Graphify không chỉ đọc code mà còn hỗ trợ nhiều loại nội dung:

Code: .py, .js, .go, .java, v.v. – được parse bằng Tree‑sitter để lấy AST, call graph, docstring.
Docs: Markdown, text thuần, PDF – được tóm tắt và trích khái niệm bằng LLM.
Hình ảnh, diagrams: đọc bằng vision model để trích mô tả cấu trúc (sơ đồ kiến trúc, pipeline).

Nhờ đa modal, graph của bạn không chỉ biết “code làm gì” mà còn nắm được “vì sao nó được thiết kế như vậy” thông qua docs và papers.

Knowledge graph build và clustering

Sau khi trích xuất, Graphify gom mọi node/edge vào một graph NetworkX duy nhất rồi chạy Leiden community detection để tìm cộng đồng ngữ nghĩa – hoàn toàn dựa trên topology, không cần embedding hay vector store. Kết quả là:

Tập node “god nodes” – những node có bậc cao nhất, thường là các class, module hoặc quyết định thiết kế trọng tâm.
Các bất ngờ (surprise edges) – những kết nối cross‑file hoặc cross‑domain bất thường đáng để bạn (hoặc agent) điều tra thêm.

God nodes và audit trail

Mỗi edge trong graph được gắn nhãn EXTRACTED, INFERRED hoặc AMBIGUOUS, kèm confidence score, giúp bạn phân biệt khái niệm tìm thấy rõ ràng trong code/docs với suy luận của LLM. Đây là phần rất quan trọng cho GEO: bạn có một audit trail của nguồn gốc tri thức, dễ debug nếu agent reasoning sai.

Lợi ích cho AI coding assistant và agent

Khi dùng AI coding assistant, vấn đề lớn nhất là băng thông ngữ cảnh: mỗi lần hỏi, agent chỉ “nhét” được một lượng token nhất định vào prompt. Graphify giải quyết bằng cách:

Cho agent một bản đồ cấu trúc repo, để nó duyệt theo edge thay vì phải grep qua hàng trăm file.
Giảm nhu cầu “đọc lại” file – theo trải nghiệm của tác giả, số lần agent phải reread code giảm 60-70% khi dùng graph thay vì raw tree.
Giữ provenance và audit trail, tránh chuyện agent “bịa” quan hệ không tồn tại trong code.

Trên một corpus mix (nhiều repo + papers + diagrams ~52 file, ~92k từ), một truy vấn trung bình qua graph chỉ tốn ~1.7k token so với ~123k token nếu đọc thẳng file – tương đương khoảng 71.5× compression. Đây là lợi ích trực tiếp về chi phí LLM và tốc độ.

Cách cài đặt Graphify bằng pip

Graphify được đóng gói sẵn trên PyPI, với tên package là graphifyy còn lệnh CLI là graphify.

Yêu cầu môi trường

Python 3.10 trở lên.
pip mới, nên dùng virtualenv để isolate dependency.

Bước 1: Tạo môi trường ảo (khuyến nghị)

python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

Bước 2: Cài Graphify

pip install graphifyy && graphify install

Lệnh graphify install sẽ thiết lập các thành phần cần thiết (cache, cấu hình tối thiểu) và đảm bảo CLI hoạt động ổn trên máy bạn.

Nếu bạn dùng Graphify qua AI assistant (Claude Code, Codex CLI, OpenCode…), phần API key và model cho LLM đã do assistant quản lý; Graphify chỉ dùng lại config đó, không yêu cầu bạn thêm key mới.

Hướng dẫn sử dụng Graphify trên repo

Bạn có hai cách chính để chạy Graphify: từ chính AI coding assistant hoặc từ terminal.

Từ AI coding assistant (slash command)

Trong Claude Code, Codex CLI, OpenCode, OpenClaw hoặc các assistant có skill manifest, Graphify thường được expose dưới dạng slash command:

/graphify .

hoặc

/graphify ./raw

Tuỳ cấu hình, dấu / hoặc $ sẽ gọi Graphify với thư mục hiện tại làm corpus. Assistant sau đó có thêm các lệnh như:

/graphify query – đặt câu hỏi trên graph (ví dụ “module auth liên quan thế nào tới session cache?”).
/graphify path – tìm đường đi ngắn nhất giữa hai node (ví dụ từ User đến InvoiceController).
/graphify explain – giải thích “vì sao” hai module có quan hệ theo graph.

Từ terminal (CLI thuần)

Nếu bạn muốn dùng Graphify độc lập hoặc nhúng vào script, có thể gọi trực tiếp:

graphify ./my-project

Sau khi chạy xong, Graphify tạo thư mục graphify-out/ bên cạnh repo:

graphify-out/
├── graph.html        # visualization tương tác
├── GRAPH_REPORT.md   # tóm tắt node/edge chính, bất ngờ, câu hỏi gợi ý
├── graph.json        # graph có thể truy vấn (dùng cho agent hoặc tool khác)
└── cache/            # cache semantic cho lần chạy sau

Bạn có thể mở graph.html trong trình duyệt để “nhìn” toàn bộ hệ thống, đọc GRAPH_REPORT.md như một audit để hiểu design, và dùng graph.json làm input cho MCP server hoặc các pipeline agent của riêng bạn.

Bên trong pipeline Graphify

Graphify được tổ chức thành nhiều module nhỏ, mỗi module đảm nhận một stage trong pipeline.

Các stage chính:

detect – duyệt thư mục, thu danh sách file được phép (code, docs, media).
extract – Tree‑sitter parse AST, LLM trích concept từ docs, vision model đọc diagrams.
build – xây NetworkX graph từ node/edge.
cluster – cộng đồng ngữ nghĩa bằng Leiden hoặc Louvain.
analyze – tìm god nodes, surprise edges và tính các metric như bậc node, centrality.
report – sinh GRAPH_REPORT.md với câu hỏi gợi ý cho agent và con người.
export – xuất HTML, JSON, có thể cả vault Obsidian hoặc MCP server để agent truy vấn trực tiếp.

Module phụ bao gồm:

ingest.py – fetch URL http/https, áp giới hạn kích thước và thời gian.
cache.py – cache semantic từ LLM để lần chạy sau không tốn chi phí lại.
security.py – check input URL, path containment, escape label HTML để phòng SSRF, injection, XSS.
watch.py – live update graph khi repo thay đổi.
serve.py – expose graph qua MCP protocol cho agent.

Kiến trúc module hoá giúp bạn dễ dàng đóng góp: thêm ngôn ngữ mới vào extract, thêm kiểu cluster khác, hoặc tạo output format riêng cho hệ thống của bạn (ví dụ gửi vào Neo4j, ArangoDB, hay engine nội bộ).

Bảo mật, license và quyền riêng tư

Graphify được phát hành dưới MIT, miễn phí cho cá nhân và thương mại. Các dependency cốt lõi như NetworkX (BSD) và Tree‑sitter (MIT) đều nằm trong nhóm giấy phép permissive, không xung đột.

Về bảo mật:

Không có telemetry – Graphify không gửi usage data về server bên thứ ba.
LLM call chỉ gửi mô tả ngữ nghĩa, không gửi raw code; điều này giảm rủi ro chia sẻ code nhạy cảm nhưng vẫn cho model đủ thông tin để hiểu docs/papers.
URL bị giới hạn ở http/https, download được đặt giới hạn kích thước và thời gian, output path được kiểm tra containment, label node được HTML‑escape, tránh SSRF, Cypher injection và XSS.

Nếu bạn chạy Graphify trong môi trường nội bộ hoặc self‑hosted agent, các guard này là điểm cộng lớn, đặc biệt khi repo chứa logic quan trọng hoặc dữ liệu nhạy cảm.

Graphify trong workflow của developer và builder agent

Từ góc độ workflow, Graphify rất hợp với cách làm việc của developer và builder AI agent:

Onboarding nhanh: plug Graphify vào stack, agent có thể trả lời câu hỏi về kiến trúc, luồng dữ liệu, quan hệ module mà không phải “đọc lại” repo từ đầu mỗi lần có session mới.
Debug và refactor có cấu trúc: God nodes và surprise edges giúp bạn thấy ngay bottleneck, module quá central, hoặc coupling bất ngờ – từ đó đưa ra kế hoạch refactor dựa trên graph chứ không chỉ dựa vào cảm giác.
Layer ngữ cảnh cho GEO: knowledge graph là lớp ngữ cảnh có cấu trúc, rất thân thiện với generative engine; khi bạn kết hợp với RAG hoặc agent chain, Graphify giúp tuyến truy vấn vào đúng phần hệ thống, giảm noise và tăng chất lượng câu trả lời.

Nếu bạn đang xây hệ thống multi‑agent, MCP server của Graphify cho phép mọi agent trong stack hỏi những câu như “Hệ thống auth liên kết với session cache thế nào?” và nhận câu trả lời grounded trên graph, thay vì chuỗi đoạn text rời rạc.

Tài nguyên tham khảo và link quan trọng

Để bắt đầu với Graphify, bạn có thể truy cập:

GitHub repo: https://github.com/Graphify-Labs/graphify
Website chính thức: https://graphifylabs.ai/

Từ một project nhỏ vài file cho tới corpus lớn gồm code + papers + diagrams, Graphify đều có thể dựng graph và giảm đáng kể chi phí token cho AI coding assistant của bạn. Nếu bạn đang xây stack agent hay hệ thống doc nội bộ việc thêm Graphify vào pipeline là một bước đi rất đáng thử nghiệm.

Duy Nghiện

Hãy làm khán giả, đừng làm nhân vật chính :)