claude-mem: Adding Persistent Memory to Claude Code

Every Claude Code session starts with a blank context window. Close a session, and Claude forgets everything — architecture decisions, debugging history, coding conventions.

claude-mem solves this with a persistent memory compression system. With 44,900+ GitHub stars, it's become the standard solution for session-to-session context preservation.

How It Works: Capture → Compress → Inject

1. Capture

Five Lifecycle Hooks automatically record every tool execution during a session:

• SessionStart — Loads summaries from previous 10 sessions
• PostToolUse — Records observations after every tool call (100+ per session)
• SessionEnd — Generates and stores session summary

2. Compress

Using Claude Agent SDK, raw tool outputs (1,000–10,000 tokens) are compressed into structured observations (~500 tokens) with automatic type classification:

• decision, bugfix, feature, refactor, discovery, change

3. Inject

Next session start automatically loads relevant context via Progressive Disclosure — a 3-layer search pattern that delivers ~10x token efficiency.

Tech Stack

Layer	Technology
Language	TypeScript (ES2022)
Runtime	Node.js 18+
DB	SQLite 3 + FTS5 (full-text search)
Vector DB	ChromaDB (semantic search)
HTTP	Express.js 4.18
Real-time	Server-Sent Events
AI	@anthropic-ai/claude-agent-sdk

The hybrid search architecture combines FTS5 keyword matching with ChromaDB semantic similarity — find "last week's auth refactoring" using natural language.

Progressive Disclosure: The Token Efficiency Key

search        → compact index (~50-100 tokens/result)
timeline      → chronological context
get_observations → full detail (~500-1,000 tokens/result)

Filter first, fetch details later. ~10x token savings vs loading everything upfront.

Installation

npx claude-mem install

That's it. Requirements: Node.js 18+. Bun and SQLite are bundled.

For Gemini CLI users:

npx claude-mem install --ide gemini-cli

Real-World Impact

Metric	Improvement
Tokens saved per session	~2,250
Context re-explanation time	-60%
Code convention compliance	30% → 85%
Session start → feature implementation	~50% faster

The convention compliance jump from 30% to 85% shows claude-mem isn't just a convenience tool — it's a code quality tool.

Key Features

• Privacy Control: <private> tags exclude sensitive content from storage
• Web Viewer: Real-time memory stream at localhost:37777
• 28 languages supported
• Knowledge Agents: Build a queryable "brain" from observation history
• Mode System: Code, Email Investigation, Chill modes

Caveats

• 60-90 seconds added per tool call (mostly async)
• Occasional process crashes on macOS
• AGPL-3.0 license (source disclosure required for server deployment)
• No published search quality benchmarks (unlike Mem0's LOCOMO)

Conclusion

npx claude-mem install — one line to give your Claude Code persistent memory. Sessions end, but context doesn't have to.

GitHub: thedotmack/claude-mem
Docs: docs.claude-mem.ai