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 (viết bằng TypeScript, giấy phép MIT) giúp AI agent như Claude Code hay Codex có một bộ nhớ lâu dài do chính bạn kiểm soát. Bạn lưu ghi chú, sự kiện cùng nguồn của chúng, rồi hỏi lại để nhận câu trả lời có trích dẫn. Cài không khó nếu quen dùng terminal: có chế độ không cần API key, chỉ cần Bun 1.4.4 trở lên.
GBrain là một bộ nhớ dài hạn cho AI agent, chạy bằng lệnh gbrain trong terminal. Bạn lưu ghi chú, thông tin về người và công ty, cuộc họp… vào đó. Sau này agent (Claude Code, Codex hoặc agent khác) hỏi lại được và nhận câu trả lời kèm nguồn.
Vấn đề repo giải quyết rất quen: mỗi lần mở một cuộc trò chuyện AI mới, nó quên sạch những gì bạn đã nói. GBrain lưu các sự kiện rõ ràng cùng nguồn gốc, cho phép sửa hoặc rút lại, và dùng chung một bộ nhớ cho nhiều agent. Nó hợp với lập trình viên, người dùng AI agent hằng ngày, hoặc dân kinh doanh cần nhớ "ai là ai, đã hứa gì" qua hàng trăm cuộc trao đổi.
Điểm đáng giá nhất là bạn có thể bắt đầu rất nhẹ: không cần API key, không cần server, không cần Docker. Khi cần mạnh hơn, bạn mới bật thêm tìm kiếm theo ngữ nghĩa, tổng hợp câu trả lời hay làm giàu dữ liệu chạy nền. Repo của Garry Tan (Chủ tịch kiêm CEO của Y Combinator), hiện có khoảng 32.782 sao và 4.890 fork.
garrytan/gbrain
GBrain là bộ nhớ có nguồn dẫn cho AI agent (Claude Code, Codex…): lưu ghi chú, tìm lại, và trả lời có trích dẫn. Tự host miễn phí, giấy phép MIT.
I.GBrain làm được gì
A.Lưu và tìm lại ghi chú, có nguồn
Bạn nhập các file markdown vào, GBrain đánh chỉ mục để tìm lại. Chế độ không key dùng tìm theo từ khóa, không gọi mô hình AI nào. Lợi ích: bạn dùng thử ngay mà không tốn thêm chi phí API.
B.Trả lời tổng hợp thay vì danh sách trang
Các công cụ ghi chú thường trả về năm trang liên quan và bạn phải tự đọc. Lệnh gbrain think chạy tìm kiếm rồi viết thành một câu trả lời có trích dẫn, kèm ghi chú những gì bộ nhớ chưa biết (trang đã cũ, hai trang mâu thuẫn, chỗ còn trống). Phần "còn thiếu gì" này là điểm tác giả nhấn mạnh nhất. Lưu ý: tổng hợp cần một khả năng chat đã được cấu hình, không chạy được hoàn toàn không key.
C.Đồ thị tri thức có kiểu
GBrain có thể nối các trang với nhau (ai làm ở công ty nào, v.v.) để bạn hỏi kiểu "ai làm ở acme-example?". Theo README, trên bộ thử BrainBench về câu hỏi quan hệ, việc này đưa R@5 từ 0,6626 lên 0,7241. Đây là số do tác giả công bố.
D.Dùng chung cho nhiều agent
Sở thích và sự kiện bền vững có thể chia sẻ giữa các agent; trạng thái tạm thời của từng công cụ vẫn nằm cục bộ. Bạn có thể nối qua MCP với Claude Code, Codex, ChatGPT, Cursor, Claude Desktop và nhiều client khác.
E.Chế độ chạy nền 24/7 (tùy chọn)
Tác giả dùng GBrain làm "daemon" nhận email, cuộc họp, tweet vào, làm giàu thông tin người và công ty, rồi dọn dẹp bộ nhớ qua đêm. Bản của tác giả có 155.795 trang. Phần này cần máy chủ riêng và chi phí API riêng; bạn không cần nó để bắt đầu.
II.Cần chuẩn bị gì
- Bun 1.4.4 trở lên. Đây là điều kiện bắt buộc của bản tự host. Nếu chưa có, các bước dưới sẽ cài.
- Một terminal. Bạn gõ lệnh ở đó.
- Một agent nếu muốn nối: README có hướng dẫn cho Claude Code và Codex. Nếu không dùng agent, vẫn chạy được ở chế độ "CLI độc lập".
- Không cần API key để bắt đầu (chế độ keyless). Embedding, rerank, tổng hợp mới cần nhà cung cấp mô hình được cấu hình riêng, và có thể tốn tiền.
- Chế độ chạy 24/7: README nói cần máy chủ từ 8GB RAM trở lên và chi phí API riêng.
- Hệ điều hành: README chỉ nói rõ bộ cài của bản hosted là script shell cho macOS và Linux. Với bản tự host trên Windows, README ở phần mình có chưa nói rõ; bạn xem thêm
docs/INSTALL.mdtrong repo.
Dù ở chế độ không key, mô hình của agent bạn đang dùng vẫn nhìn thấy nội dung bộ nhớ được gọi ra. Đừng lưu mật khẩu hay thông tin nhạy cảm vào đó nếu chưa đọc phần "memory boundaries" trong tài liệu repo.
III.Cài đặt từng bước
- Cài BunChuẩn bị môi trường chạy Bun 1.4.4 trở lên
- Cài GBrainCài lệnh gbrain từ GitHub, kênh stable
- Nối với agentChạy gbrain setup cho Claude Code hoặc Codex
- Tạo brain không keygbrain init --pglite --no-embedding
- Kiểm tragbrain doctor
A.Bước 1: Cài Bun
Bỏ qua bước này nếu máy đã có Bun 1.4.4 trở lên. Lệnh dưới là của README. Dòng thứ hai thêm Bun vào PATH để terminal tìm thấy lệnh.
curl -fsSL https://bun.sh/install | bash
export PATH="$HOME/.bun/bin:$PATH"Mở terminal mới sau khi cài nếu lệnh bun vẫn chưa nhận.
B.Bước 2: Cài GBrain từ GitHub
Đây là chỗ người mới dễ vấp nhất. README cảnh báo rõ: gói tên 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 không chạy npm install -g gbrain hay bun add -g gbrain. Chỉ cài bằng lệnh này:
bun install -g github:garrytan/gbrain#stable#stable là kênh ổn định đã được thử kỹ. README cũng cho cách khác là git clone --branch stable rồi bun install && bun link. Lỡ cài nhầm thì chạy gbrain doctor, nó sẽ chỉ cách sửa.
C.Bước 3: Nối với agent của bạn
Nếu dùng Claude Code hoặc Codex, chạy một trong hai lệnh. Phần còn lại của README có thêm dòng cho agent khác ở bước 4.
gbrain setup claude-code
gbrain setup codexTheo README, lệnh này cho bạn xem trước những gì sẽ ghi (thêm --dry-run để chỉ xem, --remove để gỡ), tạo brain không key nếu chưa có, đăng ký MCP và hook, thêm một đoạn "hỏi brain trước" vào file hướng dẫn của agent (thêm --no-instructions nếu không muốn đoạn này), rồi tự kiểm tra thử.
D.Bước 4: Tạo brain không key (nếu dùng agent khác hoặc không dùng agent)
gbrain init --pglite --no-embedding--pglite nghĩa là không cần server hay Docker. --no-embedding nghĩa là không cần key để tạo vector. Nếu bạn muốn một agent khác tự làm giúp, README có sẵn câu lệnh để dán cho agent:
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.E.Bước 5: Chạy thử kiểm tra sức khỏe
gbrain doctorPostgres, thin client, API key và nâng cấp được README chuyển sang file docs/INSTALL.md trong repo; mình không chép ở đây vì cần đọc đúng bản của bạn.
IV.Kiểm tra đã chạy được chưa
Cách đơn giản nhất theo README là chạy gbrain doctor: lệnh này kiểm tra sức khỏe cài đặt. Nếu có vấn đề, nó chỉ ra cách sửa, kể cả việc cài nhầm gói npm.
Bạn cũng nên thử một vòng "nhớ rồi gọi lại". Với chế độ CLI độc lập, README đưa chuỗi lệnh sau:
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 healthThay ~/notes/ bằng thư mục chứa file markdown của bạn, và thay cụm từ trong search bằng một câu có thật trong ghi chú. Nếu kết quả trả về trang chứa câu đó là bộ nhớ đã chạy.
Với agent, README đề nghị yêu cầu agent kiểm tra thật bằng lời gọi GBrain thật. Nếu sau khi nhập mà tìm ra kết quả rỗng, hãy nhờ agent: "Check whether my search index is ready". README giải thích rằng kết quả rỗng có thể do chỉ mục đang dựng lại, chưa chắc trang bị mất.
V.Dùng vào việc thật
A.Chuẩn bị trước cuộc họp
Bạn làm kinh doanh và sắp gặp đối tác tên Alice. Sau khi đã nhập ghi chú các lần gặp, bạn nói với agent: "What do I need to know before my meeting with Alice tomorrow?" (hoặc tiếng Việt, nếu agent hiểu). Lệnh tương đương bằng tay là:
gbrain think "What do I need to know before my meeting with Alice tomorrow?"Kết quả mong đợi theo README: một đoạn tóm tắt có trích nguồn (Alice làm gì, lần gần nhất nói chuyện, việc còn dở), kèm cảnh báo chỗ bộ nhớ không biết, ví dụ "đã lâu chưa có ghi chú mới". Bạn hỏi thẳng Alice thay vì bị bất ngờ.
Tìm kiếm chỉ tìm ra trang. Bộ nhớ thật sự thì đọc giúp bạn rồi viết ra câu trả lời, và nói rõ nó chưa biết gì.
Ông T
B.Tìm lại một câu trong kho ghi chú cá nhân
Bạn là nhân viên văn phòng, có cả thư mục ghi chú họp bằng markdown. Bạn nhập vào một lần rồi tìm theo từ khóa, hoàn toàn không cần key:
gbrain import ~/notes/ --no-embed
gbrain search "báo giá gói 500 người" --jsonsearch trả về các trang xếp theo điểm, hợp cho việc tìm đúng một câu trích dẫn hoặc lấy nguyên liệu để đọc lướt. Ví dụ cụm từ ở đây chỉ là minh họa; bạn thay bằng từ bạn thật sự đã ghi.
C.Cho Claude Code nhớ giữa các phiên làm việc
Bạn là lập trình viên mới, mỗi ngày đều nhờ Claude Code giúp việc và mệt vì phải giải thích lại bối cảnh. Chạy gbrain setup claude-code. Sau đó agent được hướng dẫn hỏi brain trước, và bạn có thể bảo nó ghi nhớ một quy ước hay một quyết định. README mô tả đây là cách thêm bộ nhớ vào agent có sẵn mà không đổi danh tính hay chỉ dẫn hiện tại của agent.
D.Dùng chung một brain trên nhiều máy hoặc nhiều agent
Bạn dùng agent ở nhiều nơi và muốn cùng một bộ nhớ. README cho hai hướng: gbrain mcp expose để mở brain trên mạng Tailscale riêng của bạn (thêm --funnel cho agent chạy trên đám mây như ChatGPT), hoặc nối tới một brain đặt ở máy khác bằng lệnh gbrain connect. Với team, hãy đọc kỹ phần ranh giới chia sẻ trước khi cấp quyền cho người khác.
VI.Lỗi hay gặp và cách xử lý
A.Lệnh gbrain không chạy hoặc chạy ra chương trình lạ
Nguyên nhân hay gặp nhất là cài nhầm gói npm trùng tên. Chạy gbrain doctor để nhận hướng dẫn sửa, rồi cài lại đúng bằng bun install -g github:garrytan/gbrain#stable. Từ giờ đừng dùng npm install -g gbrain.
B.Terminal báo không tìm thấy bun
Bun đã cài nhưng PATH chưa cập nhật. Chạy dòng export PATH="$HOME/.bun/bin:$PATH" ở Bước 1, hoặc đóng và mở lại terminal.
C.Lỗi schema chưa được nâng cấp (migrate)
README ghi rằng nếu schema chưa được migrate, hãy chạy lệnh dưới. Nếu nó thoát với mã 1, chạy gbrain doctor --json và làm theo hướng dẫn thay vì chạy --yes lần nữa.
gbrain apply-migrations --yes --no-autopilot-installD.Tìm kiếm trả về rỗng dù bạn chắc đã nhập
Chỉ mục có thể đang dựng lại hoặc quét vector chưa xong. Hỏi agent "Check whether my search index is ready" trước khi kết luận trang bị mất. Xem phần search readiness trong tài liệu repo.
E.gbrain think không trả lời
Tổng hợp cần một khả năng chat đã được cấu hình, nên không chạy được ở chế độ hoàn toàn không key. Nếu chỉ cần tìm trang, dùng gbrain search. Muốn dùng think, xem docs/INSTALL.md để cấu hình nhà cung cấp mô hình.
VII.Có nên dùng không
Điểm mạnh. Miễn phí và tự host (MIT). Bắt đầu được ngay không cần key hay server. Câu trả lời có nguồn và có ghi chú "chưa biết gì", hữu ích khi bạn không muốn tin mù quáng vào AI. Một bộ nhớ dùng chung được cho nhiều agent, và repo vẫn được cập nhật trong vài tháng gần đây.
Giới hạn. Bản đầy đủ phức tạp hơn vẻ ngoài: tìm ngữ nghĩa, tổng hợp và chạy nền đều cần cấu hình và chi phí API riêng. Xuất markdown không phải bản sao lưu đầy đủ của cơ sở dữ liệu. Nếu dùng làm "bộ não công ty", README nói quyền truy cập từ xa có kiểm soát, nhưng 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 quyền chỉ phủ những đường truy cập cụ thể, không phải cam kết tuyệt đối không rò rỉ.
Khi nên chọn cách khác. Nếu bạn chỉ cần ghi chú đơn giản, một ứng dụng ghi chú bình thường là đủ. Nếu không muốn đụng tới terminal, README có nhắc dịch vụ hosted tại gbrain.io (trả phí, tùy chọn), nhưng bài này tập trung vào bản tự host. Nếu agent bạn dùng đã có bộ nhớ tích hợp đủ tốt, hãy cân nhắc xem bạn có thật sự cần thêm một lớp nữa không.
Lời khuyên của mình: cài thử chế độ không key, nhập một thư mục ghi chú nhỏ, chạy vài lần gbrain search và gbrain doctor. Nếu thấy hữu ích mới nâng lên bước tiếp theo.
Câu hỏi thường gặp
GBrain có miễn phí không?
Có. README ghi GBrain dùng giấy phép MIT và miễn phí để tự host. Dịch vụ gbrain.io là bản hosted trả phí, hoàn toàn tùy chọn. Nếu bạn cấu hình thêm nhà cung cấp mô hình bên ngoài (embedding, tổng hợp), chi phí API sẽ tính riêng.
Có cần API key hay GPU không?
Không cần key để bắt đầu: chế độ keyless dùng tìm theo từ khóa và không gọi mô hình nào. README không nhắc yêu cầu GPU. Chạy nền 24/7 cần máy chủ từ 8GB RAM trở lên và cấu hình API riêng.
Cài GBrain bằng npm được không?
Không. README cảnh báo gói npm tên gbrain là một gói khác, không liên quan, và có thể che mất lệnh thật. Hãy cài bằng lệnh `bun install -g github:garrytan/gbrain#stable`.
Chạy được trên Windows không?
Chưa có thông tin rõ ràng trong phần README mình có. README chỉ nói bộ cài hosted là script shell cho macOS và Linux. Bạn nên xem docs/INSTALL.md trong repo để biết hỗ trợ Windows cho bản tự host.
Dữ liệu của tôi có an toàn không?
Dữ liệu nằm trên máy và cơ sở dữ liệu của bạn khi tự host. Tuy vậy, nhà cung cấp embedding, rerank, 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 vẫn thấy nội dung bộ nhớ được gọi ra, kể cả ở chế độ không key. Hãy đọc phần memory boundaries trước khi lưu thông tin nhạy cảm.
GBrain khác gì một công cụ tìm kiếm ghi chú thông thường?
Tìm kiếm thông thường trả về danh sách trang. Lệnh `gbrain think` của GBrain tổng hợp thành câu trả lời có trích dẫn và nêu rõ những gì bộ nhớ chưa biết. Nó cũng có đồ thị tri thức và dùng chung được cho nhiều agent.
Dùng với Claude Code hoặc Codex như thế nào?
Chạy `gbrain setup claude-code` hoặc `gbrain setup codex`. Lệnh này đăng ký MCP, hook và thêm chỉ dẫn hỏi brain trước vào file hướng dẫn của agent. Bạn có thể dùng `--dry-run` để xem trước, `--remove` để gỡ.


