# GBrain: bộ nhớ riêng cho AI agent, có nguồn dẫn — hướng dẫn cài đặt và dùng

> GBrain là một công cụ dòng lệnh (CLI) cùng bộ kết nối MCP, giúp AI agent như Claude Code hay Codex có bộ nhớ lâu dài mà bạn kiểm soát. Nó lưu sự việc kèm nguồn, tìm kiếm trong ghi chú và có thể tổng hợp câu trả lời có trích dẫn. Cài đặt khá gọn: cần Bun 1.4.4 trở lên, chạy vài lệnh, và có thể bắt đầu không cần API key.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-05-24 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/gbrain-bo-nho-rieng-cho-ai-agent-huong-dan-cai-dat-2

GBrain là một bộ nhớ ngoài cho AI agent. Nó lưu các sự việc kèm nguồn, cho phép sửa hoặc rút lại khi sai, rồi dùng chung bộ nhớ đó cho nhiều agent bạn đang xài (Claude Code, Codex và các client MCP khác). Repo do Garry Tan, Chủ tịch kiêm CEO của Y Combinator, viết ra để chạy các agent của chính ông ấy. Hiện có khoảng 32.800 sao và khoảng 4.900 fork trên GitHub, giấy phép MIT.

Vấn đề nó giải quyết rất quen thuộc: agent của bạn mỗi phiên lại quên sạch. Bạn phải kể lại khách hàng là ai, lần trước bàn gì, việc nào còn dang dở. GBrain gom ghi chú, cuộc họp, thông tin người và công ty vào một nơi, để agent tra cứu khi cần. Ai hay dùng AI để làm việc hằng ngày, từ dev đến người làm kinh doanh biết dùng terminal cơ bản, đều có thể thử.

Điểm đáng giá nhất là bạn có thể bắt đầu rất nhẹ: chế độ không cần khoá (keyless), tìm theo từ khoá, không cần máy chủ, không cần Docker. Khi cần mới thêm tìm kiếm theo ngữ nghĩa, tổng hợp câu trả lời và các tác vụ nền. Ngoài ra, lệnh `gbrain think` không chỉ trả danh sách trang mà viết ra câu trả lời có trích dẫn, kèm ghi chú những gì bộ nhớ còn thiếu.

```repo
- repo | garrytan/gbrain
- kind | CLI
- desc | GBrain là bộ nhớ do bạn kiểm soát cho AI agent: lưu sự việc kèm nguồn, tìm kiếm, và trả lời có trích dẫn. Cài bằng Bun, bắt đầu không cần API key.
- stars | 33k
- lang | TypeScript
- license | MIT
```

## GBrain làm được gì

### Lưu sự việc kèm nguồn và cho phép sửa

Mỗi thông tin được lưu cùng nguồn của nó. Khi sai, bạn có thể sửa hoặc rút lại. Lợi ích thực tế: bạn không phải tin mù quáng vào thứ agent "nhớ", vì luôn truy ngược được nó đến từ đâu.

### Một bộ nhớ dùng chung cho nhiều agent

Sở thích và sự việc lâu dài có thể chia sẻ giữa các agent. Còn trạng thái tạm của tác vụ và cấu hình của từng harness thì giữ cục bộ. Bạn đổi từ Claude Code sang Codex vẫn không mất ngữ cảnh.

### Tìm kiếm thô: `gbrain search`

Trả về các trang liên quan nhất, xếp hạng bằng điểm lai (vector, từ khoá và một số bước xếp hạng lại). Dùng khi bạn muốn tự đọc tư liệu gốc, tìm một câu trích dẫn cụ thể hay nạp ngữ cảnh cho agent. Chế độ từ khoá không cần model API.

### Tổng hợp câu trả lời: `gbrain think`

Chạy cùng bước truy xuất, rồi viết một câu trả lời có trích dẫn đến trang nguồn. Phần hay nhất là phân tích khoảng trống: nó báo khi trang đã cũ, khi một ý không có nguồn, khi hai trang mâu thuẫn nhau. Phần này cần cấu hình một khả năng chat (model) riêng.

### Đồ thị tri thức có kiểu

GBrain có thể tự trích các liên kết (ai làm ở công ty nào…) từ trang bạn ghi, mà không cần gọi LLM khi bật tự động liên kết. Nhờ vậy bạn hỏi được kiểu "ai làm việc ở công ty X?". Tác giả công bố trên bộ đo BrainBench, truy xuất quan hệ nâng R@5 từ 0,6626 lên 0,7241.

### Kỹ năng đi kèm tri thức

Bộ nhớ mới tạo có sẵn các skill về bộ nhớ trong thư mục nội dung. Agent có thể tham gia một danh mục skill được cấp phép, và chỉ người biên tập được duyệt mới đăng được.

### Chạy nền 24/7 (tuỳ chọn)

Phiên bản của tác giả chạy hàng chục cron job: nạp cuộc họp, email, tweet, làm giàu thông tin người và công ty, sửa trích dẫn, dọn bộ nhớ ban đêm. Phần này cần máy chủ riêng và chi phí API riêng, người mới chưa cần đụng tới.

## Cần chuẩn bị gì

- **Bun 1.4.4 trở lên.** Đây là runtime bắt buộc cho cách tự host. Nếu chưa có, README cho lệnh cài Bun (có ở bước dưới).
- **Một terminal.** Hầu hết lệnh chạy ở terminal. Script cài bản hosted của gbrain.io là shell script cho macOS và Linux. README phần tôi có không nói rõ về Windows, nên nếu dùng Windows hãy xem `docs/INSTALL.md` trong repo trước khi bắt tay.
- **Một agent (tuỳ chọn).** Claude Code hoặc Codex nếu bạn muốn nối bộ nhớ vào agent. Không có agent vẫn dùng được ở chế độ CLI độc lập.
- **API key (tuỳ chọn).** Không cần để bắt đầu. Chỉ cần khi bật embedding, reranking, trích xuất hoặc tổng hợp bằng nhà cung cấp đám mây.
- **Máy chủ 8GB RAM trở lên** chỉ khi bạn muốn bản chạy nền 24/7 kèm chu trình "dream" ban đêm.

```note
Chế độ keyless không cần API, nhưng model của agent (Claude Code, Codex…) vẫn nhìn thấy nội dung bộ nhớ đượ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ủa bạn sẽ được gửi tới họ và có thể tốn phí. Đọc phần memory boundaries trong tài liệu trước khi nạp dữ liệu nhạy cảm.
```

## Cài đặt từng bước

```steps
- Cài Bun | Chạy lệnh cài Bun nếu máy chưa có phiên bản 1.4.4 trở lên
- Cài GBrain | Cài bằng bun install -g từ GitHub, kênh stable
- Nối vào agent | Chạy gbrain setup claude-code hoặc gbrain setup codex
- Tạo bộ nhớ không cần khoá | Chạy gbrain init --pglite --no-embedding nếu dùng agent khác hoặc không dùng agent
- Kiểm tra sức khoẻ | Chạy gbrain doctor
```

README còn có cách hosted tại gbrain.io (tác giả bán dịch vụ lưu trữ tuỳ chọn). Bài này đi theo cách tự host miễn phí.

### Cài Bun

Mở terminal. Nếu máy chưa có Bun 1.4.4 trở lên, chạy hai lệnh sau. Lệnh thứ hai thêm Bun vào PATH để terminal tìm thấy nó.

```bash
curl -fsSL https://bun.sh/install | bash   # skip if Bun 1.4.4+ is installed
export PATH="$HOME/.bun/bin:$PATH"
```

Chỗ người mới hay vấp: sau khi cài, nếu gõ `bun` báo không tìm thấy thì hãy đóng terminal, mở lại rồi thử tiếp.

### Cài GBrain đúng cách

Đây là chỗ phải cẩn thận nhất. Chỉ cài bằng lệnh dưới đây.

```bash
bun install -g github:garrytan/gbrain#stable
```

```note
GBrain KHÔNG phân phối qua npm. Gói npm tên gbrain là một gói khác, không liên quan, và có thể che mất bản thật. Tuyệt đối không chạy npm install -g gbrain hay bun add -g gbrain. Lỡ cài nhầm thì chạy gbrain doctor để xem cách sửa.
```

Nếu muốn cài theo cách khác, README cho phép clone nhánh `stable` rồi chạy `bun install && bun link`:

```bash
git clone --branch stable https://github.com/garrytan/gbrain.git
cd gbrain
bun install && bun link
```

### Nối GBrain vào agent của bạn

Chạy một trong hai lệnh, tuỳ agent bạn đang dùng. Lệnh sẽ hiện trước những gì nó định ghi (dùng `--dry-run` để xem trước, `--remove` để gỡ), tạo bộ nhớ không cần khoá nếu chưa có, nối MCP và hook, thêm đoạn hướng dẫn "hỏi bộ nhớ trước" vào file chỉ dẫn của agent, rồi tự kiểm tra.

```bash
gbrain setup claude-code              # or: gbrain setup codex
```

Nếu bạn không muốn nó sửa file chỉ dẫn của agent, README cho cờ `--no-instructions`.

### Hoặc dùng độc lập, không agent

Với agent khác, hoặc khi bạn chỉ muốn thử bằng dòng lệnh, tạo bộ nhớ cục bộ không cần khoá, không cần server, không cần Docker:

```bash
gbrain init --pglite --no-embedding   # keyless; no server, no Docker
```

Nếu agent của bạn là loại khác, README có sẵn một đoạn để dán cho agent, nó sẽ tự đọc hướng dẫn cài rồi làm:

```text
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.
```

Còn Postgres, thin client, API key và nâng cấp thì xem `docs/INSTALL.md` trong repo.

### Cài plugin kèm skill có sẵn (tuỳ chọn)

README ghi hai cách cho plugin:

```bash
codex plugin marketplace add garrytan/gbrain@codex-plugin
codex plugin add gbrain@gbrain
```

```text
/plugin marketplace add garrytan/gbrain
/plugin install gbrain@gbrain
```

Hai lệnh đầu dành cho Codex (chạy ở terminal). Hai dòng sau dành cho Claude Code (gõ trong khung chat của Claude Code).

## Kiểm tra đã chạy được chưa

Cách đơn giản nhất theo README là chạy lệnh kiểm tra sức khoẻ:

```bash
gbrain doctor
```

Lệnh này báo tình trạng cài đặt, và cũng là nơi chỉ cách sửa nếu bạn lỡ cài nhầm gói npm. Nếu cần kết quả dạng máy đọc, README có nhắc `gbrain doctor --json`.

Với trường hợp nối vào agent, `gbrain setup` có bước tự kiểm tra sau khi ghi cấu hình. README cũng gợi ý yêu cầu agent thử một vòng "nhớ rồi gọi lại" (remember/recall) bằng các lệnh GBrain thật. Bạn có thể nói với agent: "Hãy lưu một ghi chú thử rồi tra lại nó bằng GBrain", sau đó xem agent có gọi đúng công cụ không.

Với chế độ độc lập, thử thêm một lượt tìm kiếm nhỏ. Cần có ít nhất một ghi chú đã được nhập (xem tình huống bên dưới). Nếu `gbrain search` trả về trang chứa cụm từ bạn gõ thì mọi thứ đã hoạt động.

## Dùng vào việc thật

### Biến thư mục ghi chú thành bộ nhớ tra cứu được

**Bối cảnh:** bạn là nhân viên văn phòng hoặc chủ shop, đã có một thư mục ghi chú Markdown về khách hàng, nhà cung cấp, biên bản họp. Muốn tìm lại nhanh mà chưa cần agent hay API key.

**Cách làm:** README đưa đúng chuỗi lệnh cho trường hợp này:

```bash
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 health
```

Bạn thay `~/notes/` bằng thư mục ghi chú của mình, và thay cụm từ mẫu bằng một cụm bạn nhớ từng viết.

**Kết quả:** nhận về danh sách trang khớp, ở dạng JSON. Chưa có tổng hợp thông minh, nhưng tìm từ khoá đã nhanh hơn việc lục từng file.

### Chuẩn bị trước cuộc họp với một khách hàng

**Bối cảnh:** sáng mai bạn gặp một đối tác. Bạn muốn nhớ họ làm gì, lần trước nói chuyện gì, còn việc gì treo.

**Cách làm:** nếu bộ nhớ đã có ghi chú về đối tác đó và bạn đã cấu hình khả năng chat cho tổng hợp, hãy hỏi agent: "Tôi cần biết gì trước cuộc họp với Alice ngày mai?". Hoặc chạy trực tiếp lệnh kiểu README:

```bash
gbrain think "who's working on AI agents at portfolio companies?"
```

Với `search` bạn nhận danh sách trang tự đọc. Với `think` bạn nhận câu trả lời có trích dẫn, kèm cảnh báo kiểu "bộ nhớ chưa có gì mới về người này từ lâu, hãy hỏi trực tiếp".

> Search tìm ra các trang. Bộ nhớ đọc chúng rồi viết câu trả lời cho bạn.
>
> — Ông T

**Kết quả:** một bản chuẩn bị họp ngắn, có nguồn cho từng ý, và có danh sách chỗ còn thiếu để bạn hỏi lại đối tác.

### Cho Claude Code hoặc Codex nhớ bối cảnh dự án

**Bối cảnh:** bạn là dev, mỗi phiên mới lại phải giải thích lại quy ước và quyết định cũ cho agent.

**Cách làm:** cài GBrain, chạy `gbrain setup claude-code` (hoặc `gbrain setup codex`) như phần trên. Lệnh này thêm chỉ dẫn "tra bộ nhớ trước" để agent chủ động gọi bộ nhớ, vì theo README, agent hiếm khi gọi một công cụ mà không ai nói với nó là có.

**Kết quả:** những sự việc và sở thích lâu dài được lưu và gọi lại giữa các phiên, còn trạng thái tạm của tác vụ vẫn ở máy bạn.

### Dùng bộ nhớ từ nhiều máy hoặc nhiều ứng dụng AI

**Bối cảnh:** bạn có bộ nhớ trên máy ở nhà nhưng muốn dùng cả từ công cụ AI khác.

**Cách làm:** README nói lệnh sau đưa bộ nhớ lên mạng Tailscale của bạn dưới dạng MCP và giữ cho nó chạy:

```bash
gbrain mcp expose
```

Thêm `--funnel` nếu cần cho agent chạy trên đám mây như Grok Bot, Muse hay ChatGPT. Với bộ nhớ ở máy khác, README dùng `gbrain connect https://your-host/mcp --token gbrain_xxx --install`.

**Kết quả:** nhiều client dùng chung một bộ nhớ. Trước khi mở ra ngoài, hãy đọc phần ranh giới chia sẻ trong tài liệu, vì README nói rõ các bài kiểm thử 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ỉ.

## Lỗi hay gặp và cách xử lý

### Cài nhầm gói npm gbrain

Triệu chứng: gõ `gbrain` ra một chương trình lạ, hoặc lệnh không đúng như hướng dẫn. Nguyên nhân thường là chạy `npm install -g gbrain`. Cách xử lý theo README: chạy `gbrain doctor` để xem cách sửa, rồi cài lại bằng `bun install -g github:garrytan/gbrain#stable`.

### Không tìm thấy lệnh `bun` hoặc `gbrain`

Sau khi cài Bun, PATH có thể chưa cập nhật. Chạy lại dòng `export PATH="$HOME/.bun/bin:$PATH"` hoặc mở terminal mới. Nếu vẫn lỗi, kiểm tra Bun đã đạt 1.4.4 trở lên chưa.

### Schema chưa được nâng cấp (migrate)

README ghi lệnh này cho trường hợp schema chưa migrate:

```bash
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.

### Kết quả tìm kiếm trống hoặc thiếu

Không vội kết luận trang không tồn tại. README nói tìm kiếm có thể chưa đầy đủ khi chỉ mục còn đang dựng lại, hoặc khi vòng quét vector bị giới hạn. Hãy nói với agent: "Check whether my search index is ready", và xem hướng dẫn search readiness and recovery trong tài liệu. Nếu bạn nhập bằng `--no-embed`, chỉ tìm theo từ khoá là bình thường.

### Agent không chịu gọi bộ nhớ

Agent hiếm khi dùng công cụ mà nó không được báo. Hãy chạy lại `gbrain setup claude-code` hoặc `gbrain setup codex` (không kèm `--no-instructions`) để đoạn chỉ dẫn được ghi vào file của agent. Sau đó khởi động lại agent và thử vòng nhớ/gọi lại.

## Có nên dùng không

**Điểm mạnh.** Miễn phí, mã nguồn mở (MIT), tự host nên dữ liệu nằm ở máy bạn. Bắt đầu không cần API key, không cần Docker. Có lệnh `think` trả lời có trích dẫn và chỉ ra chỗ bộ nhớ còn thiếu, một đ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 đều trong vài tháng gần đây.

**Giới hạn.** Đây là công cụ "có chính kiến", gắn khá chặt với cách làm của tác giả và hệ sinh thái OpenClaw/Hermes. Phần tổng hợp, embedding và chạy nền cần model API và có chi phí riêng. Xuất Markdown không phải là sao lưu đầy đủ cơ sở dữ liệu. Chia sẻ bộ nhớ cho cả công ty cần đọc kỹ ranh giới tin cậy, vì file cục bộ và thông tin đăng nhập cơ sở dữ liệu dùng chung là một ranh giới khác với phân quyền của client từ xa. README phần tôi có cũng chưa nói rõ chuyện chạy trên Windows.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần một app ghi chú để tự đọc, không dùng agent AI, thì GBrain là hơi nhiều. Nếu bạn không muốn tự cài đặt và vận hành, README có cung cấp bản hosted trả phí tại gbrain.io (tuỳ chọn). Nếu ngại cài, bạn có thể dán đoạn lệnh dành cho agent ở trên và để agent làm, rồi kiểm tra kết quả bằng `gbrain doctor`.

## 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í để tự host. Tác giả có bán dịch vụ lưu trữ tại gbrain.io, nhưng đó là tuỳ chọn. Nếu bạn cấu hình model API cho embedding hay tổng hợp thì sẽ tốn phí riêng với nhà cung cấp đó.

### Cần API key mới dùng được không?

Không bắt buộc. README nói bạn có thể bắt đầu ở chế độ keyless với tìm kiếm theo từ khoá, bằng lệnh gbrain init --pglite --no-embedding. API key chỉ cần khi bạn muốn bật tìm kiếm ngữ nghĩa, tổng hợp hay làm giàu dữ liệu nền.

### Cài bằng npm được không?

Không. README cảnh báo GBrain không phân phối trên npm, gói npm tên gbrain là gói khác và có thể che mất bản thật. Hãy cài bằng bun install -g github:garrytan/gbrain#stable.

### Có cần GPU không?

Tư liệu không nói GPU là yêu cầu. Chế độ cục bộ không cần server hay Docker. Chỉ bản chạy nền 24/7 được README khuyến nghị máy chủ từ 8GB RAM trở lên, kèm chi phí API riêng.

### Chạy được trên Windows không?

README phần có trong tư liệu chưa nói rõ về Windows. Script cài bản hosted của gbrain.io là shell script cho macOS và Linux. Bạn nên xem docs/INSTALL.md trong repo để biết hướng dẫn cho hệ điều hành của mình.

### Dữ liệu của tôi có an toàn không?

Khi tự host, bộ nhớ nằm ở máy của bạn. Tuy nhiên README lưu ý model của agent vẫn nhìn thấy bộ nhớ được gọi ra, và các nhà cung cấp embedding, reranking hay tổng hợp bạn cấu hình có thể nhận văn bản. Với chia sẻ nhiều người, hãy đọc kỹ phần ranh giới chia sẻ trước khi mở truy cập.

### GBrain khác gì một công cụ tìm kiếm ghi chú thông thường?

Lệnh gbrain search trả về danh sách trang xếp hạng, giống công cụ tìm kiếm. Lệnh gbrain think thì chạy truy xuất rồi viết câu trả lời có trích dẫn nguồn và ghi chú những gì bộ nhớ còn thiếu hoặc mâu thuẫn. GBrain còn có thể dùng chung bộ nhớ cho nhiều agent.
