317 file ứng viên và hai kiểu "trí nhớ" cho AI: index bằng knowledge graph vs README thông thường

Trong bài lab CodeGraph tuần này, có một con số làm nhiều bạn nhắn hỏi lại: 317 file ứng viên. Đó là số file mà lệnh grep -rli "telegram" trả về trên repo 4.304 file, khi mình muốn biết một message Telegram chảy qua đâu trong hệ thống. Ba file thực sự liên quan — nhưng muốn biết là ba file nào, agent phải lục qua một đống "gần đúng" trước, và mình trả token cho từng lần thử sai đó.

Câu hỏi hay nhất mình nhận được: "sao không cho AI đọc README trước như mọi người vẫn làm? Đỡ phải cài thêm tool."

Câu hỏi rất đúng — vì đó chính là cách "index" phổ biến nhất hiện nay: viết một file README (hoặc CLAUDE.md, docs/) mô tả dự án, rồi để agent đọc nó trước khi làm việc. Bài này mình so hai cách đó với nhau, trên cùng bộ số liệu đã đo, để trả lời rõ: README là một loại index — nhưng là index cho người. Knowledge graph là index cho máy. Và hai thứ trả lời hai loại câu hỏi khác nhau.

Cách 1: "Index" bằng README — quen tay, nhưng dừng ở tầng ý định

Quy trình quen thuộc: agent mở README, biết được dự án làm gì, cấu trúc thư mục đại khái ra sao, chạy lệnh nào để build. Với câu hỏi tổng quan ("dự án này về cái gì?"), README thắng tuyệt đối — vài trăm dòng do con người chắt lọc, đọc một lần là nắm được ý định của dự án.

Nhưng thử đặt đúng câu hỏi kiến trúc của mình — "message Telegram đi qua những hàm nào trước khi agent trả lời?" — thì README bất lực, vì ba lý do nằm trong bản chất của nó:

1. README không chứa quan hệ gọi nhau. Nó nói "thư mục src/telegram/ xử lý Telegram" — và hết. Bên trong 78 file .ts của thư mục đó, hàm nào gọi hàm nào, README không biết. Agent vẫn phải quay về grep: 317 file ứng viên, đọc lần lượt, thử và sai.
2. README do người viết, và người thì quên cập nhật. Code đổi mỗi ngày; README đổi mỗi... quý. Agent tin vào một bản mô tả cũ còn tệ hơn không có gì — nó tự tin đi sai đường thay vì dò dẫm đúng đường.
3. README mô tả cái "nên là", không phải cái "đang là". Muốn biết sửa hàm reply thì vỡ chỗ nào, không README nào trả lời được — vì tác giả README cũng không biết chính xác tại thời điểm bạn hỏi.

Tóm lại: README "index" được ngữ cảnh và quy ước — thứ rất quý — nhưng không index được cấu trúc đang chạy của code.

Cách 2: Index bằng knowledge graph — máy đọc code, máy trả lời

CodeGraph làm việc ngược lại: không nhờ ai mô tả cả. Nó parse thẳng cú pháp code bằng tree-sitter, bóc ra 72.325 node và 211.390 edge — từng function, class, import và quan hệ gọi nhau — nhét vào SQLite ngay trong dự án. Trên repo 4.304 file của mình, khâu index này mất 2 phút 18 giây, chạy một lần rồi cập nhật theo code.

Cùng câu hỏi kiến trúc ở trên, một lệnh codegraph explore trả lời trong 1,97 giây: đúng 2 file trung tâm của luồng dispatch, kèm call graph, blast radius (sửa reply thì 18 chỗ ảnh hưởng) và cảnh báo symbol nào chưa có test. Không phải lục 317 file ứng viên nào cả.

Khác biệt cốt lõi không nằm ở tốc độ — nằm ở nguồn sự thật. README là lời kể của con người về code; knowledge graph là ảnh chụp X-quang của chính code, tái lập được, không phụ thuộc trí nhớ hay thiện chí cập nhật của ai.

Đặt hai "kiểu trí nhớ" cạnh nhau

	README / CLAUDE.md	Knowledge graph (CodeGraph)
Ai tạo ra	Con người viết tay	Máy parse từ AST, deterministic
Cập nhật	Khi ai đó nhớ ra	Re-index theo code
Trả lời tốt	"Dự án này là gì, quy ước nào?"	"Hàm nào gọi hàm nào, sửa đây vỡ đâu?"
Câu hỏi kiến trúc	Vẫn phải grep: 317 file ứng viên	2 file trung tâm, 1,97 giây
Chi phí cho agent	Rẻ lúc đọc, đắt lúc dò (token thử-sai)	Đắt lúc index (2'18"), rẻ mỗi lần hỏi
Điểm mù	Cấu trúc thật của code	Ý định, bối cảnh, quy ước đội nhóm

Nhìn bảng này sẽ thấy vì sao mình nói hai thứ không thay thế nhau. Trong các dự án của mình bây giờ, agent được trang bị cả hai: CLAUDE.md dạy nó quy tắc và ý định (viết giọng nào, cấm gì, quy trình ra sao), còn graph cho nó bản đồ cấu trúc để khỏi đi lạc. Thiếu cái đầu, agent làm đúng kỹ thuật nhưng sai ý mình; thiếu cái sau, nó hiểu ý mình nhưng mò mẫm đốt token.

Khi nào chỉ cần README là đủ?

Nói cho công bằng, đúng như tài liệu CodeGraph tự nhận: lợi ích tỉ lệ thuận với kích thước repo. Dự án ~150 file, cấu trúc phẳng, README tử tế — grep vốn đã rẻ, thêm knowledge graph gần như không thấy khác biệt. Ngưỡng đáng cân nhắc theo trải nghiệm của mình: khi repo vượt vài trăm file, hoặc khi bạn bắt đầu thấy agent "để em tìm đã" nhiều hơn "đây là câu trả lời".

Nguyên lý chung: đừng bắt trí nhớ làm việc của chỉ mục

Nếu bạn đọc blog này thường xuyên, chắc thấy bài học này quen quen. Nó chính là nguyên lý mình áp dụng cho "bộ não thứ 2": thông tin thô để một nơi (RAW), tri thức đã tiêu hoá có cấu trúc để một nơi (WIKI), và AI trả lời từ chỉ mục có cấu trúc thay vì lục cả kho mỗi lần được hỏi. CodeGraph làm đúng việc đó cho code; bộ não thứ 2 làm việc đó cho tri thức cá nhân. Cùng một nguyên lý: đầu tư một lần vào cấu trúc, tiết kiệm mãi mãi ở mỗi lần truy vấn.

Câu hỏi thường gặp

Có nên bỏ viết README khi đã có knowledge graph? Không. Graph không biết "vì sao đội bạn chọn kiến trúc này" hay "quy ước đặt tên là gì". README/CLAUDE.md vẫn là nơi duy nhất chứa được những thứ đó — hãy viết nó ngắn, đúng, và bớt mô tả cấu trúc (việc đó để graph lo).

Index 183 MB có đáng lo không? Trên repo 4.304 file, database chiếm 183 MB — đổi lấy việc mỗi câu hỏi kiến trúc rẻ đi hàng chục tool call. Với mình là cái giá hời, nhưng bạn nên biết trước con số này.

Người không code có rút được gì từ bài này? Có — nguyên lý "index cho người vs index cho máy" áp dụng cho mọi kho thông tin: tài liệu công ty, ghi chú cá nhân, hồ sơ khách hàng. Bản mô tả viết tay giúp người mới hiểu bối cảnh; chỉ mục có cấu trúc giúp AI trả lời chính xác. Kho nào của bạn đang chỉ có "README viết tay"?

Bước tiếp theo

Nếu repo của bạn đã vượt vài trăm file và hoá đơn coding agent bắt đầu dày lên vì "thuế khám phá" — đọc bài lab đầy đủ với screenshot từng bước rồi thử codegraph init trên một bản clone. Còn nếu thứ đang bừa bộn của bạn không phải code mà là thông tin — bắt đầu từ nguyên lý index cho chính bộ não của mình:

🎁 "Đừng Học Thuộc Nữa — Để AI Nhớ Hộ Bạn" — dựng "bộ não thứ 2" trong một buổi tối, không cần biết code. 👉 Nhận cẩm nang tại đây →

---

Về tác giả. Lưu Hải Long — kỹ sư Big Data & AI engineering. Nhiều năm xây hệ thống dữ liệu quy mô petabyte cho các sản phẩm hàng chục triệu người dùng; hiện xây các hệ thống AI tự vận hành và bộ skill claude_support. Mọi con số trong bài đo trên máy của tác giả — không phải số đi mượn.