GitHub - ramakay/claude-self-reflect: Claude forgets everything. This fixes that. 🔗 www.npmjs.com/package/claude-self-reflect

# Step 1: Get your free Voyage AI key
# Sign up at https://www.voyageai.com/ - it takes 30 seconds

# Step 2: Install with Voyage key
npm install -g claude-self-reflect
claude-self-reflect setup --voyage-key=YOUR_ACTUAL_KEY_HERE

[!NOTE] Cloud mode provides 1024-dimensional embeddings (vs 384 local) for more accurate semantic search but sends conversation data to Voyage AI for processing.

Real-time Quality Scoring in Statusline

Your code quality displayed live as you work:

• 🟢 A+ (95-100): Exceptional code quality
• 🟢 A (90-95): Excellent, production-ready
• 🟢 B (80-90): Good, minor improvements possible
• 🟡 C (60-80): Fair, needs refactoring
• 🔴 D (40-60): Poor, significant issues
• 🔴 F (0-40): Critical problems detected

Pattern Categories Analyzed

• Security Patterns: SQL injection, XSS vulnerabilities, hardcoded secrets
• Performance Patterns: N+1 queries, inefficient loops, memory leaks
• Error Handling: Bare exceptions, missing error boundaries
• Type Safety: Missing type hints, unsafe casts
• Async Patterns: Missing await, promise handling
• Testing Patterns: Test coverage, assertion quality

How It Works

1. During Import: AST elements extracted from all code blocks
2. Pattern Matching: 100+ patterns from unified registry
3. Quality Scoring: Weighted scoring normalized by lines of code
4. Statusline Display: Real-time feedback as you code

Search & Memory:

• reflect_on_past - Search past conversations using semantic similarity with time decay (supports quick/summary modes)
• store_reflection - Store important insights or learnings for future reference
• get_next_results - Paginate through additional search results
• search_by_file - Find conversations that analyzed specific files
• search_by_concept - Search for conversations about development concepts
• get_full_conversation - Retrieve complete JSONL conversation files

Temporal Queries:

• get_recent_work - Answer "What did we work on last?" with session grouping
• search_by_recency - Time-constrained search like "docker issues last week"
• get_timeline - Activity timeline with statistics and patterns

Runtime Configuration:

• switch_embedding_mode - Switch between local/cloud modes without restart
• get_embedding_mode - Check current embedding configuration
• reload_code - Hot reload Python code changes
• reload_status - Check reload state
• clear_module_cache - Clear Python cache

Status & Monitoring:

• get_status - Real-time import progress and system status
• get_health - Comprehensive system health check
• collection_status - Check Qdrant collection health and stats

[!TIP] Use reflect_on_past --mode quick for instant existence checks - returns count + top match only!

All tools are automatically available when the MCP server is connected to Claude Code.

See your indexing progress right in your terminal! Works with Claude Code Statusline:

• Progress Bar - Visual indicator [████████ ] 91%
• Indexing Lag - Shows backlog • 7h behind
• Auto-updates every 60 seconds
• Zero overhead with intelligent caching

Learn more about statusline integration →

Searches are project-aware by default. Claude automatically searches within your current project:

# In ~/projects/MyApp
You: "What authentication method did we use?"
Claude: [Searches ONLY MyApp conversations]

# To search everywhere
You: "Search all projects for WebSocket implementations"
Claude: [Searches across ALL your projects]

Recent conversations matter more. Old ones fade. Like your brain, but reliable.

• 90-day half-life: Recent memories stay strong
• Graceful aging: Old information fades naturally
• Configurable: Adjust decay rate to your needs

[!NOTE] Memory decay ensures recent solutions are prioritized while still maintaining historical context.

• Search: <3ms average response time
• Scale: 600+ conversations across 24 projects
• Reliability: 100% indexing success rate
• Memory: 96% reduction from v2.5.15
• Real-time: HOT/WARM/COLD intelligent prioritization

[!TIP] For best performance, keep Docker allocated 4GB+ RAM and use SSD storage.

HOT/WARM/COLD Intelligent Prioritization

• HOT (< 5 minutes): 2-second intervals for near real-time import
• WARM (< 24 hours): Normal priority with starvation prevention
• COLD (> 24 hours): Batch processed to prevent blocking

Files are categorized by age and processed with priority queuing to ensure newest content gets imported quickly while preventing older files from being starved.

Components

• Vector Database: Qdrant for semantic search
• MCP Server: Python-based using FastMCP
• Embeddings: Local (FastEmbed) or Cloud (Voyage AI)
• Import Pipeline: Docker-based with automatic monitoring

Minimum Requirements

• Docker Desktop (macOS/Windows) or Docker Engine (Linux)
• Node.js 16+ (for the setup wizard)
• Claude Code CLI
• 4GB RAM available for Docker
• 2GB disk space for vector database

Recommended

• 8GB RAM for optimal performance
• SSD storage for faster indexing
• Docker Desktop 4.0+ for best compatibility

Operating Systems

• macOS 11+ (Intel & Apple Silicon)
• Windows 10/11 with WSL2
• Linux (Ubuntu 20.04+, Debian 11+)

• Vector DB: Qdrant (local, your data stays yours)
• Embeddings:
  • Local (Default): FastEmbed with all-MiniLM-L6-v2
  • Cloud (Optional): Voyage AI
• MCP Server: Python + FastMCP
• Search: Semantic similarity with time decay

• Performance tuning
• Security & privacy
• Windows setup
• Architecture details
• Contributing

• Troubleshooting Guide
• GitHub Issues
• Discussions

For complete uninstall instructions, see docs/UNINSTALL.md.

Quick uninstall:

# Remove MCP server
claude mcp remove claude-self-reflect

# Stop Docker containers
docker-compose down

# Uninstall npm package
npm uninstall -g claude-self-reflect

v7.0 - Automated Narratives (Oct 2025)

• 9.3x better search quality via AI-powered conversation summaries
• 50% cost savings using Anthropic Batch API ($0.012 per conversation)
• 82% token compression while maintaining searchability
• Rich metadata extraction (tools, concepts, files)
• Problem-solution narrative structure
• Automated batch processing with Docker monitoring

v4.0 - Performance Revolution (Sep 2025)

• 20x faster status checks (119ms → 6ms)
• 50% storage reduction via unified state management
• 10x faster imports (10/sec → 100/sec)
• 90% memory reduction (500MB → 50MB)
• Runtime mode switching (no restart required)
• Prefixed collection naming (breaking change)
• Code quality tracking with AST-GREP (100+ patterns)

v3.3 - Temporal Intelligence (Aug 2025)

• Time-based search: "docker issues last week"
• Session grouping: "What did we work on last?"
• Activity timelines with statistics
• Recency-aware queries

v2.8 - Full Context Access (Jul 2025)

• Complete conversation retrieval
• JSONL file access for deeper analysis
• Enhanced debugging capabilities

View complete changelog →

1. "No collections created" after import

Symptom: Import runs but Qdrant shows no collections
Cause: Docker can't access Claude projects directory
Solution:

# Run diagnostics to identify the issue
claude-self-reflect doctor

# Fix: Re-run setup to set correct paths
claude-self-reflect setup

# Verify .env has full paths (no ~):
cat .env | grep CLAUDE_LOGS_PATH
# Should show: CLAUDE_LOGS_PATH=/Users/YOUR_NAME/.claude/projects

2. MCP server shows "ERROR" but it's actually INFO

Symptom: [ERROR] MCP server "claude-self-reflect" Server stderr: INFO Starting MCP server
Cause: Claude Code displays all stderr output as errors
Solution: This is not an actual error - the MCP is working correctly. The INFO message confirms successful startup.

3. "No JSONL files found"

Symptom: Setup can't find any conversation files
Cause: Claude Code hasn't been used yet or stores files elsewhere
Solution:

# Check if files exist
ls ~/.claude/projects/

# If empty, use Claude Code to create some conversations first
# The watcher will import them automatically

4. Docker volume mount issues

Symptom: Import fails with permission errors
Cause: Docker can't access home directory
Solution:

# Ensure Docker has file sharing permissions
# macOS: Docker Desktop → Settings → Resources → File Sharing
# Add: /Users/YOUR_USERNAME/.claude

# Restart Docker and re-run setup
docker compose down
claude-self-reflect setup

5. Qdrant not accessible

Symptom: Can't connect to localhost:6333
Solution:

# Start services
docker compose --profile mcp up -d

# Check if running
docker compose ps

# View logs for errors
docker compose logs qdrant

Run Comprehensive Diagnostics

claude-self-reflect doctor

This checks:

• Docker installation and configuration
• Environment variables and paths
• Claude projects and JSONL files
• Import status and collections
• Service health

Check Logs

# View all service logs
docker compose logs -f

# View specific service
docker compose logs qdrant
docker compose logs watcher

Generate Diagnostic Report

# Create diagnostic file for issue reporting
claude-self-reflect doctor > diagnostic.txt

1. Check Documentation

   • Troubleshooting Guide
   • FAQ
   • Windows Setup

2. Community Support

   • GitHub Discussions
   • Discord Community

3. Report Issues

   • GitHub Issues
   • Include diagnostic output when reporting