garrytan/gbrain: bộ nhớ riêng cho AI agent, có nguồn dẫn — 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 công cụ dòng lệnh (CLI) viết bằng TypeScript, giúp Claude Code, Codex và các agent khác có chung một bộ nhớ do bạn kiểm soát, lưu sự việc kèm nguồn. Bạn có thể bắt đầu không cần API key, chỉ tìm theo từ khoá. Cài bằng Bun khá gọn, nhưng nếu chưa quen terminal thì nên đọc kỹ từng bước và cẩn thận chỗ không cài qua npm.
GBrain là một bộ nhớ dùng chung cho các AI agent mà bạn đang dùng, như Claude Code hay Codex. Nó lưu các sự việc kèm nguồn, cho phép sửa hoặc rút lại thông tin sai, và để nhiều agent cùng đọc một bộ nhớ. Tác giả là Garry Tan, Chủ tịch kiêm CEO của Y Combinator. Ông viết GBrain để chạy chính các agent của mình. Repo dùng giấy phép MIT, hiện có khoảng 32.814 sao và 4.897 fork.
Vấn đề nó giải quyết rất quen: agent hôm nay giúp bạn xong việc, mai mở phiên mới là quên sạch. GBrain cho agent một chỗ để ghi và tra lại, thay vì bạn phải dán lại bối cảnh mỗi lần. Người nên dùng là ai đang làm việc hằng ngày với agent lập trình, hoặc muốn gom ghi chú Markdown thành một kho tri thức tra cứu được.
Điểm đáng giá nhất là cách trả lời. Công cụ ghi chú thông thường trả về danh sách trang để bạn tự mở đọc. GBrain có lệnh gbrain think đọc giúp bạn, viết thành câu trả lời có trích dẫn, và nói thẳng điều gì brain còn chưa biết. Bạn có thể bắt đầu ở chế độ không cần key, chỉ tìm theo từ khoá, rồi thêm các phần nâng cao sau.
garrytan/gbrain
GBrain là bộ nhớ tự quản cho AI agent: lưu sự việc kèm nguồn, tìm bằng từ khoá hoặc ngữ nghĩa, và tổng hợp câu trả lời có trích dẫn.
I.GBrain làm được gì
A.Bộ nhớ có nguồn, sửa được, dùng chung
GBrain lưu các sự việc rõ ràng kèm nguồn của chúng. Khi một thông tin sai, bạn có thể sửa hoặc rút lại. Các sở thích và sự việc lâu dài có thể chia sẻ giữa nhiều agent. Trạng thái tạm thời của tác vụ và cấu hình của từng công cụ thì ở lại trên máy bạn.
B.Hai cách hỏi: tìm thô và tổng hợp
gbrain search trả về các trang liên quan nhất, xếp hạng bằng điểm lai giữa vector và từ khoá. Dùng khi bạn muốn tài liệu thô để đọc lướt, tìm một câu trích cụ thể. Lệnh này ở chế độ từ khoá không cần API của mô hình nào.
gbrain think chạy cùng bước truy xuất rồi viết một câu trả lời tổng hợp có dẫn nguồn. README nhấn mạnh phần phân tích khoảng trống: câu trả lời cho biết khi nào một trang đã cũ, một ý chưa có nguồn, hai trang mâu thuẫn nhau, hay còn chỗ cần bổ sung. Lệnh này cần có cấu hình khả năng chat (mô hình ngôn ngữ).
C.Đồ thị tri thức có kiểu
GBrain có thể nối các trang với nhau (ví dụ người làm ở công ty nào) để bạn hỏi kiểu «ai làm ở acme-example?». Theo README, trên bộ đo BrainBench về câu hỏi quan hệ, phần truy xuất quan hệ nâng R@5 từ 0,6626 lên 0,7241. Đây là số do tác giả công bố, bạn nên xem như tham khảo.
D.Kỹ năng đi kèm tri thức
Brain cục bộ mới có sẵn các skill về bộ nhớ trong thư mục nội dung của nó. README cũng nói đến việc agent tham gia một danh mục skill được cấp quyền, và chỉ người biên tập được duyệt mới đăng được.
E.Chạy ở nhiều nơi
Bạn có thể cắm GBrain vào Claude Code, Codex qua MCP. Lệnh gbrain mcp expose đưa brain trên máy bạn ra qua mạng Tailscale riêng của bạn. Ngoài ra còn có bản host sẵn tại gbrain.io (trả phí, không bắt buộc) cho ai không muốn tự cài.
F.Chế độ chạy nền 24/7
Tác giả kể bộ não của mình có 155.795 trang, 24.589 người, 5.340 công ty và 66 tác vụ cron chạy tự động. Đó là hệ thống của ông, không phải điều bạn nhận ngay sau khi cài. Phiên bản chạy nền cần máy chủ có từ 8GB RAM trở lên cùng chi phí API riêng.
II.Cần chuẩn bị gì
- Bun từ 1.4.4 trở lên. Đây là yêu cầu chính khi tự host. README có lệnh cài Bun nếu máy chưa có.
- Một terminal. README dùng lệnh kiểu shell. Script cài bản host là shell script cho macOS và Linux. Về Windows, README đoạn mình có chưa nói rõ, nên bạn xem thêm docs/INSTALL.md trong repo trước khi cài.
- Một agent nếu muốn dùng cùng agent. Ví dụ Claude Code hoặc Codex. Nếu không có agent, bạn vẫn dùng được GBrain độc lập qua dòng lệnh.
- Không cần API key để bắt đầu. README gọi đây là chế độ keyless, tìm theo từ khoá. Tìm theo ngữ nghĩa, tổng hợp và làm giàu dữ liệu nền thì cần cấu hình nhà cung cấp mô hình riêng.
- Máy chủ 8GB+ RAM chỉ cần nếu bạn muốn bản chạy 24/7.
GBrain không có trên npm. Gói tên gbrain trên npm là của người khác và có thể che mất bản thật. Đừng chạy npm install -g gbrain hay bun add -g gbrain. Chỉ cài theo hướng dẫn bên dưới.
III.Cài đặt từng bước
- Cài BunChạy script cài Bun nếu máy chưa có bản 1.4.4 trở lên
- Cài GBrainDùng bun install -g từ GitHub, kênh stable
- Nối với agentChạy gbrain setup cho Claude Code hoặc Codex
- Hoặc dùng độc lậpKhởi tạo brain bằng gbrain init rồi import ghi chú
- Kiểm traChạy gbrain doctor xem sức khoẻ hệ thống
A.Cài Bun nếu chưa có
Mở terminal (ở bất kỳ thư mục nào) rồi chạy lệnh dưới. README ghi rõ bỏ qua nếu bạn đã có Bun 1.4.4 trở lên. Dòng export thêm Bun vào PATH để terminal nhận ra lệnh bun.
curl -fsSL https://bun.sh/install | bash # skip if Bun 1.4.4+ is installed
export PATH="$HOME/.bun/bin:$PATH"B.Cài GBrain
Đây là lệnh cài chính thức. Chú ý dấu #stable: nó chọn kênh stable, được README gọi là kênh đã được chạy thử lâu. Đừng thay bằng lệnh npm.
bun install -g github:garrytan/gbrain#stableREADME còn nêu cách thứ hai: clone nhánh stable rồi chạy bun install && bun link. Nếu chọn cách này, bạn tự cd vào thư mục vừa clone trước khi chạy hai lệnh đó.
git clone --branch stable https://github.com/garrytan/gbrain.git
cd gbrain
bun install && bun linkC.Nối GBrain với agent của bạn
Nếu bạn dùng Claude Code hoặc Codex, chạy một trong hai lệnh sau. README cho biết lệnh này sẽ hiện ra những gì nó định ghi trước khi làm. Bạn có thể thêm --dry-run để xem trước, --remove để gỡ. Nó chỉ tạo brain không cần key nếu chưa có brain, rồi nối MCP, hook và một khối hướng dẫn «ưu tiên dùng brain» trong file chỉ dẫn của agent (thêm --no-instructions nếu không muốn khối này).
gbrain setup claude-code # or: gbrain setup codexVới harness khác hoặc khi không có agent, README dùng lệnh dưới để khởi tạo brain cục bộ, không cần server hay Docker:
gbrain init --pglite --no-embedding # any other harness, or no agentNếu muốn cài plugin có sẵn skill, README ghi cho Claude Code hai lệnh sau (gõ trong Claude Code):
/plugin marketplace add garrytan/gbrain
/plugin install gbrain@gbrainD.Hoặc dùng độc lập, không cần agent
Chuỗi lệnh sau khởi tạo brain, nạp các ghi chú Markdown trong thư mục ~/notes/, tìm thử một cụm từ, rồi kiểm tra sức khoẻ. Nếu thư mục ghi chú của bạn ở chỗ khác, đổi đường dẫn tương ứng.
gbrain init --pglite --no-embedding # keyless; no server, no Docker
gbrain import ~/notes/ --no-embed # index your markdown
gbrain search "a phrase from a note" --json
gbrain doctor # verify healthChỗ người mới hay vấp: --no-embed và --no-embedding nghĩa là chưa dùng embedding, nên chưa có tìm theo ngữ nghĩa, chỉ có từ khoá. Postgres, thin client, API key và nâng cấp có trong docs/INSTALL.md của repo.
E.Cách cài dành cho agent
Với agent lập trình khác, README gợi ý dán nguyên đoạn sau để agent tự đọc hướng dẫn và làm:
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.IV.Kiểm tra đã chạy được chưa
Cách đơn giản nhất là chạy lệnh sức khoẻ:
gbrain doctorREADME dùng lệnh này để xác nhận hệ thống ổn. Nó cũng là nơi chỉ cách sửa nếu bạn lỡ cài nhầm gói npm. Với bản độc lập, bạn thử thêm gbrain search với một cụm từ có trong ghi chú đã import. Nếu ra được trang chứa cụm từ đó thì brain đã hoạt động.
Với bản nối agent, README gợi ý nhờ agent làm một vòng ghi rồi gọi lại (remember rồi recall) bằng lệnh GBrain thật. README cũng nói rõ việc khởi động lại agent và xác nhận dùng thật là hai bước tách biệt sau khi cài. Nên mở lại phiên agent mới rồi hỏi thử một thứ bạn vừa dặn nó nhớ.
Nếu schema chưa được nâng cấp, README chỉ lệnh gbrain apply-migrations --yes --no-autopilot-install. Nếu lệnh này thoát với mã 1, chạy gbrain doctor --json thay vì chạy lại --yes.
V.Dùng vào việc thật
Bên dưới là các tình huống mình dựng từ khả năng README mô tả. Tên người, công ty chỉ là ví dụ.
A.Chuẩn bị trước buổi gặp khách
Bạn làm kinh doanh, mai gặp chị Alice của một công ty khách hàng. Ghi chú các cuộc họp trước nằm trong thư mục Markdown và đã được import vào brain. Bạn chạy:
gbrain think "What do I need to know before my meeting with Alice tomorrow?"Theo ví dụ trong README, kết quả không phải danh sách trang. Bạn nhận một đoạn viết sẵn: Alice làm gì, lần cuối nói chuyện khi nào, còn những việc nào đang mở, kèm nguồn cho từng ý. Cuối đoạn có cảnh báo kiểu «brain chưa có thêm gì về Alice từ sáu tuần trước, có thể đã trao đổi qua kênh brain không thấy». Lệnh này cần đã cấu hình khả năng chat.
Tìm kiếm cho bạn trang để đọc, còn brain đọc giúp bạn rồi nói luôn chỗ nào nó chưa biết.
Ông T
B.Tra ghi chú cá nhân mà 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, không muốn đăng ký dịch vụ nào. Bạn khởi tạo ở chế độ không key, import thư mục, rồi tìm:
gbrain init --pglite --no-embedding
gbrain import ~/notes/ --no-embed
gbrain search "báo giá gói 500 người" --jsonKết quả là các trang khớp theo từ khoá, in ra dạng JSON. Chế độ này chưa hiểu nghĩa câu, nên hãy dùng đúng từ khoá có trong ghi chú.
C.Cho Claude Code nhớ giữa các phiên
Bạn là lập trình viên, mỗi lần mở Claude Code phải giải thích lại quy ước dự án. Bạn chạy gbrain setup claude-code, mở lại phiên mới rồi nói với agent những điều cần nhớ. README dặn rằng agent hiếm khi gọi một brain nếu không ai báo nó biết. Vì vậy lệnh setup mới ghi sẵn khối hướng dẫn «brain-first» vào file chỉ dẫn của agent. Phiên sau, bạn hỏi lại điều đó để xem agent có gọi được bộ nhớ không.
D.Dùng chung brain cho nhiều công cụ
Bạn muốn Claude Code, Codex và một agent khác trên điện thoại cùng đọc một bộ nhớ. README đưa ra lệnh gbrain mcp expose để đưa brain trên máy bạn ra qua Tailscale. Thêm --funnel nếu cần cho agent chạy trên đám mây. Brain nằm ở máy khác thì dùng lệnh gbrain connect với địa chỉ MCP và token. Trước khi chia sẻ với người khác, hãy đọc phần ranh giới chia sẻ trong tài liệu của repo.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh gbrain chạy ra chương trình lạ
Nguyên nhân hay gặp nhất là bạn lỡ cài gói npm trùng tên. README cảnh báo gói đó không liên quan và có thể che bản thật. Hãy chạy gbrain doctor, README nói lệnh này đưa ra cách sửa. Sau đó cài lại bằng bun install -g github:garrytan/gbrain#stable.
B.Terminal báo không tìm thấy lệnh bun hoặc gbrain
Thường do PATH chưa có thư mục của Bun. Chạy lại dòng export PATH="$HOME/.bun/bin:$PATH" hoặc mở terminal mới. Đừng đoán thêm đường dẫn khác ngoài những gì README ghi.
C.Schema chưa được nâng cấp
Chạy gbrain apply-migrations --yes --no-autopilot-install. Nếu lệnh thoát mã 1, đừng chạy lại --yes. Hãy chạy gbrain doctor --json và làm theo gợi ý sửa trong đó.
D.Tìm kiếm không ra gì dù ghi chú có thật
README nói kết quả tìm có thể chưa đầy đủ khi chỉ mục còn đang dựng lại. Đừng vội kết luận là trang không tồn tại. Hãy nhờ agent «Check whether my search index is ready» và xem phần search readiness trong tài liệu. Ngoài ra nếu bạn đang ở chế độ không embedding, hãy thử đúng từ khoá thay vì diễn đạt khác.
E.Agent không dùng brain
Do agent chưa được báo là brain tồn tại. Chạy lại gbrain setup claude-code hoặc gbrain setup codex, rồi khởi động lại agent. README nhấn mạnh khởi động lại và kiểm tra dùng thật là hai bước riêng.
VII.Có nên dùng không
Điểm mạnh. Bắt đầu được mà không cần key nào. Giấy phép MIT, tự host miễn phí. Lệnh think trả lời có nguồn và nói rõ phần còn thiếu, đây là điểm khác với công cụ ghi chú chỉ trả danh sách trang. Repo còn được cập nhật trong vài tháng gần đây và có hướng dẫn riêng cho nhiều agent.
Giới hạn cần biết. Đây là công cụ khá lớn, nhiều khái niệm (MCP, Tailscale, Postgres, cron). Người chưa từng dùng terminal sẽ thấy khó. README nói thẳng: nhà cung cấp embedding, reranking, trích xuất hay tổng hợp mà bạn cấu hình có thể nhận văn bản của bạn và tính phí. Mô hình của agent cũng thấy phần bộ nhớ được gọi ra, kể cả ở chế độ không key. Xuất Markdown không phải bản sao lưu đầy đủ của cơ sở dữ liệu. Với brain dùng chung cho công ty, README tự nêu rằng các bài kiểm tra phân quyền chỉ phủ những đường truy cập cụ thể, không phải bảo đảm tuyệt đối không rò rỉ. Nên đọc kỹ tài liệu ranh giới chia sẻ trước khi cho người khác vào.
Khi nào chọn cách khác. Nếu bạn chỉ cần vài ghi chú và agent đã có bộ nhớ tích hợp đủ dùng, chưa cần thêm GBrain. Nếu không muốn tự cài, bản host tại gbrain.io là lựa chọn của tác giả, có trả phí. Mình chưa có thông tin về giá. Nếu bạn dùng Windows, hãy đọc docs/INSTALL.md trước, vì README đoạn mình có chỉ nói rõ script cài bản host dành cho macOS và Linux.
Lời khuyên của mình: cài thử ở chế độ không key với một thư mục ghi chú nhỏ, xem search và doctor ổn rồi mới tính nối agent hay thêm key.
Câu hỏi thường gặp
GBrain có miễn phí không?
Theo README, GBrain dùng giấy phép MIT và tự host miễn phí. gbrain.io là dịch vụ host trả phí, không bắt buộc. Nếu bạn cấu hình thêm nhà cung cấp mô hình (embedding, tổng hợp…), chi phí API của họ là khoản riêng. Tư liệu chưa nêu giá cụ thể của bản host.
Cần API key mới dùng được không?
Không cần để bắt đầu. README gọi đây là chế độ keyless: bạn khởi tạo bằng gbrain init --pglite --no-embedding và tìm theo từ khoá. Tìm theo ngữ nghĩa, lệnh think (tổng hợp) và làm giàu dữ liệu nền thì cần cấu hình thêm nhà cung cấp mô hình.
Có cài bằng npm install -g gbrain được không?
Không. README cảnh báo gói gbrain trên npm không liên quan và có thể che bản thật. Hãy cài bằng bun install -g github:garrytan/gbrain#stable, hoặc clone nhánh stable rồi chạy bun install && bun link.
Cần GPU hoặc máy mạnh không?
Tư liệu không nhắc GPU cho chế độ cơ bản, vốn không cần server hay Docker. Chỉ bản chạy nền 24/7 (nhập liệu và gộp bộ nhớ ban đêm) được README khuyên dùng máy chủ từ 8GB RAM trở lên, kèm chi phí API riêng.
Chạy trên Windows được không?
Tư liệu mình có chưa nói rõ về Windows cho phần tự host. Chỉ biết script cài bản host là shell script cho macOS và Linux. Bạn 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?
Ở chế độ tự host, brain nằm trên máy và cơ sở dữ liệu của bạn. Tuy nhiên README nói rõ nhà cung cấp embedding, reranking, trích xuất hay tổng hợp mà bạn cấu hình có thể nhận văn bản, và mô hình của agent thấy phần bộ nhớ được gọi ra. Với brain dùng chung, nên đọc tài liệu ranh giới chia sẻ trước khi cấp quyền.
GBrain khác gì công cụ ghi chú thông thường?
Theo README, công cụ thông thường trả danh sách trang để bạn tự đọc. GBrain có thêm lệnh think viết câu trả lời có trích dẫn và chỉ ra khoảng trống kiến thức. Nó cũng cho nhiều agent dùng chung một bộ nhớ, có thể sửa hoặc rút lại thông tin.


