GBrain: bộ nhớ có nguồn dẫn cho AI agent bạn đang dùng — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về garrytan/gbrain — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: GBrain: bộ nhớ dài hạn cho AI agent bạn đang dùng — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
GBrain là một "bộ não" mã nguồn mở (MIT) do Garry Tan, CEO của Y Combinator, viết bằng TypeScript. Nó giúp AI agent như Claude Code hay Codex nhớ sự việc kèm nguồn, tìm lại và trả lời có trích dẫn. Cài bản không cần API key khá nhanh, nhưng cần có Bun và biết mở terminal.
GBrain là một bộ nhớ mã nguồn mở cho AI agent. Nó lưu những sự việc bạn muốn agent nhớ, kèm nguồn gốc của từng sự việc. Bạn có thể sửa hoặc rút lại thông tin, và nhiều agent khác nhau cùng dùng chung một bộ nhớ. Tác giả là Garry Tan, Chủ tịch kiêm CEO của Y Combinator. Ông viết nó để chạy các agent của chính mình.
Vấn đề repo giải quyết rất quen thuộc: bạn trò chuyện với AI hôm nay, mai nó quên sạch. Ghi chú, email, cuộc họp nằm rải rác, AI không biết đường mà đọc. GBrain gom chúng về một chỗ do bạn kiểm soát. Agent tra cứu ở đó trước khi trả lời. Ai hay dùng Claude Code, Codex hoặc Cursor và muốn chúng nhớ lâu hơn một phiên chat thì nên xem repo này. Dân kinh doanh hay phải chuẩn bị họp, nhớ khách hàng, nhớ lời hứa cũng hợp.
Điểm đáng giá nhất là bạn có thể bắt đầu mà không cần API key. Chế độ "keyless" dùng tìm kiếm theo từ khoá. Khi cần hơn thì bạn mới bật tìm kiếm theo ngữ nghĩa, tổng hợp câu trả lời và làm giàu dữ liệu nền. Repo hiện có khoảng 32.800 sao và 4.890 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây.
garrytan/gbrain
GBrain là bộ nhớ mã nguồn mở cho AI agent: lưu sự việc kèm nguồn, tìm kiếm và trả lời tổng hợp có trích dẫn, dùng chung cho Claude Code, Codex và nhiều agent khác.
I.GBrain làm được gì
A.Lưu sự việc kèm nguồn, cho phép sửa và rút lại
Mỗi thông tin trong bộ nhớ đều có nguồn. Khi sự việc thay đổi, bạn sửa được hoặc rút lại. Nhờ vậy bộ nhớ không biến thành một đống ghi chú cũ không ai dám tin.
B.Một bộ nhớ cho nhiều agent
Sở thích và sự việc lâu dài có thể dùng chung giữa các agent. Còn trạng thái tạm thời của từng tác vụ hay cấu hình của từng công cụ thì ở lại trên máy. Bạn không phải dạy lại từng agent từ đầu.
C.Tìm kiếm thô: gbrain search
Lệnh này trả về những trang liên quan nhất, xếp hạng bằng điểm kết hợp (từ khoá, vector và các yếu tố khác). Hợp khi bạn muốn tự lướt tư liệu, tìm đúng một câu trích hoặc nạp ngữ cảnh cho agent.
D.Trả lời tổng hợp: gbrain think
Đây là phần đáng giá nhất. Thay vì đưa 10 trang để bạn tự đọc, gbrain think viết một câu trả lời có trích dẫn nguồn. Nó còn nói rõ bộ nhớ chưa biết gì. Ví dụ trang nào đã cũ, ý nào chưa có nguồn, hai trang nào mâu thuẫn nhau. Phần "chỗ còn thiếu" này giúp bạn biết cần hỏi thêm ai, bổ sung gì.
E.Đồ thị tri thức có kiểu
GBrain nối các trang với nhau theo quan hệ, ví dụ ai làm ở công ty nào. Bạn hỏi "ai đang làm ở acme-example?" thì nó đi theo các liên kết. Theo tác giả, với các câu hỏi về quan hệ, truy xuất bằng đồ thị nâng chỉ số R@5 từ 0,6626 lên 0,7241 trên bộ thử BrainBench.
F.Kỹ năng đi kèm tri thức
Bộ nhớ cục bộ mới có sẵn các kỹ năng (skill) về bộ nhớ. Bạn cũng có thể kết nối với agent qua MCP, hoặc cài thành plugin cho Claude Code và Codex.
G.Dùng như bộ nhớ công ty
Người dùng từ xa bị giới hạn theo nguồn, theo thao tác và theo mức hiển thị. Tuy vậy README nhắc rõ: file cục bộ và thông tin đăng nhập cơ sở dữ liệu dùng chung là ranh giới tin cậy khác. Các bài kiểm tra phân quyền chỉ kiểm từng đường truy cập, không phải lời bảo đảm "không bao giờ lộ". Hãy đọc kỹ phần ranh giới chia sẻ trong tài liệu trước khi dùng cho cả nhóm.
II.Cần chuẩn bị gì
- Bun 1.4.4 trở lên. README ghi rõ cách tự host cần Bun phiên bản này. Chưa có Bun thì cài ở bước dưới.
- Một agent hoặc không. GBrain chạy được cùng Claude Code, Codex, hoặc chạy độc lập qua dòng lệnh, không cần agent.
- API key: không bắt buộc ở bước đầu. Chế độ keyless dùng từ khoá. Muốn tổng hợp (
gbrain think) thì cần cấu hình một mô hình chat. Muốn tìm theo ngữ nghĩa hoặc xếp hạng lại thì cần nhà cung cấp embedding hoặc reranking, và những dịch vụ này có tính phí riêng. - Hệ điều hành. README ghi rõ script cài bản hosted là shell script cho macOS và Linux. Tài liệu bạn đưa mình chưa nói rõ lệnh tự host có chạy trực tiếp trên Windows hay không. Bạn dùng Windows nên xem docs/INSTALL.md trong repo trước khi cài.
- Máy chạy 24/7 (tuỳ chọn). Bản chạy nền liên tục, tự thu thập và "dream cycle" qua đêm, theo README cần máy chủ 8GB RAM trở lên và có chi phí API riêng.
Không cần key không có nghĩa là dữ liệu không rời máy. Ngay cả ở chế độ keyless, mô hình của agent vẫn đọc được phần ký ức được gọi ra. Nếu bạn cấu hình nhà cung cấp embedding, reranking hay tổng hợp trên đám mây, văn bản có thể được gửi đến họ. Đừng nhập dữ liệu nhạy cảm cho tới khi bạn đã đọc phần "memory boundaries" trong tài liệu.
III.Cài đặt từng bước
- Cài BunCài môi trường chạy Bun 1.4.4 trở lên
- Cài GBrainCài lệnh gbrain từ GitHub, nhánh stable
- Nối với agentChạy gbrain setup cho Claude Code hoặc Codex
- Tạo bộ nhớ keylessKhởi tạo bộ nhớ cục bộ không cần key
- Kiểm tra sức khoẻChạy gbrain doctor
A.Cài Bun
GBrain chạy trên Bun. Nếu máy đã có Bun 1.4.4 trở lên thì bỏ qua bước này. Mở terminal rồi chạy:
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"Dòng đầu tải và cài Bun. Dòng thứ hai thêm Bun vào PATH để terminal tìm thấy lệnh bun. Mở terminal mới sau khi cài cũng là cách khác để PATH được nạp lại.
B.Cài GBrain
Đây là chỗ người mới hay vấp nhất. README cảnh báo rõ: GBrain không phân phối trên npm. Gói gbrain trên npm là một gói khác, không liên quan, và có thể che mất lệnh thật. Vì vậy tuyệt đối đừng chạy npm install -g gbrain hay bun add -g gbrain. Cách đúng là:
bun install -g github:garrytan/gbrain#stablePhần #stable là kênh ổn định đã được chạy thử lâu hơn. README cũng cho cách khác: git clone --branch stable rồi bun install && bun link. Lỡ cài nhầm gói npm thì chạy gbrain doctor, nó sẽ chỉ cách sửa.
C.Nối GBrain với agent
Nếu bạn dùng Claude Code hoặc Codex, chạy một trong hai lệnh:
gbrain setup claude-code # or: gbrain setup codexLệnh này cho bạn xem trước những gì nó sẽ ghi (thêm --dry-run để chỉ xem, --remove để gỡ). Nó chỉ tạo bộ nhớ keyless khi chưa có bộ nhớ nào. Sau đó nó đăng ký MCP, hook, và thêm một đoạn hướng dẫn "hỏi bộ nhớ trước" vào file chỉ dẫn của agent (thêm --no-instructions nếu không muốn đoạn này). Cuối cùng nó tự chạy thử. Đoạn hướng dẫn rất quan trọng, vì agent hiếm khi tự gọi một bộ nhớ mà không ai báo cho nó biết.
D.Tạo bộ nhớ keyless (nếu dùng agent khác hoặc không dùng agent)
gbrain init --pglite --no-embedding # any other harness, or no agentLệnh này tạo bộ nhớ cục bộ bằng PGLite, không cần server, không cần Docker, không cần key. Có thể bạn muốn nạp ghi chú ngay:
gbrain import ~/notes/ --no-embed # index your markdownThay ~/notes/ bằng thư mục chứa file markdown của bạn. Cờ --no-embed nghĩa là chưa tạo embedding, nên không tốn tiền API.
E.Với agent khác
Nếu dùng một agent lập trình khác, README có sẵn một câu lệnh để dán vào agent. Agent sẽ tự đọc hướng dẫn cài và làm giúp bạn:
Add GBrain memory to this existing agent. Read and follow:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
Keep my current identity and instructions, start keyless, and show me the
search-mode choice. Verify a remember/recall round trip with real GBrain calls.Postgres, thin client, API key và nâng cấp thì xem docs/INSTALL.md trong repo.
F.Cài như plugin (tuỳ chọn)
README còn có hai đường cài plugin kèm skill chọn lọc:
codex plugin marketplace add garrytan/gbrain@codex-plugin
codex plugin add gbrain@gbrain/plugin marketplace add garrytan/gbrain
/plugin install gbrain@gbrainHai lệnh đầu dành cho Codex, hai lệnh sau gõ trong Claude Code.
IV.Kiểm tra đã chạy được chưa
Cách đơn giản nhất là dùng lệnh kiểm tra sức khoẻ có sẵn:
gbrain doctorNếu có vấn đề, nó báo và gợi ý cách sửa. Bạn có thể thêm --json để lấy kết quả dạng máy đọc được. README ghi rằng nếu cần sửa lược đồ dữ liệu thì chạy gbrain doctor --json rồi làm theo hướng dẫn nó đưa ra, thay vì chạy lại lệnh --yes.
Tiếp theo thử một vòng "nhớ rồi gọi lại". Nếu bạn đã nạp ghi chú, tìm một cụm từ có trong ghi chú:
gbrain search "a phrase from a note" --jsonThấy trang chứa cụm từ đó trả về là bộ nhớ đã hoạt động. Nếu dùng agent, hãy yêu cầu nó nhớ một sự việc, mở phiên mới rồi hỏi lại. Agent phải gọi GBrain thật để trả lời. Trước khi dùng thật, hãy khởi động lại agent. README nhấn mạnh việc khởi động lại và kiểm chứng bằng dùng thật là hai bước riêng.
Nếu kết quả tìm kiếm trống, đừng vội kết luận trang không tồn tại. README nói chỉ mục có thể đang dựng lại. Hãy hỏi agent: "Check whether my search index is ready".
V.Dùng vào việc thật
A.Chuẩn bị cuộc họp với khách hàng
Bạn là người làm kinh doanh, mai gặp chị Alice bên công ty đối tác. Ghi chú các lần gặp, email và trao đổi trước đó đã nằm trong bộ nhớ. Bạn nói với agent: "What do I need to know before my meeting with Alice tomorrow?", hoặc chạy trực tiếp lệnh gbrain think với câu hỏi tương tự.
Kết quả không phải danh sách trang. Đó là một đoạn viết sẵn: Alice làm gì, lần cuối nói chuyện về điều gì, còn những việc nào treo. Mỗi ý đều có nguồn. Cuối cùng là một lời nhắc, kiểu "bộ nhớ chưa có thông tin gì mới về Alice từ lâu, có thể cô ấy đã trả lời qua kênh bộ nhớ không nhìn thấy". Bạn biết ngay nên hỏi lại gì.
Tìm kiếm cho bạn các trang. Bộ nhớ đọc chúng thay bạn rồi viết câu trả lời.
Ông T
B.Tìm lại ghi chú cá nhân, không cần key
Bạn là nhân viên văn phòng, có một thư mục ghi chú markdown cho họp hành và dự án. Bạn muốn tìm lại một câu chốt ở đâu đó trong đống ghi chú. Chạy lần lượt:
gbrain init --pglite --no-embedding
gbrain import ~/notes/ --no-embed
gbrain search "a phrase from a note" --jsonKết quả là các trang khớp với cụm từ, bằng tìm kiếm từ khoá, không tốn đồng API nào. Cách này hợp để thử xem GBrain có đáng dùng hay không trước khi đầu tư thêm.
C.Cho Claude Code nhớ dự án giữa các phiên
Bạn là lập trình viên mới, mỗi lần mở Claude Code lại phải giải thích lại quy ước của dự án. Chạy gbrain setup claude-code, khởi động lại Claude Code, rồi bảo nó ghi nhớ các quy ước. Phiên sau bạn hỏi lại. Nhờ đoạn "hỏi bộ nhớ trước" đã được thêm vào file chỉ dẫn, agent sẽ gọi bộ nhớ trước khi trả lời. Kết quả là bạn ít phải lặp lại những điều đã nói.
D.Dùng chung một bộ nhớ trên nhiều thiết bị
Bạn có một bộ nhớ trên máy tính ở nhà và muốn agent trên đám mây cũng truy cập được. README có lệnh gbrain mcp expose, đưa bộ nhớ lên mạng Tailscale riêng của bạn và giữ nó chạy. Thêm --funnel nếu agent ở trên đám mây như ChatGPT. Muốn nối vào một bộ nhớ đã có sẵn ở máy khác, dùng gbrain connect https://your-host/mcp --token gbrain_xxx --install (thêm --agent codex cho Codex). Phần này cần Tailscale và thêm bước cấu hình, nên người mới hãy đọc hướng dẫn "use your brain from anywhere over MCP" trong tài liệu trước.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh gbrain gọi ra một chương trình lạ
Nguyên nhân hay gặp là bạn đã cài gói npm cùng tên. Gói đó không phải của tác giả này. Chạy gbrain doctor để nó chỉ cách sửa, rồi cài lại bằng bun install -g github:garrytan/gbrain#stable.
B.Không tìm thấy lệnh bun hoặc gbrain
Sau khi cài Bun, terminal cũ chưa nạp PATH. Chạy lại export PATH="$HOME/.bun/bin:$PATH" hoặc mở một terminal mới. Nếu bạn dùng Windows và lệnh cài của Bun không chạy được, hãy xem docs/INSTALL.md vì tư liệu mình có chưa nói rõ.
C.Lược đồ dữ liệu chưa được nâng cấp
README nhắc đến trường hợp này. Chạy gbrain apply-migrations --yes --no-autopilot-install. Nếu lệnh thoát với mã 1, đừng chạy lại --yes. Hãy chạy gbrain doctor --json và làm theo cách sửa nó đưa ra.
D.Agent không dùng bộ nhớ
Agent hiếm khi tự gọi một bộ nhớ nếu không được báo. Hãy chắc là bạn đã chạy gbrain setup <harness> mà không thêm --no-instructions, và đã khởi động lại agent sau khi cài. Cách thử nhanh nhất là nhờ agent ghi nhớ một sự việc rồi hỏi lại trong phiên mới.
E.Tìm kiếm trả về rỗng
Chưa chắc trang không tồn tại. Chỉ mục có thể đang dựng lại, hoặc một lần quét vector bị giới hạn. Hãy hỏi agent kiểm tra xem chỉ mục đã sẵn sàng chưa, và xem tài liệu "search readiness and recovery".
VII.Có nên dùng không
Điểm mạnh. Bạn bắt đầu được mà không cần key. Mã nguồn mở, giấy phép MIT, tự host miễn phí. Mỗi thông tin có nguồn, sửa và rút lại được. Một bộ nhớ dùng chung cho nhiều agent. Phần tổng hợp có "chỗ còn thiếu" giúp bạn biết bộ nhớ không biết gì, nên bớt bị ảo tưởng là AI đã nắm hết.
Giới hạn. Repo khá lớn và có nhiều chế độ, nên người mới dễ choáng. Chế độ tổng hợp, tìm theo ngữ nghĩa và chạy nền 24/7 cần thêm API và máy mạnh hơn, kèm chi phí riêng. Xuất ra markdown không phải bản sao lưu đầy đủ của cơ sở dữ liệu. Các con số ấn tượng như 155.795 trang là bộ nhớ riêng của tác giả sau thời gian dài, không phải thứ bạn có ngay ngày đầu. Với việc dùng chung cho cả công ty, phân quyền có ranh giới riêng và bạn phải đọc kỹ trước khi mở cho người khác.
Khi nào chọn cách khác. Nếu bạn chỉ cần ghi chú đơn giản cho một agent duy nhất và agent đó đã có bộ nhớ tích hợp đủ dùng, có lẽ bạn chưa cần thêm một lớp nữa. Nếu bạn không muốn tự cài đặt, README có nhắc một dịch vụ hosted tuỳ chọn có tính phí. Chi tiết gói và giá mình chưa có thông tin trong tư liệu. Còn nếu bạn muốn một bộ nhớ do mình kiểm soát, cắm vào nhiều agent, thì GBrain đáng thử, bắt đầu từ chế độ keyless.
Câu hỏi thường gặp
GBrain có miễn phí không?
Có. GBrain dùng giấy phép MIT và miễn phí khi tự host. README cũng nhắc đến dịch vụ hosted tuỳ chọn có tính phí. Nếu bạn bật tìm theo ngữ nghĩa, tổng hợp hay chạy nền, chi phí API của nhà cung cấp mô hình sẽ tính riêng.
Dùng GBrain có cần API key không?
Không bắt buộc để bắt đầu. Chế độ keyless dùng tìm kiếm theo từ khoá và không cần model API. Muốn dùng gbrain think để tổng hợp câu trả lời thì cần cấu hình một khả năng chat.
Có cần GPU không?
Tư liệu không nói cần GPU. Bản chạy 24/7 theo README cần máy chủ có 8GB RAM trở lên và API riêng. Cấu hình tối thiểu cho chế độ keyless thì chưa có thông tin cụ thể.
GBrain chạy được trên Windows không?
Tư liệu chưa nói rõ. README chỉ ghi script cài bản hosted là shell script cho macOS và Linux. Cách tự host dùng Bun 1.4.4 trở lên. Bạn dùng Windows nên xem docs/INSTALL.md trong repo trước khi cài.
Dữ liệu của tôi có an toàn không?
Bộ nhớ cục bộ chạy trên máy bạn. Tuy vậy README nhắc rằng nhà cung cấp embedding, reranking, trích xuất hay tổng hợp trên đám mây có thể nhận văn bản, và mô hình của agent vẫn thấy ký ức được gọi ra ngay cả ở chế độ keyless. Phân quyền chia sẻ cũng có ranh giới riêng, nên đọc phần boundaries trước khi dùng cho nhiều người.
Tôi có cài bằng npm install -g gbrain được không?
Không. README cảnh báo gói npm tên gbrain không liên quan và có thể che lệnh thật. Hãy cài bằng bun install -g github:garrytan/gbrain#stable, hoặc git clone --branch stable rồi bun install && bun link.
gbrain search khác gbrain think thế nào?
gbrain search trả về các trang liên quan nhất để bạn tự đọc. gbrain think chạy cùng bước truy xuất rồi viết câu trả lời tổng hợp có trích dẫn nguồn và ghi chú những gì bộ nhớ chưa biết. Muốn dùng think cần cấu hình khả năng chat.


