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 more accurate semantic search but sends conversation data to Voyage AI for processing.

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

• 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

🔥 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

• 🔧 Fixed MCP Indexing: Now correctly shows 97.1% progress (was showing 0%)
• 🔥 HOT/WARM/COLD: Intelligent file prioritization for near real-time imports
• 📊 Enhanced Monitoring: Real-time status with visual indicators

For Existing Users

# Update to latest version
npm update -g claude-self-reflect

# Run setup - it will detect your existing installation
claude-self-reflect setup
# Choose "yes" when asked about metadata enrichment

# Or manually enrich metadata anytime:
docker compose run --rm importer python /app/scripts/delta-metadata-update-safe.py

What You Get

• search_by_concept("docker") - Find conversations by topic
• search_by_file("server.py") - Find conversations that touched specific files
• Better search accuracy with metadata-based filtering

• v2.5.18 - Security dependency updates
• v2.5.17 - Critical CPU fix and memory limit adjustment
• v2.5.16 - Initial streaming importer with CPU throttling
• v2.5.15 - Critical bug fixes and collection creation improvements
• v2.5.14 - Async importer collection fix
• v2.5.11 - Critical cloud mode fix
• v2.5.10 - Emergency hotfix for MCP server startup
• v2.5.6 - Tool Output Extraction

Full 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