Claude-mem: bộ nhớ xuyên phiên cho AI coding agent

Bạn đóng Claude Code cuối ngày. Sáng hôm sau mở lại, agent hỏi lại đúng những thứ hôm qua bạn đã giải thích: vì sao chọn Postgres cho service này, bug kia sửa bằng cách nào. Không phải agent kém. Phiên làm việc đã kết thúc, và ngữ cảnh đi theo nó.

Claude-mem xử lý đúng điểm gãy này: giữ lại những gì agent đã làm và đã quyết, rồi nạp lại vào phiên sau. Đây không phải công cụ nén context trong một phiên, cũng không phải workspace hay harness mới.

Vấn đề thực tế: đóng phiên là mất ngữ cảnh

Mỗi phiên Claude Code có một cửa sổ ngữ cảnh hữu hạn. Khi phiên kết thúc, những gì agent ‘học’ được, quyết định kiến trúc, nguyên nhân gốc của một bug, quy ước deploy của team, không tự trở thành kiến thức bền vững cho phiên sau, trừ khi bạn ghi lại bằng tay vào tài liệu như CLAUDE.md.

Phần lớn kiến thức dạng này nằm trong chuỗi hành động, không nằm trong tài liệu. Bạn thử cách A, thất bại vì lý do X, chuyển sang cách B và nó chạy. Tài liệu cuối cùng thường chỉ ghi ‘dùng cách B’.

Chi phí của việc này cộng dồn theo ba hướng: thời gian tóm tắt lại bối cảnh; token phải nạp lại để nhắc bối cảnh; và nguy hiểm nhất, quyết định bị đảo ngược trong im lặng khi agent không biết một hướng đi đã từng bị loại bỏ có lý do.

Để khỏi nhầm: Headroom nén log trong phiên; Cindy là workspace giữ phiên xuyên thiết bị; Graphify xây knowledge graph của codebase tĩnh. Claude-mem nằm ở tầng khác: nó nhớ diễn biến làm việc theo thời gian.

Claude-mem là gì

Claude-mem, repo thedotmack/claude-mem, giấy phép Apache-2.0, được mô tả là hệ thống nén bộ nhớ bền vững cho Claude Code: tự động ghi lại quan sát từ việc dùng tool, tạo tóm tắt ngữ nghĩa, và cung cấp lại cho phiên sau.

Tính đến ngày 31/10/2026 theo GitHub API, repo này có khoảng 107.000 stars. Phiên bản mới nhất được kiểm tra là v15.7.0, phát hành ngày 30/10/2026, ngay sau v15.6.0 ngày 29/10/2026. Nhịp release nhanh như vậy là lý do bạn nên ghim phiên bản khi dùng cho dự án chính. OctoCounts, một nguồn thứ ba, ghi nhận 1.140 stars trong ngày 31/10/2026.

Theo mô tả của repo, ngoài Claude Code, claude-mem còn hỗ trợ OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode và các agent khác. Bài này tập trung vào luồng Claude Code vì đó là luồng có hướng dẫn plugin rõ ràng nhất.

Nên cân nhắc claude-mem nếu bạn dùng Claude Code thường xuyên, làm dự án dài hơi và trong team có những quyết định lặp lại. Chưa cần vội nếu bạn chỉ dùng agent thỉnh thoảng hoặc team bạn đã có kỷ luật ghi chép chặt chẽ.

Kiến trúc: hooks, worker và hybrid search

Claude Code có các lifecycle hook và claude-mem bám vào đó: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop (Summary) và SessionEnd. Mỗi hook là lệnh claude-mem hook claude-code , trong đó PostToolUse ghi quan sát chính và SessionStart nạp lại cho phiên mới.

Hệ quả kiến trúc quan trọng nhất: toàn bộ chuỗi phụ thuộc vào việc hook được đăng ký đúng. Nếu hook không đăng ký, agent vẫn chạy bình thường, chỉ là không còn nhớ gì qua phiên sau. Đây là kiểu hỏng âm thầm.

Luồng dữ liệu chạy như sau. Hook ghi lại hoạt động dùng tool. Một worker service chạy nền, được quản lý bằng Bun dưới dạng HTTP API trên máy local, tiếp nhận các ghi nhận thô, xử lý thành tóm tắt ngữ nghĩa và ghi vào kho lưu trữ. Cổng mặc định của worker là 37700 + (uid % 100).

Kho lưu trữ gồm hai thành phần bổ sung cho nhau. SQLite với FTS5 đảm nhiệm tìm kiếm toàn văn theo từ khóa: nhanh và chính xác với tên file, tên hàm, mã lỗi. Chroma, một vector database, đảm nhiệm tìm kiếm theo ngữ nghĩa. Kết hợp hai cách này gọi là hybrid search.

Giới hạn cần nói rõ: bộ nhớ chỉ tốt bằng dữ liệu nó ghi được. Quyết định thống nhất ngoài phiên làm việc thì claude-mem không biết. Ngược lại, phiên làm việc chứa nhiều thao tác thử-sai sẽ để lại cả những hướng đi đã bị loại bỏ trong kho bộ nhớ.

Theo mình, claude-mem không chỉ đổi bài toán từ ‘mất context’ sang ‘có context’, mà đổi chế độ lỗi từ ‘quên’ sang ‘nhớ sai’. Quên thì bạn nhận ra ngay. Nhớ sai thì nguy hiểm hơn, vì agent trình bày lại một quyết định cũ đã bị đảo ngược như thể nó vẫn còn hiệu lực.

Hướng dẫn cài đặt cho Claude Code

Một lưu ý trung thực trước khi vào lệnh: bài này đối chiếu tài liệu chính thức và repo tính đến ngày 31/10/2026. Mình chưa chạy cài đặt thực tế bản v15.7.0 trên máy thật trong đợt này.

Tài liệu chính thức nêu các điều kiện tiên quyết: Node.js từ 20.0.0 trở lên; Claude Code bản mới nhất có hỗ trợ plugin; Bun từ 1.0 trở lên, tự cài nếu thiếu; uv, tự cài nếu thiếu; SQLite 3, đi kèm qua bun:sqlite.

Trong Claude Code, chạy lần lượt:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Sau đó khởi động lại Claude Code. Tài liệu cho biết ngữ cảnh từ phiên trước sẽ tự xuất hiện ở phiên mới sau khi cài đặt đúng. Cách khác là npx claude-mem install, tự cài Bun và uv nếu thiếu.

Tài liệu cảnh báo rõ một lỗi rất dễ mắc: lệnh npm install -g claude-mem chỉ cài SDK, không đăng ký plugin hooks và không thiết lập worker service. Nếu cài theo cách này, chuỗi hook-worker không tồn tại. Quy tắc rất đơn giản: nếu bạn cài bằng npm global, hãy coi như chưa cài và cài lại bằng luồng plugin.

Cũng đừng copy snippet của luồng khác: snippet Grok Bot mặc định gắn với CMEM Pro (hosted memory), dùng nhầm có thể đưa dữ liệu sang chế độ hosted khi bạn tưởng mình đang chạy local.

Sau khi khởi động lại Claude Code, hãy kiểm chứng bằng hành vi, không phải bằng việc lệnh chạy không báo lỗi. Mở một phiên trong một dự án thử, cho agent làm một việc có dấu vết rõ ràng rồi đóng phiên. Mở phiên mới và hỏi agent về việc vừa làm, xem nó có truy hồi đúng quyết định không.

Đồng thời kiểm tra worker local đang chạy và file cấu hình ~/.claude-mem/settings.json đã được tạo. Chỉ khi phiên mới truy hồi đúng, hãy dùng claude-mem cho dự án chính.

Về local và hosted, bài này chưa xác minh đầy đủ, cho đúng v15.7.0, rằng mọi lựa chọn trong trình cài đặt Claude Code đều giữ dữ liệu ở local, cũng như chi phí CMEM Pro. Vì vậy, trước khi dùng cho repo nhạy cảm, hãy đọc kỹ lựa chọn provider và xác nhận bạn đang ở chế độ local.

Đánh giá: ưu điểm, nhược điểm, bảo mật và vận hành

Ưu điểm rõ nhất là tính liên tục xuyên phiên mà không cần bạn tóm tắt tay sau mỗi lần làm việc. Ưu điểm thứ hai là truy hồi theo ngữ cảnh thay vì đọc lại toàn bộ log, nhờ hybrid search chỉ lấy vài quan sát liên quan. Ưu điểm thứ ba là mô hình chạy local theo mô tả cho luồng Claude Code.

Nhược điểm lớn nhất đã nêu: bộ nhớ cũ hoặc sai. Một quyết định kiến trúc đã bị đảo ngược, một workaround tạm thời rồi quên gỡ, đều có thể được truy hồi lại ở phiên sau với vẻ ngoài đáng tin. Cách giảm rủi ro có căn cứ là dọn dẹp bộ nhớ định kỳ.

Nhược điểm thứ hai là nhiễu: càng ghi nhiều observation, càng dễ lẫn quan sát không quan trọng. Nhược điểm thứ ba là phụ thuộc vào chuỗi hook, worker và kho dữ liệu, mắt xích nào hỏng âm thầm cũng làm mất tính năng cốt lõi mà không báo lỗi rõ ràng.

Về bảo mật, đây là phần cần đọc kỹ nhất trước khi cài. Observation được ghi từ tool usage, nghĩa là đầu vào và đầu ra của tool đều có thể đi vào kho bộ nhớ, kể cả secret hoặc token vô tình xuất hiện trong output. Một kho như vậy cần được đối xử như dữ liệu nhạy cảm.

Tài liệu chính thức cung cấp hai cơ chế kiểm soát: thẻ , loại nội dung được đánh dấu khỏi quá trình lưu trữ, và auto-redaction theo regex, thay các mẫu secret đã biết bằng marker trước khi lưu trữ.

Điểm quan trọng: theo trang cấu hình chính thức, auto-redaction là tính năng opt-in và cờ CLAUDE_MEM_REDACT_ENABLED mặc định là false. Nếu bạn cài xong và dùng ngay mà không chạm vào cấu hình, redaction tự động chưa bật. Trước khi dùng cho repo có thể chứa credential, hãy bật redaction trong ~/.claude-mem/settings.json.

Về hiệu năng, đợt này không có dữ liệu đo kiểm: không con số giảm token, không benchmark tốc độ. Bài này vì vậy không đưa ra claim hiệu năng nào; chi phí suy luận được là công ghi observation, tóm tắt, lưu trữ và truy vấn hybrid search mỗi phiên.

Về vận hành, ba việc tối thiểu là: sao lưu thư mục ~/.claude-mem trước mỗi lần nâng cấp; ghim phiên bản khi đã ổn định; và giám sát worker service.

Khi cần rollback: gỡ hoặc vô hiệu hóa plugin trong Claude Code, dừng worker service, rồi xóa kho bộ nhớ hoặc khôi phục từ bản sao lưu. Lệnh gỡ chính xác cần đối chiếu tài liệu tại thời điểm thực hiện; bài này không tự suy ra lệnh gỡ. Sau rollback, mở phiên mới và xác nhận nó không còn nạp ngữ cảnh cũ nữa.

So sánh trên tiêu chí rõ ràng

Headroom giải bài toán phiên dài, claude-mem giải bài toán phiên sau. Hai bài toán nối tiếp nhau, và theo mình, kết hợp cả hai là hợp lý nếu bạn vừa làm việc phiên dài vừa quay lại dự án nhiều lần, nhưng đây là nhận định, không phải tính năng tích hợp đã được kiểm chứng.

Use case thực tế

Với team backend, những quyết định như ‘vì sao service này không dùng cache ở tầng đó’ thường chỉ sống trong đầu một vài người. Lớp bộ nhớ xuyên phiên giúp người mới, hoặc chính bạn sau ba tháng, lần lại được lý do, không chỉ kết quả, với điều kiện team dọn dẹp bộ nhớ khi quyết định thay đổi.

Với homelab và sysadmin, agent tham gia cấu hình dịch vụ, sửa lỗi Docker hay xử lý sự cố mạng. Bộ nhớ xuyên phiên giúp agent nhớ ‘lần trước lỗi này sửa bằng cách nào’. Nhưng theo mình, nó không thay thế runbook: dùng observation để gợi nhớ, rồi viết runbook từ đó, là cách dùng có kỷ luật hơn.

Trường hợp không nên kỳ vọng là dự án đổi hướng nhanh: quyết định tuần trước có thể đã lỗi thời tuần này, và truy hồi tự động sẽ kéo bạn về hướng cũ.

Xử lý lỗi thường gặp

Cài bằng npm global rồi mà phiên mới vẫn không nhớ gì. Đây là cài sai cách như đã cảnh báo: npm install -g claude-mem chỉ cài SDK. Cài lại bằng luồng plugin, khởi động lại Claude Code, rồi kiểm chứng bằng phiên mới.

Worker không chạy hoặc kho bộ nhớ không tăng. Kiểm tra file ~/.claude-mem/settings.json đã được tạo chưa và worker local có đang chạy không. Nếu một trong hai vắng mặt, gỡ và cài lại plugin là hướng xử lý trực tiếp hơn là sửa tay cấu hình.

Agent nhắc lại quyết định cũ đã bị đảo ngược. Tạo quan sát mới ghi rõ quyết định cũ không còn hiệu lực và lý do thay đổi, đồng thời đặt lịch dọn dẹp bộ nhớ định kỳ.

Nghi ngờ secret lọt vào bộ nhớ. Bật redaction trong cấu hình, dùng thẻ cho nội dung nhạy cảm trong các phiên sau, và rà soát lại kho bộ nhớ hiện có trước khi tiếp tục dùng cho repo nhạy cảm.

Kết luận

Claude-mem phù hợp với người dùng Claude Code thường xuyên, làm dự án dài hơi, có nhiều quyết định lặp lại và sẵn sàng vận hành thêm một worker cùng một kho dữ liệu. Với nhóm này, chi phí vận hành nhỏ hơn chi phí lặp lại ngữ cảnh mỗi ngày.

Chưa phù hợp với người dùng agent thỉnh thoảng, dự án ngắn hoặc đổi hướng nhanh, và môi trường nhạy cảm với dữ liệu rời máy mà chưa xác minh được chế độ local/hosted.

Theo mình, bước tiếp theo an toàn nhất là: cài qua plugin trên một dự án thử, bật redaction trước khi làm việc với repo nhạy cảm, kiểm chứng bằng phiên mới, sao lưu thư mục ~/.claude-mem trước khi nâng cấp, rồi mới đưa vào dự án chính. Bản dịch tiếng Việt của tài liệu gốc nằm trong repo tại docs/i18n/README.vi.md.

Tham khảo

• Repo chính thức: https://github.com/thedotmack/claude-mem
• Tài liệu chính thức: https://docs.claude-mem.ai
• Trang cấu hình (redaction, file settings): https://docs.claude-mem.ai/configuration
• Releases (v15.7.0, ngày 30/10/2026): https://github.com/thedotmack/claude-mem/releases
• Bảng trending tham khảo (nguồn thứ ba): https://octocounts.com/trending