- claude-mem là plugin 72.4K stars giải quyết vấn đề Claude Code không có trí nhớ xuyên session.
- Plugin dùng 5 lifecycle hooks để ghi lại mọi hành động của AI, nén bằng AI, lưu vào SQLite + Chroma vector DB.
- Pattern thiết kế "fast hook + slow worker" giúp hook chỉ mất vài ms trong khi worker xử lý bất đồng bộ.
TL;DR
claude-mem (72.4K stars, 259 releases tính đến tháng 5/2026) là plugin cho Claude Code giải quyết vấn đề: AI không nhớ gì khi bạn đóng session. Plugin cài 5 lifecycle hooks để tự động ghi lại mọi hành động, nén thành semantic summaries, và inject context vào session mới. Pattern thiết kế cốt lõi - hook nhẹ + background worker nặng - là bài học áp dụng được cho bất kỳ hook phức tạp nào.
Vấn đề: AI không có trí nhớ xuyên session
Ai đã dùng Claude Code lâu đều biết cảm giác này: bạn mất cả buổi sáng giải thích cho Claude hiểu kiến trúc của dự án, những quyết định đã được đưa ra, những pitfalls cần tránh. Đóng terminal. Hôm sau mở lại - Claude là một tờ giấy trắng, không biết gì về những gì hôm qua đã làm.
Tác giả bài viết gốc (一个 iOS engineer) kể: liên tục 3 ngày phải giải thích lại background dự án cho mỗi session mới. Đến ngày thứ ba thì thực sự bực - và đó là lúc đặt câu hỏi: cái này không thể tự động hóa được sao?
claude-mem ra đời để trả lời câu hỏi đó.
claude-mem hoạt động như thế nào
Plugin cài đặt bằng một lệnh duy nhất: npx claude-mem install. Sau đó nó nhúng 5 lifecycle hooks vào Claude Code config và khởi động một background worker service.
Toàn bộ vòng đời của một session được "neo" bằng hooks:
SessionStart - khi session mở: query database lấy memory liên quan đến project hiện tại, nén thành index, inject âm thầm vào context của Claude. Đây là khoảnh khắc Claude "nhớ lại" những gì đã làm trước đây.
UserPromptSubmit - khi bạn gõ prompt: ghi lại intent của bạn trong lần này.
PostToolUse - sau mỗi tool call: đây là engine quan sát chính. Mỗi lần Claude đọc file, chạy lệnh, sửa code - đều được ghi thành một observation. Hàng trăm observations có thể được tạo ra trong một session dài.
Stop - khi Claude kết thúc turn: trigger tạo summary cho session vừa rồi.
SessionEnd - khi đóng session: cleanup và archive cuối cùng.
Ví dụ thực tế từ tài liệu: một team TypeScript đang migrate Next.js từ Pages Router sang App Router. Qua 3 ngày làm việc, claude-mem ghi lại mọi file đã được convert, patterns đã áp dụng, bugs đã sửa. Sáng thứ tư mở session mới, Claude đã biết: migration đang ở 60%, file nào đã xong, pattern nào đang dùng - không cần giải thích lại.
Lớp lưu trữ: SQLite + Chroma vector DB
Dữ liệu được lưu hoàn toàn local tại ~/.claude-mem/. Kiến trúc storage gồm hai lớp:
SQLite với FTS5: lưu raw sessions, observations, summaries. Full-text search cho keyword matching.
Chroma vector database: xử lý semantic search - tìm memory theo nghĩa, không chỉ theo từ khóa.
Khi Claude cần retrieve memory, plugin dùng 3-layer MCP tool workflow: search (lấy compact index ~50-100 tokens/result) → timeline (xem chronological context) → get_observations (fetch full details cho kết quả cần). Pattern này tiết kiệm ~10x tokens so với fetch toàn bộ chi tiết ngay từ đầu.
Ngoài ra có web UI local tại http://localhost:37777 để xem live observation stream, filter theo project, và search qua memory.
Pattern quan trọng nhất: Fast Hook + Slow Worker
Đây là bài học kỹ thuật có giá trị nhất trong toàn bộ kiến trúc claude-mem, và nó áp dụng được cho bất kỳ hook nào phức tạp.
Mâu thuẫn cốt lõi: Hook chạy trong luồng của Claude - AI phải đợi hook xong mới tiếp tục. Vì vậy hook phải trả về nhanh (khuyến nghị <1 giây). Nhưng "memory compression" - quá trình AI phân tích hàng trăm raw observations, đánh giá mức độ liên quan, nén thành semantic summaries - mất 5-30 giây.
Một bên yêu cầu "xong trong 1 giây", một bên "cần nửa phút". Làm sao giải quyết?
Giải pháp của claude-mem: Hook script chỉ làm một việc cực nhanh - đẩy event vào queue (vài millisecond) rồi ngay lập tức trả về exit 0. Claude tiếp tục làm việc không bị gián đoạn. Phần compression nặng được giao cho background worker service chạy nền - worker lấy items từ queue, xử lý bất đồng bộ theo thời gian của nó.
Hai bên hoàn toàn decoupled: hook nhẹ chỉ "bắt sự kiện và chuyển tiếp", worker nặng "xử lý chậm rãi phía sau".
Tác giả bài viết gốc chỉ ra một điều thú vị: CodeIsland - dự án pixel animation trên notch MacBook - có kiến trúc giống y chang. Hook trigger → gửi message qua socket (vài ms) → trả về ngay. App CodeIsland chạy nền nhận message → render animation. Hai ứng dụng hoàn toàn khác nhau về mục đích, nhưng đến cùng một kiến trúc - vì cùng bị ép bởi ràng buộc "hook phải nhanh".
Nếu bạn định viết hook phức tạp: đừng làm việc nặng trong hook. Hook chỉ bắt sự kiện và chuyển tiếp - phần còn lại giao cho background service.
Một chi tiết kỹ thuật đáng chú ý
Tác giả bài gốc đề cập một "gotcha" thú vị trong thiết kế claude-mem: bạn có thể nghĩ memory compression nên xảy ra vào lúc context window sắp đầy - khi có nhiều thứ nhất cần nén. Nhưng cách đó không hoạt động.
Lý do: tại thời điểm "context sắp đầy", bản thân summary chưa được tạo ra - hook không có gì để nhìn vào. Vì vậy claude-mem phải đi đường vòng: đợi đến session tiếp theo, khi summary của session cũ đã nằm trong database rồi, mới pull lên và xử lý.
Đây là ví dụ điển hình của khoảng cách giữa "thời điểm lý tưởng về mặt lý thuyết" và "thời điểm thực sự có thể can thiệp" trong engineering. Hooks giỏi phải được thiết kế quanh thời điểm thực tế, không phải thời điểm lý tưởng.
Con số thực tế
72.4K GitHub stars, 6.2K forks
259 releases trong khoảng 7 tháng - tốc độ phát triển cực nhanh
109 contributors
Hỗ trợ: Claude Code, Cursor, Gemini CLI, OpenCode, Windsurf, Codex CLI
Cài đặt:
npx claude-mem install(1 lệnh)Storage: hoàn toàn local, không upload lên cloud
Kết - Ba điều mang về từ cả series
Qua 3 bài, ta đã đi từ khái niệm cơ bản đến kiến trúc phức tạp. Ba điều đáng nhớ nhất:
Hook là ràng buộc cứng, không phải ràng buộc mềm. Dùng khi bạn cần một hành động chắc chắn xảy ra, không phải hy vọng AI nhớ làm.
PreToolUse để chặn, PostToolUse để quan sát. Một cái kiểm soát trước khi tool chạy, một cái ghi lại sau khi tool đã chạy.
Hook phức tạp = fast hook + slow worker. Hook chỉ bắt sự kiện và enqueue. Phần nặng giao background service. claude-mem và CodeIsland đều áp dụng pattern này - không phải ngẫu nhiên.
Và một triết lý tổng quát hơn: trật tự đúng là - làm AI có thể quan sát được trước, rồi mới kiểm soát, cuối cùng mới tự động hóa. Bỏ qua bước đầu sẽ xây được ảo giác an toàn thay vì an toàn thực sự.