claude-code-ultimate-guide/docs/resource-evaluations/claude-mem-evaluation.md

Resource Evaluation: claude-mem

Resource: thedotmack/claude-mem - Persistent Memory for Claude Code URL: https://github.com/thedotmack/claude-mem Type: Plugin / MCP Server Evaluated: 2026-02-10 Evaluator: Florian BRUNIAUX + Claude (Anthropic)

---

Quick Summary

Score: 4/5 (High Value - Integrate within 1 week)

Claude-mem is a Claude Code plugin providing automatic session memory through AI-compressed capture of tool usage, observations, and decisions. It fills a gap in the guide: while Serena (symbol memory) and grepai (semantic search) are documented, automatic session capture is not.

Key Stats (verified 2026-02-10):

• 26.5k GitHub stars, 1.8k forks
• 181 releases, 46 contributors
• Latest: v9.1.1 (Feb 7, 2026)
• License: AGPL-3.0 + PolyForm Noncommercial

---

Content Summary

What claude-mem does:

1. Automatic Capture: Hooks into Claude Code lifecycle (SessionStart, PostToolUse, Stop, SessionEnd) to record all tool operations
2. AI Compression: Uses Claude to generate semantic summaries of observations (~10x token reduction)
3. Hybrid Search: Full-text + vector search (Chroma) + natural language queries
4. Progressive Disclosure: 3-layer retrieval (search → timeline → get_observations) saves 95% tokens
5. Web Dashboard: Real-time UI at http://localhost:37777 for exploring session history
6. Automatic Injection: Relevant context auto-injected at session start

Architecture:

Lifecycle Hooks → Observation capture → AI compression (Claude)
                                             ↓
                                    SQLite storage
                                             ↓
                              Chroma vector indexation
                                             ↓
                              Session start injection

Performance claims (from articles, not independently verified):

• Progressive disclosure: 10x token reduction
• Endless Mode (beta): 95% context reduction → 20x more tool calls before limits
• Cost: ~$0.15 per 100 observations processed

---

Relevance Score: 4/5

Why 4/5 (High Value)?

✅ Strengths:

1. Gap Identified: Guide documents Serena (symbol memory, manual) and grepai (semantic search) but not automatic session capture
2. Massive Adoption: 26.5k stars, 181 releases, 46 active contributors
3. Production-Ready: AGPL-3.0 licensed, stable API, active maintenance
4. Complementary: Doesn't replace existing tools, enhances them
5. Token Efficiency: Progressive disclosure pattern valuable for context management

⚠️ Why Not 5/5?:

1. Pattern Partially Covered: Serena write_memory() exists for manual memory, so gap is "automatic" not "memory"
2. AGPL-3.0 Restrictions: Commercial use limitations, source disclosure requirements
3. Hidden Costs: $0.15/100 observations not documented in official README
4. CLI Only: No web interface, no cloud sync, no multi-machine support
5. Niche Use Case: Benefits users with >10 sessions/week, less valuable for occasional users

Comparison to Existing Coverage

Aspect	This Resource (claude-mem)	Our Guide (v3.23.4)
Automatic session capture	✅ Core feature	❌ Missing
Tool usage tracking	✅ Hooks-based	➕ Documented (hooks architecture) but no specific tool
Progressive disclosure	✅ 3-layer workflow	❌ Pattern not documented
Session-to-session memory	✅ Automatic injection	➕ Partial (Serena manual, not auto)
Web dashboard	✅ Real-time UI	❌ Missing
Token efficiency patterns	✅ 95% reduction	➕ Documented (context management) but not this magnitude
AGPL licensing implications	⚠️ Restrictions	❌ Missing (licensing considerations)
Cost: API compression	⚠️ $0.15/100 obs	❌ Missing (hidden costs)
Platform limitations	⚠️ CLI only	❌ Missing

Summary: Guide covers building blocks (hooks, MCP, Serena) but lacks integrated solution that claude-mem provides. Gap is moderate (not critical) because patterns exist, but automatic capture adds significant value.

---

Integration Recommendations

Where to Document

Recommended: Section 8.2.5 (after grepai) in guide/ultimate-guide.md ~line 8463

Structure:

## 8.2.5 claude-mem (Automatic Session Capture)

### Architecture & Features
- Lifecycle hooks integration
- AI compression workflow
- Progressive disclosure pattern
- Web dashboard overview

### Installation & Setup
- Plugin marketplace installation
- Configuration options
- Privacy controls (<private> tags)

### Usage Patterns
- Automatic injection workflow
- Natural language queries
- Web UI navigation

### Cost & Privacy Considerations
- API compression costs ($0.15/100 obs)
- AGPL-3.0 licensing implications
- Data locality (SQLite + Chroma)
- Privacy tags for sensitive content

### Decision Matrix: vs Serena vs grepai
| Need | Tool | Rationale |
|------|------|-----------|
| Auto capture tool usage | claude-mem | Zero manual effort |
| Symbol-aware navigation | Serena | Precise editing |
| Semantic discovery | grepai | Intent-based search |
| Manual decision storage | Serena | Explicit control |

### Hybrid Workflows
- claude-mem + Serena (auto capture + manual decisions)
- claude-mem + grepai (session history + semantic search)
- Complete stack: rg → grepai → Serena → claude-mem

Size: 300-400 lines (not 800 as initially proposed)

Files to Create/Modify

1. guide/ultimate-guide.md

   • Add Section 8.2.5 (~300 lines)
   • Update Section 2.2 (Session vs Persistent Memory) with claude-mem reference

2. machine-readable/reference.yaml

   claude_mem: "guide/ultimate-guide.md:8463"
   claude_mem_architecture: "guide/ultimate-guide.md:8470"
   claude_mem_progressive_disclosure: "guide/ultimate-guide.md:8520"
   claude_mem_dashboard: "guide/ultimate-guide.md:8550"
   claude_mem_vs_serena: "guide/ultimate-guide.md:8600"
   claude_mem_installation: "/plugin marketplace add thedotmack/claude-mem"
   claude_mem_repo: "https://github.com/thedotmack/claude-mem"
   claude_mem_stars: "26.5k"
   claude_mem_license: "AGPL-3.0"
   claude_mem_score: "4/5"
   

3. examples/plugins/claude-mem.md (installation template)

4. CHANGELOG.md

   ## [3.24.0] - 2026-02-XX
   
   ### Added
   - **Section 8.2.5**: claude-mem plugin documentation
   - Memory Stack Patterns (claude-mem + Serena + grepai integration)
   - Decision matrix for memory tools
   

Priority

High Value - Integrate within 1 week

Rationale:

• Fills genuine gap (automatic capture not documented)
• Massive community adoption (26.5k stars)
• Complementary to existing tools
• BUT not "Critical" (5/5) because patterns partially exist

---

Technical Analysis: claude-mem vs Serena vs grepai

Architecture Comparison

Aspect	claude-mem	Serena	grepai
Purpose	Session capture	Symbol memory	Semantic search
Trigger	Auto (hooks)	Manual API	Manual CLI
Storage	SQLite + Chroma	.serena/memories/	Ollama vectors
Technology	AI compression	Key-value store	Embeddings
Indexation	Session events	Project symbols	Code files
Query	Natural language	Key lookup	Semantic search
Dashboard	✅ Web UI	❌ No	❌ No
Cost	$0.15/100 obs	Free (local)	Free (local)
Privacy	✅ Local	✅ Local	✅ Local

Use Case Matrix

Need	Tool	Example
"What did we do yesterday?"	claude-mem	Auto-inject previous context
"Find function login"	Serena	find_symbol --name "login"
"Who calls this function?"	grepai	grepai trace callers "login"
"Record arch decision"	Serena	write_memory("auth", "JWT")
"Find code that does X"	grepai	grepai search "payment validation"
"Summary of all sessions"	claude-mem	Web dashboard + search
"Exact pattern 'authenticate'"	rg (native)	rg "authenticate" --type ts

Memory Stack Pattern (Proposed)

┌─────────────────────────────────────────────────────────┐
│           Memory Stack (4 layers)                       │
├─────────────────────────────────────────────────────────┤
│ Layer 4: Session Capture   → claude-mem (automatic)    │
│ Layer 3: Symbol Memory     → Serena (manual decisions) │
│ Layer 2: Semantic Search   → grepai (discovery)        │
│ Layer 1: Exact Search      → rg (native, fast)         │
└─────────────────────────────────────────────────────────┘

Integrated Workflow Example:

# Scenario: Refactoring auth module after 3 days

# 1. AUTO CONTEXT (claude-mem)
# At session start, Claude injects:
# "3 previous sessions explored auth module.
#  Decision: Migrate to JWT.
#  Files modified: auth.service.ts, session.middleware.ts"

# 2. ARCH DECISIONS (Serena)
serena list_memories
# → "auth_decision: Use JWT for stateless API (2026-02-07)"

serena read_memory("auth_decision")

# 3. SEMANTIC DISCOVERY (grepai)
grepai search "JWT token validation"
# → Finds validateJWT() in auth.service.ts

# 4. DEPENDENCIES (grepai trace)
grepai trace callers "validateJWT"
# → Called by: ApiGateway, AdminPanel, UserController

# 5. EXACT SEARCH (rg)
rg "validateJWT" --type ts -A 5

Result: Complete context without re-reading all files, safe refactoring.

---

Fact-Check Results

Claim	Source	Verified	Notes
26.5k stars	GitHub (WebFetch 2026-02-10)	✅	Perplexity had 15.6k (outdated)
1.8k forks	GitHub	✅	Confirmed
181 releases	GitHub	✅	Perplexity had 174 (outdated)
46 contributors	GitHub	✅	Perplexity had 22 (outdated)
AGPL-3.0 license	GitHub README	✅	+ PolyForm Noncommercial for ragtime/
Latest: v9.1.1 (Feb 7, 2026)	GitHub releases	✅	Active
Target: Claude Code	GitHub README	✅	Primary (+ Desktop secondary support)
Guide doesn't document Serena	ultimate-guide.md grep	❌ FALSE	10 occurrences found
Guide doesn't document grepai	ultimate-guide.md grep	❌ FALSE	22 occurrences found
Progressive disclosure 10x	Perplexity + articles	⚠️	Claim verified but metric approximate
$0.15/100 observations	External articles	⚠️	Not found in official README
95% Endless Mode	Articles	⚠️	Beta claim, not independently verified

Corrections Applied:

1. Gap analysis corrected: Guide DOES document Serena (lines 686, 762, 765, 770, 775, 779, 968, 1521, 1532) and grepai (22 mentions). Gap is not "no memory docs" but "no automatic capture solution".

2. Stats verified: 26.5k stars (Perplexity outdated), 181 releases, 46 contributors.

3. Product target: Claude Code (primary), not confused with Desktop.

4. Perplexity reliability: Detected outdated data → always verify GitHub directly for critical stats.

---

Limitations & Considerations

claude-mem Limitations

1. AGPL-3.0 License

   • Modifications require source disclosure
   • Network deployment requires AGPL
   • Commercial use restrictions

2. Hidden Costs

   • $0.15 per 100 observations (API compression)
   • Not documented in official README
   • Can accumulate on large projects

3. CLI Only

   • No web interface support
   • No cloud sync between machines
   • No VS Code integration

4. Manual Privacy Tags

   • <private> tags required for sensitive content
   • Forgetting tags → sensitive data in DB
   • No automatic secret detection

Overlaps with Existing Tools

Guide already documents:

• Session search (guide/observability.md:29)
• Session migration (guide/observability.md:175)
• Context management (/compact, /clear)

Question: Does claude-mem provide enough incremental value to justify 300-400 lines?

Answer: Yes, because:

• ✅ Automatic capture (vs manual Serena)
• ✅ AI compression (vs raw sessions)
• ✅ Web dashboard (vs CLI only)
• ✅ Progressive disclosure (token efficiency)

---

Technical Writer Challenge Results

Agent ID: ac8e0c6

Challenge Summary:

The technical-writer agent challenged the initial 5/5 score, identifying:

1. False premise: "Guide doesn't document Serena/grepai" → FALSE (both documented)
2. Stats contradictions: 15.6k vs 26.5k stars → Required verification
3. Product confusion: Clarified Claude Code vs Claude Desktop targeting
4. Sizing issues: 800 lines over-dimensioned → Reduced to 300-400 lines
5. Urgency questioned: <24h unrealistic → Changed to 1 week

Result: Score adjusted from 5/5 → 4/5 based on:

• Gap is real but moderate (Serena/grepai exist, automatic capture missing)
• AGPL-3.0 + hidden costs + CLI-only = limitations
• Complementary tool, not critical infrastructure

---

External Resources

Articles:

• Corti.com: Claude-Mem Deep Dive (2026-02-03)
• yuv.ai: Persistent Memory Guide (2026-02-05)
• byteiota: Progressive Disclosure Analysis (2026-02-04)

Videos:

• YouTube: 5-Minute Setup Guide (2026-02-06)
• YouTube: Unlimited Memory Demo (2026-02-05)

GitHub:

• thedotmack/claude-mem
• Release Notes v9.1.1

Benchmarks:

• No independent benchmarks found as of 2026-02-10
• Claims from articles: "95% context reduction, 20x tool calls" (not verified)
• Progressive disclosure: "10x token reduction" (plausible based on architecture)

---

Decision

Score: 4/5 (High Value - Integrate within 1 week)

Action:

1. Integrate Section 8.2.5 in guide/ultimate-guide.md (300-400 lines)
2. Update machine-readable/reference.yaml with claude-mem entries
3. Create plugin template in examples/plugins/claude-mem.md
4. Add to CHANGELOG.md v3.24.0

Confidence: High (stats verified, architecture understood, integration plan clear)

---

Evaluated: 2026-02-10 Next Review: Before v3.24.0 integration Status: Approved for integration