# claude-mem: trí nhớ bền vững cho AI viết code qua nhiều phiên — hướng dẫn cài đặt và dùng

> claude-mem là plugin và công cụ dòng lệnh giúp AI viết code (Claude Code, Codex, Cursor, OpenCode và nhiều agent khác) nhớ được những gì đã làm ở các phiên trước. Nó chạy một agent phụ để ghi chú, lưu trên máy bạn, rồi nạp bản tóm tắt vào phiên mới. Cài chỉ một lệnh npx, cần Node 20.19 trở lên.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-27 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/claude-mem-tri-nho-ben-vung-cho-claude-code-va-ai-agent

claude-mem là một plugin giúp AI viết code nhớ được công việc giữa các phiên làm việc. Bình thường, mỗi lần mở phiên mới, agent như Claude Code lại bắt đầu từ con số không: đọc lại cùng những file, hỏi lại cùng câu hỏi, và đôi khi lặp lại đúng lỗi bạn đã sửa hôm trước. claude-mem chạy thêm một agent thứ hai bên cạnh để ghi chú, rồi đưa ghi chú đó vào phiên sau.

Repo này hợp với lập trình viên, và cả người mới đang dùng AI để làm sản phẩm hằng ngày (chủ shop tự dựng web bán hàng, nhân viên văn phòng viết script tự động). Nếu bạn hay phải nhắc lại AI rằng dự án này dùng thư viện nào, đã quyết định gì, thì đây là thứ đáng thử.

Điểm đáng giá nhất: nó chạy tự động sau khi cài, dữ liệu nằm trên máy bạn, và chỉ nạp phần mục lục gọn vào phiên mới, chi tiết chỉ được mở khi cần. Hiện repo có khoảng 116.559 sao và 10.110 fork, giấy phép Apache-2.0, viết chủ yếu bằng TypeScript.

```repo
- repo | thedotmack/claude-mem
- kind | Plugin
- desc | claude-mem tự ghi chú những gì AI viết code đã làm và nạp lại vào các phiên sau, để Claude Code, Codex, Cursor… không quên việc cũ.
- stars | 117k
- lang | TypeScript
- license | Apache-2.0
```

## claude-mem làm được gì

Dưới đây là các tính năng chính, theo hướng bạn sẽ thấy lợi ích gì khi dùng.

### Phiên sau bắt đầu từ chỗ phiên trước dừng lại

Mỗi phiên mới mở ra với một mục lục gọn của các ghi chú (gọi là observation) trong quá khứ. Agent chỉ mở chi tiết khi cần, nên đỡ tốn token. Bạn đỡ phải giải thích lại bối cảnh dự án mỗi sáng.

### Tìm lại việc đã làm

Kỹ năng mem-search tìm trong lịch sử dự án theo ba bước: lấy mục lục, xem dòng thời gian quanh kết quả, rồi mới lấy chi tiết. Ví dụ bạn hỏi agent về một lỗi đăng nhập từng sửa, nó tìm lại đúng ghi chú thay vì đọc lại cả dự án.

### Giao diện xem trực tiếp (My Work và viewer)

Khi worker khởi động, nó in ra một địa chỉ để bạn xem tiến độ, yêu cầu đang chạy và hàng đợi cần duyệt (My Work). Phần xem bộ nhớ, các phiên và cài đặt nằm ở đường dẫn /viewer.

### Chia sẻ với nhóm (tuỳ chọn)

TeamBrain là không gian chung cho nhóm, tuỳ chọn. Mỗi người tự chọn chia sẻ gì; yêu cầu và ghi chú cá nhân vẫn tách riêng.

### Giữ bí mật ra ngoài bộ nhớ

README nói bạn có thể bọc nội dung nhạy cảm trong một thẻ đặc biệt để nó không bao giờ được lưu. Cú pháp chính xác của thẻ không còn trong đoạn README mình có, nên bạn xem trong tài liệu chính thức của dự án.

### Ảnh chụp màn hình

Mặc định, bản sao ảnh chụp màn hình từ công cụ được giữ trong thư mục media-v1 của ~/.claude-mem và hiện trong My Work. Ảnh chỉ được tải lên cmem.ai khi bạn bật Cloud Sync, và chỉ gửi cho mô hình quan sát khi bạn bật riêng tính năng suy luận ảnh. Có công tắc Keep images trong Settings để tắt.

### Tuỳ chỉnh thứ được nạp vào

Có các cài đặt chi tiết để chọn phiên mới bắt đầu với loại ngữ cảnh nào. Mỗi ghi chú đều có ID, bạn trích dẫn được qua API của worker hoặc mở trong trình xem web.

### Hỗ trợ nhiều agent

README nói claude-mem chạy với Claude Code, Codex, Cursor, OpenCode và 11 agent khác. Riêng Copilot CLI, Goose, Roo Code và Warp chỉ tìm kiếm được bộ nhớ, còn phiên của chúng không được ghi lại.

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

- Node.js: bản 20.19 trở lên trong nhánh 20.x, hoặc 22.12 trở lên (theo package.json: ^20.19.0 || >=22.12.0).
- Một agent được hỗ trợ: Claude Code (bản mới nhất, có hỗ trợ plugin) hoặc agent khác trong danh sách Other agents của README.
- Bun (runtime và trình quản lý tiến trình): tự cài nếu máy chưa có.
- uv (trình quản lý gói Python, dùng cho tìm kiếm vector): tự cài nếu thiếu.
- SQLite 3: đã đi kèm sẵn.
- Tài khoản: bước cài đặt có đăng nhập claude-mem bằng email (magic link, không cần thẻ để đăng nhập). Bạn có thể bỏ qua, xem phần cài đặt bên dưới.
- Windows: README có ghi chú riêng cho Windows và nói hook của Claude Code không cần Git Bash.

README không nêu yêu cầu về GPU hay dung lượng ổ đĩa.

```note
Nếu bạn chọn observer của claude-mem, README nói gói này bắt đầu bằng 30 ngày dùng thử và trang thanh toán sẽ yêu cầu phương thức thanh toán. Bạn có thể chọn cách khác: khoá OpenRouter hoặc Gemini của riêng bạn, hoặc gói Anthropic. Đọc kỹ từng màn hình trước khi bấm.
```

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

```steps
- Kiểm tra Node | Chắc chắn máy có Node 20.19+ hoặc 22.12+
- Chạy trình cài | Gõ npx claude-mem install trong terminal
- Chọn agent và nhà cung cấp | Chọn agent muốn gắn bộ nhớ, đăng nhập hoặc bỏ qua
- Khởi động lại agent | Mở lại Claude Code hoặc agent bạn chọn
- Làm việc như bình thường | Bộ nhớ tự ghi từ prompt đầu tiên
```

### Kiểm tra Node đã có chưa

Mở terminal (PowerShell trên Windows, Terminal trên macOS) và xem phiên bản. Lệnh dưới là lệnh phổ thông, không nằm trong README.

```bash
node --version
```

Nếu máy báo không nhận ra lệnh npm hay node (README có nhắc lỗi này trên Windows), cài Node.js từ trang nodejs.org rồi đóng và mở lại terminal.

### Chạy trình cài đặt

Đây là cách README khuyên dùng. Lệnh tìm các agent có trên máy và hỏi bạn muốn cài cho cái nào.

```bash
npx claude-mem install
```

Sau khi cài, bạn cứ làm việc. README nói ghi chú bắt đầu xuất hiện từ prompt đầu tiên, và phiên thứ hai trong cùng một dự án sẽ mở đầu với ký ức của phiên thứ nhất.

Trình cài cũng hỏi đăng nhập claude-mem trên trình duyệt, rồi bạn chọn nhà cung cấp bộ nhớ: observer của claude-mem, khoá OpenRouter hoặc Gemini của bạn, hoặc gói Anthropic. Muốn bỏ qua đăng nhập, README nêu ba cách: truyền cờ --provider cụ thể, đặt CLAUDE_MEM_ONLINE_OPTIN=false, hoặc chạy trong CI/shell không tương tác. Tên các giá trị cờ --provider không có trong đoạn README mình có, nên xem npx claude-mem --help.

### Hoặc cài từ chợ plugin của Claude Code

Nếu bạn chỉ dùng Claude Code, gõ hai lệnh sau ngay trong Claude Code:

```bash
/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem
```

Sau đó khởi động lại Claude Code. Ngữ cảnh từ các phiên cũ sẽ tự hiện ở phiên mới.

```note
Đừng chạy npm install -g claude-mem để cài. README cảnh báo lệnh đó chỉ cài phần SDK/thư viện, không đăng ký hook của plugin và không dựng worker. Luôn dùng npx claude-mem install hoặc các lệnh /plugin ở trên.
```

### Cài cho agent khác

Để cài trực tiếp cho một agent, thêm cờ --ide. Ví dụ OpenCode (bản 1.3.4 trở lên), nhớ khởi động lại OpenCode sau khi cài:

```bash
npx claude-mem install --ide opencode
```

README còn có các giá trị t3code, antigravity, omp, pi, grok-bot, và dsh (kèm --dsh-profile tui):

```bash
npx claude-mem install --ide t3code
npx claude-mem install --ide antigravity
npx claude-mem install --ide omp
npx claude-mem install --ide pi
npx claude-mem install --ide dsh --dsh-profile tui
npx claude-mem install --ide grok-bot
```

Danh sách đầy đủ giá trị --ide xem bằng:

```bash
npx claude-mem --help
```

Với OpenClaw Gateway, README có lệnh một dòng riêng:

```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```

Lệnh này tải một script về chạy thẳng. Nếu bạn không quen, hãy đọc hướng dẫn tích hợp OpenClaw trên trang tài liệu trước khi chạy.

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

Cách đơn giản nhất theo README: làm việc với agent ở một dự án, kết thúc phiên, rồi mở phiên mới ở cùng dự án. Bộ nhớ chỉ được nạp từ phiên thứ hai, nên phiên đầu tiên chưa thấy gì là bình thường.

Bạn cũng có thể:

- Mở địa chỉ worker được in ra khi khởi động để xem My Work, hoặc thêm /viewer để xem bộ nhớ và các phiên đã ghi.
- Chạy lệnh chẩn đoán của README:

```bash
npx claude-mem doctor
```

Nếu muốn nạp sẵn cả một repo ngay từ đầu, trong agent gõ lệnh sau. README nói mất khoảng 5 phút với repo cỡ vừa và là tuỳ chọn:

```bash
/learn-codebase
```

Trên Windows, README nói trình cài đặt đặt launcher tại %LOCALAPPDATA%\claude-mem\bin\claude-mem.exe và thêm thư mục đó vào Path của bạn. Hãy khởi động lại terminal hoặc IDE sau khi cài.

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

Các tình huống dưới đây bám theo khả năng README mô tả: ghi chú tự động, nạp mục lục vào phiên mới, và tìm lại bằng ba công cụ search, timeline, get_observations.

### Dev làm tiếp dự án sau cuối tuần

Bạn làm một ứng dụng đặt lịch cho tiệm spa, chiều thứ Sáu dừng giữa chừng. Thứ Hai mở Claude Code ở cùng thư mục. Thay vì giải thích lại, agent đã có mục lục các việc phiên trước: file nào đã sửa, quyết định nào đã chốt. Bạn chỉ cần nhắn:

```text
Tiếp tục phần nhắc lịch hẹn từ phiên trước.
```

Kết quả: agent bám đúng mạch cũ và chỉ mở chi tiết ghi chú khi cần.

### Nhân viên văn phòng viết script báo cáo, tìm lại lỗi đã sửa

Bạn nhờ AI viết script gộp file Excel hằng tuần. Một tháng sau, script lại báo lỗi giống cũ. Bạn hỏi agent xem trước đây lỗi này sửa thế nào, và agent dùng mem-search. Theo README, nó đi qua ba công cụ. Ví dụ truy vấn ở bước một:

```typescript
// Step 1: Search for index
search(query="authentication bug", type="bugfix", limit=10)

// Step 2: Review index, identify relevant IDs (e.g., #123, #456)

// Step 3: Fetch full details
get_observations(ids=[123, 456])
```

Bạn không cần tự gõ các lệnh này. Agent tự gọi, bạn chỉ cần hỏi bằng lời thường. Kết quả: có lại cách sửa cũ mà không phải đọc lại toàn bộ lịch sử.

> Agent của bạn không dở. Nó chỉ quên. Cho nó một cuốn sổ, nó làm việc khác hẳn.
>
> — Ông T

### Chủ shop có dự án chứa khoá bí mật

Bạn tự dựng trang đặt hàng và trong code có khoá API thanh toán. Trước khi làm việc với agent, bạn tìm trong tài liệu cách bọc thông tin nhạy cảm bằng thẻ mà README nhắc để nó không bị lưu. Với ảnh chụp màn hình có thông tin khách, bạn vào Settings tắt công tắc Keep images. Kết quả: bộ nhớ vẫn hoạt động nhưng những thứ bạn đánh dấu không đi vào kho ghi chú.

### Nhóm nhỏ cùng làm một dự án

Ba người cùng làm một công cụ nội bộ. Mỗi người dùng agent riêng và mỗi người tự chọn chia sẻ gì qua TeamBrain, nên ghi chú cá nhân không lẫn với việc chung. Phần này tuỳ chọn; hướng dẫn thiết lập nằm ở tài liệu của dự án. Kết quả: người vào sau thấy được các phát hiện đã liên kết thay vì phải hỏi lại từng người.

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

### Lệnh npm hoặc npx không được nhận ra

Đây là lỗi README nhắc đích danh trên Windows. Cài Node.js từ trang chủ, bảo đảm nó nằm trong PATH, rồi đóng mở lại terminal.

### Hook báo không tìm thấy lệnh claude-mem

Thông báo dạng Executable not found in $PATH: "claude-mem". Khởi động lại terminal hoặc IDE để nhận Path mới, rồi chạy:

```bash
npx claude-mem doctor
```

README trỏ tới mục Troubleshooting trong tài liệu cho trường hợp này.

### Cài xong mà không thấy bộ nhớ nào

Nguyên nhân hay gặp: bạn mới ở phiên đầu. README nói ký ức chỉ được nạp từ phiên thứ hai trong cùng dự án. Ngoài ra kiểm tra bạn đã khởi động lại agent sau khi cài và agent đó không thuộc nhóm chỉ tìm kiếm (Copilot CLI, Goose, Roo Code, Warp).

### Cài bằng npm install -g rồi không thấy tác dụng

Đúng như cảnh báo: lệnh đó chỉ cài SDK/thư viện. Hãy cài lại bằng npx claude-mem install hoặc các lệnh /plugin.

### Không muốn gửi số liệu sử dụng

README nói thống kê ẩn danh bật mặc định. Tắt bằng:

```bash
npx claude-mem telemetry disable
```

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

Điểm mạnh: cài một lệnh, chạy tự động, bộ nhớ lưu trên máy (thư mục ~/.claude-mem, cơ sở dữ liệu SQLite), đồng bộ đám mây là tuỳ chọn. Hỗ trợ nhiều agent, có giao diện xem và có cách giữ bí mật ra khỏi bộ nhớ.

Giới hạn bạn nên biết:

- Cần một agent "quan sát" để viết ghi chú. Nghĩa là có chi phí token hoặc gói dùng thử ở phía nhà cung cấp bạn chọn.
- Hiệu quả tiết kiệm token chưa được đo đầy đủ: chính README thừa nhận tỷ lệ chỉ mục nhỏ hơn bản đầy đủ khoảng một phần mười, nhưng đó không phải số đo về độ nhớ hay tiết kiệm đầu cuối.
- Có thống kê ẩn danh mặc định, phải tự tắt nếu không muốn.
- Một số agent chỉ tìm kiếm chứ không ghi lại phiên.
- Phần cấu hình chi tiết nằm ở tài liệu chính thức; bài này chưa đi sâu vào đó.

Nếu bạn chỉ dùng AI thỉnh thoảng cho vài việc lẻ, không giữ dự án dài hơi, bạn chưa cần nó. Nếu dự án chạy nhiều tuần và bạn mệt vì giải thích lại từ đầu, hãy thử trên một dự án nhỏ trước, rồi hãy bật cho các dự án quan trọng.

## Câu hỏi thường gặp

### claude-mem có miễn phí không?

Mã nguồn dùng giấy phép Apache-2.0. Về chi phí, README nói observer của claude-mem có 30 ngày dùng thử và trang thanh toán yêu cầu phương thức thanh toán. Bạn có thể chọn khoá OpenRouter hoặc Gemini của riêng bạn, hoặc gói Anthropic. Mức phí cụ thể sau dùng thử thì tư liệu này chưa nêu.

### claude-mem có cần GPU không?

README không nêu yêu cầu GPU. Yêu cầu được nêu gồm Node.js 20.19 trở lên (hoặc 22.12 trở lên), một agent được hỗ trợ, cùng Bun và uv sẽ tự cài nếu thiếu. SQLite đã đi kèm sẵn.

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

Có. README có mục ghi chú riêng cho Windows. Hook của Claude Code không cần Git Bash, trình cài đặt đặt launcher vào thư mục %LOCALAPPDATA%\claude-mem\bin và thêm vào Path của bạn. Sau khi cài, hãy khởi động lại terminal hoặc IDE.

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

README nói bộ nhớ nằm trong ~/.claude-mem trên máy bạn và đồng bộ đám mây là tuỳ chọn. Bạn có thể bọc nội dung nhạy cảm trong thẻ riêng để không bị lưu, và tắt việc giữ ảnh chụp màn hình. Thống kê ẩn danh bật mặc định, tắt bằng npx claude-mem telemetry disable. Tư liệu này không đánh giá bảo mật sâu hơn thế.

### Cài bằng npm install -g claude-mem được không?

Không nên. README nói lệnh đó chỉ cài SDK/thư viện, không đăng ký hook của plugin và không thiết lập worker. Hãy dùng npx claude-mem install, hoặc trong Claude Code dùng /plugin marketplace add thedotmack/claude-mem rồi /plugin install claude-mem.

### claude-mem hỗ trợ những agent nào?

Claude Code, Codex, Cursor, OpenCode và nhiều agent khác, ví dụ T3 Code, Antigravity CLI, OMP, Pi, DeepSeek Harness, Grok Bot, OpenClaw. Copilot CLI, Goose, Roo Code và Warp chỉ tìm kiếm được bộ nhớ chứ không ghi lại phiên. Danh sách đầy đủ xem bằng npx claude-mem --help.

### Khi nào bộ nhớ bắt đầu có tác dụng?

Ghi chú được tạo ngay từ prompt đầu tiên, nhưng README nói việc nạp bộ nhớ chỉ bắt đầu từ phiên thứ hai trong cùng một dự án. Nếu muốn nạp sẵn cả repo, có thể chạy lệnh /learn-codebase, mất khoảng 5 phút với repo cỡ vừa.
