Claude-Mem: Khi AI Agent Có Thể Nhớ Mọi Thứ Bạn Đã Làm

2026-06-15 2334 words 11 minutes

Contents

Claude-Mem: Khi AI Agent Có Thể Nhớ Mọi Thứ Bạn Đã Làm

Hồi tuần trước, mình mở Claude Code lên để tiếp tục feature đang dở — và nhận ra mình phải giải thích lại toàn bộ project context từ đầu.

Tại sao lần trước mình chọn pattern này? File nào đã sửa? Bug gì đã fix? Tất cả biến mất theo session cũ. Claude Code mỗi session là một tờ giấy trắng. Cay vcl.

Nếu bạn từng trải nghiệm cảm giác này, Claude-Mem chính là thứ bạn cần.

Nó Là Gì?

Claude-Mem (GitHub: thedotmack/claude-mem) là một plugin mã nguồn mở — hiện đã có hơn 46,000 stars trên GitHub. Một con số điên đối với một plugin. Lý do đơn giản: nó giải quyết đúng cái đau nhất khi làm việc với AI agent.

Cách nó hoạt động cũng đơn giản đến bất ngờ:

Quan sát mọi tool call trong session (Read, Write, Edit, Bash…)
Nén thông tin bằng AI thành structured observations
Lưu vào SQLite + vector database
Tiêm context liên quan vào session tiếp theo

Một AI giúp AI khác ghi chép. Elegant.

Và quan trọng — nó không chỉ cho Claude Code. Claude-Mem hỗ trợ Claude Code, OpenClaw, Codex, Gemini CLI, Copilot, OpenCode, Hermes, và nhiều hơn nữa.

Cài Đặt: 2 Dòng, Xong

Nếu bạn dùng Claude Code:

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

Restart Claude Code. Context từ session trước sẽ tự động xuất hiện ở session mới. Không cần config gì thêm.

Đối với các agent khác:

        
# Gemini CLI
npx claude-mem install --ide gemini-cli

# OpenCode
npx claude-mem install --ide opencode

# OpenClaw (cách mình dùng)
curl -fsSL https://install.cmem.ai/openclaw.sh | bash

⚠️ Một cái bẫy nhỏ: npm install -g claude-mem chỉ cài SDK/library, KHÔNG đăng ký hooks hay khởi động worker. Phải dùng npx claude-mem install hoặc /plugin install mới chạy được. Mình mất 15 phút debug cái này, hy vọng bạn không bị như mình 💀

Architecture Deep Dive

Đây là phần mình thích nhất — mổ xẻ cách Claude-Mem được thiết kế.

Tổng Quan

Claude-Mem gồm 5 thành phần chính:

        
        
        
    
┌─────────────────────────────────────────────────────────────────┐
│                    CLAUDE CODE SESSION                           │
│                                                                  │
│  Setup → SessionStart → PromptSubmit → ToolUse → Stop → End    │
│    ↓          ↓              ↓           ↓        ↓       ↓     │
│  [check]  [2 hooks]      [hook]      [hook]    [hook]  [hook]  │
└─────────────────────────────────────────────────────────────────┘
      ↓          ↓              ↓           ↓        ↓       ↓
┌─────────────────────────────────────────────────────────────────┐
│                    CLAUDE-MEM SYSTEM                             │
│                                                                  │
│  Worker Service (Express HTTP API, port 37777)                  │
│  SQLite Database (observations, sessions, FTS5 search)          │
│  Chroma Vector DB (semantic search, optional)                   │
│  React Viewer UI (real-time memory stream)                      │
└─────────────────────────────────────────────────────────────────┘

Tech stack:

TypeScript (ES2022) + Node.js 20+ / Bun
SQLite 3 với FTS5 full-text search
Chroma (optional) cho semantic search
Express.js 5 cho HTTP API
React + TypeScript cho Viewer UI
Claude Agent SDK (hoặc Gemini / OpenRouter) cho AI compression

Hook System: Trái Tim Của Mọi Thứ

Đây là phần thông minh nhất của Claude-Mem. Nó không modify Claude Code (vốn là closed-source binary), mà quan sát từ bên ngoài thông qua lifecycle hooks.

Plugin đăng ký 7 hook scripts cho toàn bộ vòng đời của một Claude Code session:

┌──────────────────┬──────────────────────────────────────────────┐
│ HOOK             │ NHIỆM VỤ                                     │
├──────────────────┼──────────────────────────────────────────────┤
│ Setup            │ Check version marker (<100ms, always exit 0) │
│ SessionStart #1  │ Khởi động Bun worker nếu chưa chạy           │
│ SessionStart #2  │ Inject context từ session trước vào prompt    │
│ UserPromptSubmit │ Tạo session record + lưu raw prompt cho FTS5 │
│ PostToolUse (*)  │ Capture observation từ mọi tool call         │
│ Stop             │ Gọi Claude Agent SDK tạo session summary     │
│ SessionEnd       │ Graceful cleanup, không DELETE sessions      │
└──────────────────┴──────────────────────────────────────────────┘

Key insight: Mỗi hook phải chạy dưới 1 giây. AI compression (mất 5-30 giây) được đẩy hết ra background worker. Hooks chỉ làm đúng một việc: nhận data → đẩy vào queue → return ngay.

Đây là phần mình nể nhất. Design này giống như message queue pattern trong distributed systems — decouple ingestion với processing. Hooks là producer, worker là consumer.

        
        
        
    
Hook (nhanh, ~20ms)
  │
  ├─ Read stdin (<1ms)
  ├─ INSERT INTO observation_queue (<10ms)
  └─ Return success (<20ms total)
         │
         ▼ (queue)
Worker (chậm, 5-30s)
  ├─ Poll observation_queue
  ├─ Claude Agent SDK nén observation
  └─ Lưu vào observations table

Context Injection: Progressive Disclosure

Phần context injection cũng đáng nói. Thay vì nhồi toàn bộ history vào prompt (tốn token kinh khủng), SessionStart hook chỉ inject một index nhẹ:

        
# [claude-mem] recent context

**Legend:** 🎯 session-request | 🔴 gotcha | 🟡 problem-solution

### Oct 26, 2025

**General**
| ID | Time | T | Title | Tokens |
|----|------|---|-------|--------|
| #2586 | 12:58 AM | 🔵 | Context hook file empty | ~51 |
| #2590 | 01:15 AM | 🔴 | SQLite FTS5 query syntax | ~120 |

*Use MCP search tools to access full details*

Claude có thể dùng index này để tự quyết định có cần fetch full details không. Cơ chế này giống như L1/L2/L3 cache — fetch càng sâu thì càng tốn token, nhưng chỉ fetch khi thực sự cần.

Search Pipeline: 3-Layer Progressive Disclosure

Đây là phần làm mình “ồ” khi đọc source. Search trong Claude-Mem không phải là gọi một API rồi dump hết kết quả. Nó theo kiểu progressive disclosure — disclose từng layer một:

Layer 1: search() → Index nhẹ (~50-100 tokens/result)
   ↓ Chọn IDs quan tâm
Layer 2: timeline() → Context xung quanh (~100-200 tokens/obs)
   ↓ Xác nhận IDs cần đọc
Layer 3: get_observations() → Full details (~500-1000 tokens/obs)

So sánh token thực tế:

Cách tiếp cận	Token dùng	Độ liên quan
Traditional (fetch 20 obs)	10,000-20,000	~10%
3-Layer (search → filter → fetch)	~3,000	100%

Tiết kiệm ~10x. Với giá API của Claude, cái này không phải chuyện đùa.

Cách dùng thực tế:

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

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

// Step 3: Fetch only what you need
get_observations(ids=[123, 456])

MCP tools có sẵn: search, timeline, get_observations. Hỗ trợ FTS5 query syntax đầy đủ (AND, OR, NOT, phrase search, column-specific search).

Bonus: Từ v5.4.0+, có thêm mem-search skill — load nhanh hơn MCP tools, tiết kiệm thêm ~2,250 tokens mỗi session.

Worker Service: Bộ Não Background

Worker là Express.js HTTP server chạy trên port 37700 + (uid % 100) (mặc định 37777). Nhiệm vụ chính:

Search API: 10 endpoints cho full-text search, timeline, observations
Viewer UI: React app real-time memory stream qua SSE (Server-Sent Events)
Async Processing: Poll observation queue, dùng Claude Agent SDK để nén observations thành structured learnings
Multi-provider: Hỗ trợ Claude Agent SDK, Gemini, hoặc OpenRouter

Worker được manage bởi Bun — auto-start, auto-restart nếu crash. Cũng clean.

OpenClaw Integration

Phần mình quan tâm nhất vì mình dùng OpenClaw. OpenClaw’s embedded runner gọi Anthropic API trực tiếp — không spawn claude process — nên hooks của Claude Code không fire. Plugin Claude-Mem cho OpenClaw giải quyết vấn đề này bằng cách hook vào OpenClaw’s event system:

        
        
        
    
OpenClaw Gateway
  │
  ├── before_agent_start ───→ Init session
  ├── before_prompt_build ──→ Inject context vào system prompt
  ├── tool_result_persist ──→ Record observation (fire-and-forget)
  ├── agent_end ────────────→ Summarize + Complete session
  └── gateway_start ────────→ Reset session tracking
                    │
                    ▼
         Claude-Mem Worker (localhost:37777)

Context được inject vào system prompt thông qua appendSystemContext, không đụng đến MEMORY.md. Cache 60 giây để tránh re-fetch mỗi LLM turn.

Bonus: Observation feed — stream real-time observations đến Telegram, Discord, Slack, Signal, WhatsApp, LINE. Mỗi observation tạo 1 message kiểu:

🧠 Claude-Mem Observation
**Implemented retry logic for API client**
Added exponential backoff with configurable max retries

Cảm giác như có một đồng nghiệp AI gửi Slack update về những gì agent của bạn đang làm. Vừa hữu ích, vừa hơi creepy 😂

Điểm Mạnh

✅ Đa nền tảng: Claude Code, OpenClaw, Codex, Gemini, Copilot, OpenCode, Hermes — một plugin cho tất cả

✅ Non-invasive: Không modify agent behavior, chỉ quan sát qua hooks. Nếu plugin crash, agent vẫn chạy bình thường.

✅ Token-efficient: Progressive disclosure tiết kiệm ~10x token so với RAG truyền thống. Với giá API hiện tại, cái này translate thẳng ra tiền.

✅ Graceful cleanup: v4.1.0+ không DELETE sessions, worker tự finish processing rồi exit. Tránh race condition và mất pending observations.

✅ Real-time viewer: Web UI tại localhost:37777, xem memory stream live. Có infinite scroll, project filtering, GPU-accelerated animations.

✅ Multi-language: Hỗ trợ 28+ ngôn ngữ — từ tiếng Việt, Trung, Nhật, Hàn đến Hebrew, Ả Rập, Urdu, Bengali.

✅ OpenClaw native: Plugin riêng, tích hợp sâu với event system + observation feed đa kênh.

✅ Apache 2.0: Mã nguồn mở, có thể embed vào tools khác. Lý do chọn license này được tác giả nói thẳng: “durable agentic memory should be easy to embed in developer tools, local agents, MCP servers, enterprise systems, robotics stacks, and production agent harnesses.”

✅ Beta channel: Có Endless Mode — biomimetic memory architecture cho extended sessions. Dành cho ai muốn thử bleeding edge.

Điểm Yếu

Đây là phần quan trọng nhất. Mình không muốn viết bài PR — nên sẽ nói thẳng những gì chưa ổn.

1. SPOF: Worker Single Point of Failure

Worker là một process duy nhất. Nếu nó crash, observations bị stuck trong queue. Có recovery command (npm run queue:recover) nhưng bạn phải chủ động check. Không có health check tự động, không có alert. Trong production, cái này không ổn.

2. SQLite Không Phải Cho Multi-User

Database là một file local ~/.claude-mem/claude-mem.db. Không share được giữa nhiều máy, không có replication. OK cho dev cá nhân, không OK cho team. Nếu bạn đang nghĩ đến việc setup Claude-Mem cho cả team 5 người cùng làm 1 project — quên đi.

3. Chroma Optional, Nhưng Setup Không Hề Đơn Giản

Semantic search cần Chroma vector DB riêng. Mặc định chỉ có FTS5 full-text search — tức là keyword-based. Nếu bạn muốn search kiểu “tìm bug liên quan đến connection pooling” mà observation không có từ “connection pooling”, FTS5 sẽ miss. Cần Chroma để embedding-based search, nhưng setup thêm Chroma là thêm complexity. Không phải kiểu “chạy là xong”.

4. Token Cost Cho AI Compression

Mỗi observation được nén bằng Claude Agent SDK (hoặc Gemini/OpenRouter). Nhiều tool calls = nhiều API calls = tốn tiền. Một session làm việc 2 tiếng với Claude Code có thể sinh ra 50-100 observations. Mỗi lần nén tốn ~500-1000 tokens. Tính ra mỗi tháng có thể tốn vài USD chỉ riêng cho việc “nhớ”.

Docs không có cost estimate rõ ràng. Mình phải tự đo.

5. Không Có Retention Policy

Observations tích lũy không giới hạn. Chưa có auto-cleanup, TTL, hay archive policy. Database sẽ phình to theo thời gian. Dùng 6 tháng → vài chục MB. Dùng 2 năm → có thể vài GB. Không có tool để prune old data.

6. Privacy: Local Storage, Nhưng Cần Cẩn Thận

Tất cả observations lưu local SQLite. OK cho dev cá nhân. Nhưng nếu làm việc với codebase nhạy cảm (fintech, healthcare, internal tools của công ty) — bạn cần biết rằng mọi tool input/output đều bị capture. Có tag exclusion (<private>) nhưng phải config thủ công, không có auto-detection.

7. Phụ Thuộc Claude Code Hook API

Nếu Claude Code thay đổi hook API, plugin phải update. Lịch sử đã có breaking change từ Claude Code v2.1.0 (ultrathink update) — SessionStart hooks không còn hiển thị user-visible messages. Không phải lỗi của Claude-Mem, nhưng là risk nếu bạn phụ thuộc vào nó cho workflow hàng ngày.

So Sánh Với Alternatives

	Claude-Mem	Mem0	Zep	LangMem
Loại	Plugin (hooks)	API/SDK	Cloud API	SDK
Agent support	10+ agents	Universal	Universal	LangChain only
Storage	SQLite + Chroma	Cloud/Local	Cloud	In-memory/Redis
Search	FTS5 + Vector	Vector	Vector + Graph	Vector
Token efficiency	✅ Progressive disclosure	❌ Fetch all	❌ Fetch all	❌ Fetch all
Offline	✅ Fully local	❌ Cloud	❌ Cloud	✅ Local
Observability	✅ Viewer UI + Feed	❌ Dashboard	✅ Dashboard	❌ None
Cost	Free (self-hosted)	Freemium	Paid	Free
Setup	2 commands	API key	API key	pip install
Multi-user	❌	✅	✅	❌

Bottom line: Claude-Mem thắng ở token efficiency và multi-agent support. Mem0/Zep thắng ở multi-user. LangMem thắng ở simplicity. Chọn gì phụ thuộc vào bạn dùng một mình hay theo team, dùng Claude Code hay LangChain.

Cá nhân mình: nếu bạn dùng Claude Code hoặc OpenClaw một mình, Claude-Mem là lựa chọn on-premise tốt nhất hiện tại. Không cần nghĩ.

Verdict

Ai nên dùng:

Dev làm việc dài hạn trên cùng một project với Claude Code/OpenClaw
Muốn agent “nhớ” decisions, bug fixes, architecture choices giữa các sessions
Ưu tiên privacy (local storage), không muốn gửi data ra cloud
Muốn thứ gì đó chạy ngay sau 2 dòng command, không cần đọc docs dài dòng

Khi nào không nên dùng:

Project ngắn hạn, one-off scripts — setup không đáng công
Team cần share memory giữa nhiều người — cần cloud solution như Mem0/Zep
Budget hạn chế cho API calls — AI compression có hidden cost
Làm việc với codebase siêu nhạy cảm — cần audit kỹ những gì bị capture

Rating: ⭐⭐⭐⭐ (4/5)

Trừ 1 sao vì thiếu retention policy, worker SPOF, và không có cost estimate rõ ràng. Đây là những thứ một plugin 46K stars nên có.

Nhìn chung, Claude-Mem là plugin must-have cho bất kỳ ai dùng Claude Code hoặc OpenClaw thường xuyên. Mình đã cài vào OpenClaw được 2 tuần, và khác biệt rõ rệt nhất là: agent không còn hỏi lại những câu mình đã trả lời tuần trước. Nó “biết” mình đã làm gì, đã quyết định gì. Cảm giác như có đồng nghiệp mới — người đọc hết documentation của team trước khi join.

Cái cảm giác mở Claude Code lên, nhìn dòng context hiện ra, và nghĩ “à đúng rồi, lần trước mình đang dở cái này” — nó satisfying vcl.

Links:

GitHub: github.com/thedotmack/claude-mem
Docs: docs.claude-mem.ai
OpenClaw Integration: docs.claude-mem.ai/openclaw-integration
Discord: discord.gg/J4wttp9vDu

Bạn đã thử Claude-Mem chưa? Xài solution nào khác cho agent memory? Để lại comment, mình muốn nghe 🦞