marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add claude-mem plugin documentation (automatic session memory)

Browse source 
Integrate claude-mem (thedotmack/claude-mem) into the guide as Section 8.2.5.
Score: 4/5 (High Value - automatic session capture fills documentation gap).

Added:
- Section 8.2.5: claude-mem plugin (automatic session memory)
  * Automatic capture via lifecycle hooks
  * AI compression + progressive disclosure (10x tokens)
  * Web dashboard at localhost:37777
  * Natural language search
  * Privacy controls (<private> tags)
  * Cost analysis ($0.15/100 obs)
  * AGPL-3.0 licensing considerations

- Memory Tools Decision Matrix (claude-mem vs Serena vs grepai)
  * 4-layer memory stack pattern
  * Integrated workflow examples
  * When to use automatic vs manual memory

- Plugin template: examples/plugins/claude-mem.md
  * Installation, configuration, troubleshooting
  * Advanced features (progressive disclosure, endless mode)
  * Export/import, cost optimization

- Resource evaluation: docs/resource-evaluations/claude-mem-evaluation.md
  * Technical analysis (fact-checked stats)
  * Comparison to existing tools
  * Integration recommendations

- reference.yaml: 14 new claude-mem entries

Changed:
- Updated search tools comparison (5 tools: rg, grepai, Serena, ast-grep, claude-mem)
- Extended feature matrix with "Auto capture" and "Web dashboard" rows

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

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX 2026-02-10 08:47:17 +01:00
parent 9031c8fd05
commit d5c3a82cac
5 changed files with 1190 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

388
docs/resource-evaluations/claude-mem-evaluation.md Normal file
View file

@ -0,0 +1,388 @@
# 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**:
```markdown
## 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**
```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**
```markdown
## [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**:
```bash
# 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](https://corti.com/claude-mem-persistent-memory-for-ai-coding-assistants/) (2026-02-03)
- [yuv.ai: Persistent Memory Guide](https://yuv.ai/blog/claude-mem) (2026-02-05)
- [byteiota: Progressive Disclosure Analysis](https://byteiota.com/claude-mem-persistent-memory-for-claude-code/) (2026-02-04)
**Videos**:
- [YouTube: 5-Minute Setup Guide](https://www.youtube.com/watch?v=ryqpGVWRQxA) (2026-02-06)
- [YouTube: Unlimited Memory Demo](https://www.youtube.com/watch?v=qhuS__jC4n8) (2026-02-05)
**GitHub**:
- [thedotmack/claude-mem](https://github.com/thedotmack/claude-mem)
- [Release Notes v9.1.1](https://github.com/thedotmack/claude-mem/releases/tag/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