# garrytan/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) 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.

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

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.

```repo
- repo | garrytan/gbrain
- kind | CLI
- desc | 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.
- stars | 33k
- lang | TypeScript
- license | MIT
```

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

### 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.

### 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ữ).

### Đồ 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.

### 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.

### 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.

### 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.

## 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.

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

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

```steps
- Cài Bun | Chạy script cài Bun nếu máy chưa có bản 1.4.4 trở lên
- Cài GBrain | Dùng bun install -g từ GitHub, kênh stable
- Nối với agent | Chạy gbrain setup cho Claude Code hoặc Codex
- Hoặc dùng độc lập | Khởi tạo brain bằng gbrain init rồi import ghi chú
- Kiểm tra | Chạy gbrain doctor xem sức khoẻ hệ thống
```

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

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

### 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.

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

README 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 đó.

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

### 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).

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

Vớ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:

```bash
gbrain init --pglite --no-embedding   # any other harness, or no agent
```

Nếu muốn cài plugin có sẵn skill, README ghi cho Claude Code hai lệnh sau (gõ trong Claude Code):

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

### 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.

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

Chỗ 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.

### 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:

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

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

Cách đơn giản nhất là chạy lệnh sức khoẻ:

```bash
gbrain doctor
```

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

## 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ụ.

### 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:

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

### 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:

```bash
gbrain init --pglite --no-embedding
gbrain import ~/notes/ --no-embed
gbrain search "báo giá gói 500 người" --json
```

Kế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ú.

### 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ù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.

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

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

### 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.

### 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 đó.

### 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.

### 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.

## 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.
