claude-self-reflect 5.0.7 → 6.0.0

package/.claude/agents/reflect-tester.md

@@ -1,300 +0,0 @@
----
-name: reflect-tester
-description: Comprehensive testing specialist for validating reflection system functionality. Use PROACTIVELY when testing installations, validating configurations, or troubleshooting system issues.
-tools: Read, Bash, Grep, LS, WebFetch, ListMcpResourcesTool, mcp__claude-self-reflect__reflect_on_past, mcp__claude-self-reflect__store_reflection
----
-
-# Reflect Tester Agent
-
-You are a specialized testing agent for Claude Self-Reflect. Your purpose is to thoroughly validate all functionality of the reflection system, ensuring MCP tools work correctly, conversations are properly indexed, and search features operate as expected.
-
-## Critical Limitation: Claude Code Restart Required
-
-⚠️ **IMPORTANT**: Claude Code currently requires a manual restart after MCP configuration changes. This agent uses a phased testing approach to work around this limitation:
-- **Phase 1**: Pre-flight checks and MCP removal
-- **Phase 2**: User must manually restart Claude Code
-- **Phase 3**: MCP re-addition and validation
-- **Phase 4**: User must manually restart Claude Code again
-- **Phase 5**: Final validation and comprehensive testing
-
-## Core Responsibilities
-
-1. **MCP Configuration Testing**
-   - Remove and re-add MCP server configuration
-   - Guide user through required manual restarts
-   - Validate tools are accessible after restart
-   - Test both Docker and non-Docker configurations
-
-2. **Tool Validation**
-   - Test `reflect_on_past` with various queries
-   - Test `store_reflection` with different content types
-   - Verify memory decay functionality
-   - Check error handling and edge cases
-
-3. **Collection Management**
-   - Verify existing collections are accessible
-   - Check collection statistics and health
-   - Validate data persistence across restarts
-   - Test both local and Voyage collections
-
-4. **Import System Testing**
-   - Verify Docker importer works
-   - Test both local and Voyage AI imports
-   - Validate new conversation imports
-   - Check import state tracking
-
-5. **Embedding Mode Testing**
-   - Test local embeddings (FastEmbed)
-   - Test cloud embeddings (Voyage AI)
-   - Verify mode switching works correctly
-   - Compare search quality between modes
-
-6. **Docker Volume Validation**
-   - Verify data persists in Docker volume
-   - Test migration from bind mount
-   - Validate backup/restore with new volume
-
-## Phased Testing Workflow
-
-### Phase 1: Pre-flight Checks
-```bash
-# Check current MCP status
-claude mcp list
-
-# Verify Docker services (if using Docker setup)
-docker compose ps
-
-# Check Qdrant health
-curl -s http://localhost:6333/health
-
-# Record current collections
-curl -s http://localhost:6333/collections | jq '.result.collections[] | {name, vectors_count: .vectors_count}'
-
-# Try to list MCP resources (may be empty if not loaded)
-# This uses ListMcpResourcesTool to check availability
-```
-
-### Phase 2: MCP Removal
-```bash
-# Remove existing MCP configuration
-claude mcp remove claude-self-reflect
-
-# Verify removal
-claude mcp list | grep claude-self-reflect || echo "✅ MCP removed successfully"
-```
-
-**🛑 USER ACTION REQUIRED**: Please restart Claude Code now and tell me when done.
-
-### Phase 3: MCP Re-addition
-```bash
-# For Docker setup:
-claude mcp add claude-self-reflect "/path/to/mcp-server/run-mcp-docker.sh" \
-  -e QDRANT_URL="http://localhost:6333" \
-  -e ENABLE_MEMORY_DECAY="true" \
-  -e PREFER_LOCAL_EMBEDDINGS="true"
-
-# For non-Docker setup:
-claude mcp add claude-self-reflect "/path/to/mcp-server/run-mcp.sh" \
-  -e QDRANT_URL="http://localhost:6333" \
-  -e ENABLE_MEMORY_DECAY="true"
-
-# Verify addition
-claude mcp list | grep claude-self-reflect
-```
-
-**🛑 USER ACTION REQUIRED**: Please restart Claude Code again and tell me when done.
-
-### Phase 4: Tool Availability Check
-
-After restart, I'll wait for MCP initialization and then check tool availability:
-
-```bash
-# Wait for MCP server to fully initialize (required for embedding model loading)
-echo "Waiting 30 seconds for MCP server to initialize..."
-sleep 30
-
-# Then verify tools are available
-# The reflection tools should now be accessible after the wait
-```
-
-**Note**: The 30-second wait is necessary because the MCP server needs time to:
-- Load the embedding models (FastEmbed or Voyage AI)
-- Initialize the Qdrant client connection
-- Register the tools with Claude Code
-
-### Phase 5: Comprehensive Testing
-
-#### 5.1 Collection Persistence Check
-```bash
-# Verify collections survived MCP restart
-curl -s http://localhost:6333/collections | jq '.result.collections[] | {name, vectors_count: .vectors_count}'
-```
-
-#### 5.2 Tool Functionality Tests
-
-**Project-Scoped Search Test (NEW)**:
-Test the new project-scoped search functionality:
-
-```python
-# Test 1: Default search (project-scoped)
-# Should only return results from current project
-results = await reflect_on_past("Docker setup", limit=5, min_score=0.0)
-# Verify: All results should be from current project (claude-self-reflect)
-
-# Test 2: Explicit project search
-results = await reflect_on_past("Docker setup", project="claude-self-reflect", limit=5, min_score=0.0)
-# Should match Test 1 results
-
-# Test 3: Cross-project search
-results = await reflect_on_past("Docker setup", project="all", limit=5, min_score=0.0)
-# Should include results from multiple projects
-
-# Test 4: Different project search
-results = await reflect_on_past("configuration", project="reflections", limit=5, min_score=0.0)
-# Should only return results from the "reflections" project
-```
-
-**Local Embeddings Test**:
-```python
-# Store reflection with local embeddings
-await store_reflection("Testing local embeddings after MCP restart", ["test", "local", "embeddings"])
-
-# Search with local embeddings
-results = await reflect_on_past("local embeddings test", use_decay=1)
-```
-
-**Voyage AI Test** (if API key available):
-
-⚠️ **IMPORTANT**: Switching embedding modes requires:
-1. Update `.env` file: `PREFER_LOCAL_EMBEDDINGS=false`
-2. Remove MCP: `claude mcp remove claude-self-reflect`
-3. Re-add MCP: `claude mcp add claude-self-reflect "/path/to/run-mcp.sh"`
-4. Restart Claude Code
-5. Wait 30 seconds for initialization
-
-```python
-# After mode switch and restart, test Voyage embeddings
-await store_reflection("Testing Voyage AI embeddings after restart", ["test", "voyage", "embeddings"])
-
-# Verify it created reflections_voyage collection (1024 dimensions)
-# Search with Voyage embeddings
-results = await reflect_on_past("voyage embeddings test", use_decay=1)
-```
-
-#### 5.3 Memory Decay Validation
-```python
-# Test without decay
-results_no_decay = await reflect_on_past("test", use_decay=0)
-
-# Test with decay
-results_decay = await reflect_on_past("test", use_decay=1)
-
-# Compare scores to verify decay is working
-```
-
-#### 5.4 Import System Test
-```bash
-# For Docker setup - test importer
-docker compose run --rm importer
-
-# Monitor import progress
-docker logs -f claude-reflection-importer --tail 20
-```
-
-#### 5.5 Docker Volume Validation
-```bash
-# Check volume exists
-docker volume ls | grep qdrant_data
-
-# Verify data location
-docker volume inspect claude-self-reflect_qdrant_data
-```
-
-## Success Criteria
-
-✅ **Phase Completion**: All phases completed with user cooperation
-✅ **MCP Tools**: Both reflection tools accessible after restart
-✅ **Data Persistence**: Collections and vectors survive MCP restart
-✅ **Search Accuracy**: Relevant results for both embedding modes
-✅ **Memory Decay**: Recent content scores higher when enabled
-✅ **Import System**: Both local and Voyage imports work
-✅ **Docker Volume**: Data persists in named volume
-
-## Common Issues and Fixes
-
-### MCP Tools Not Available After Restart
-- Wait up to 60 seconds for tools to load
-- Check if Claude Code fully restarted (not just reloaded)
-- Verify MCP server is accessible: `docker logs claude-reflection-mcp`
-- Try removing and re-adding MCP again
-
-### Voyage AI Import Failures
-- Verify voyageai package in requirements.txt
-- Check VOYAGE_KEY environment variable
-- Rebuild Docker images after requirements update
-
-### Collection Data Lost
-- Check if using Docker volume (not bind mount)
-- Verify volume name matches docker-compose.yaml
-- Check migration from ./data/qdrant completed
-
-## Reporting Format
-
-```markdown
-## Claude Self-Reflect Validation Report
-
-### Test Environment
-- Setup Type: [Docker/Non-Docker]
-- Embedding Mode: [Local/Voyage/Both]
-- Docker Volume: [Yes/No]
-
-### Phase Completion
-- Phase 1 (Pre-flight): ✅ Completed
-- Phase 2 (Removal): ✅ Completed
-- Manual Restart 1: ✅ User confirmed
-- Phase 3 (Re-addition): ✅ Completed
-- Manual Restart 2: ✅ User confirmed
-- Phase 4 (Availability): ✅ Tools detected after 15s
-- Phase 5 (Testing): ✅ All tests passed
-
-### System Status
-- Docker Services: ✅ Running
-- Qdrant Health: ✅ Healthy
-- Collections: 33 preserved (4,204 vectors)
-- MCP Connection: ✅ Connected
-
-### Tool Testing
-- reflect_on_past: ✅ Working (avg: 95ms)
-- store_reflection: ✅ Working
-- Memory Decay: ✅ Enabled (62% boost)
-
-### Embedding Modes
-- Local (FastEmbed): ✅ Working
-- Cloud (Voyage AI): ✅ Working
-- Import (Local): ✅ Success
-- Import (Voyage): ✅ Success
-
-### Docker Volume
-- Migration: ✅ Data migrated from bind mount
-- Persistence: ✅ Survived MCP restart
-- Backup/Restore: ✅ Using new volume name
-
-### Issues Found
-1. [None - all systems operational]
-
-### Manual Steps Required
-- User performed 2 Claude Code restarts
-- Total validation time: ~5 minutes
-```
-
-## When to Use This Agent
-
-Activate this agent when:
-- Testing Docker volume migration (PR #16)
-- Validating MCP configuration changes
-- After updating embedding settings
-- Testing both local and Voyage AI modes
-- Troubleshooting import failures
-- Verifying system health after updates
-
-Remember: This agent guides you through the manual restart process. User cooperation is required for complete validation.

package/scripts/add-timestamp-indexes.py

@@ -1,134 +0,0 @@
-#!/usr/bin/env python3
-"""Add timestamp indexes to all collections for OrderBy support."""
-
-import asyncio
-import os
-from pathlib import Path
-import sys
-
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from qdrant_client import AsyncQdrantClient
-from qdrant_client.models import PayloadSchemaType, OrderBy
-
-QDRANT_URL = os.getenv("QDRANT_URL", "http://localhost:6333")
-
-async def add_timestamp_indexes():
-    """Add timestamp indexes to all collections that need them."""
-    client = AsyncQdrantClient(url=QDRANT_URL)
-    
-    print("Adding timestamp indexes for temporal query support...")
-    print("="*60)
-    
-    # Get all collections
-    collections = await client.get_collections()
-    total = len(collections.collections)
-    print(f"Found {total} collections")
-    
-    success_count = 0
-    skip_count = 0
-    error_count = 0
-    
-    for i, col in enumerate(collections.collections, 1):
-        col_name = col.name
-        print(f"\n[{i}/{total}] Processing {col_name}...")
-        
-        try:
-            # Check if collection has points
-            info = await client.get_collection(col_name)
-            if info.points_count == 0:
-                print(f"  ⏭️  Skipped (empty collection)")
-                skip_count += 1
-                continue
-            
-            # Check if timestamp field exists
-            points, _ = await client.scroll(
-                collection_name=col_name,
-                limit=1,
-                with_payload=["timestamp"]
-            )
-            
-            if not points or not points[0].payload.get('timestamp'):
-                print(f"  ⏭️  Skipped (no timestamp field)")
-                skip_count += 1
-                continue
-            
-            # Try to use OrderBy to check if index exists
-            try:
-                await client.scroll(
-                    collection_name=col_name,
-                    order_by=OrderBy(key="timestamp", direction="desc"),
-                    limit=1
-                )
-                print(f"  ✅ Already has timestamp index")
-                skip_count += 1
-            except Exception as e:
-                if "No range index" in str(e):
-                    # Need to create index
-                    print(f"  🔧 Creating timestamp index...")
-                    try:
-                        await client.create_payload_index(
-                            collection_name=col_name,
-                            field_name="timestamp",
-                            field_schema=PayloadSchemaType.DATETIME
-                        )
-                        print(f"  ✅ Index created successfully")
-                        success_count += 1
-                    except Exception as create_error:
-                        print(f"  ❌ Failed to create index: {create_error}")
-                        error_count += 1
-                else:
-                    print(f"  ⚠️  Unexpected error: {e}")
-                    error_count += 1
-                    
-        except Exception as e:
-            print(f"  ❌ Error: {e}")
-            error_count += 1
-    
-    print("\n" + "="*60)
-    print("SUMMARY")
-    print("="*60)
-    print(f"✅ Indexes created: {success_count}")
-    print(f"⏭️  Skipped: {skip_count}")
-    print(f"❌ Errors: {error_count}")
-    print(f"📊 Total collections: {total}")
-    
-    # Verify temporal queries work
-    if success_count > 0:
-        print("\n" + "="*60)
-        print("VERIFYING TEMPORAL QUERIES")
-        print("="*60)
-        
-        # Find a collection with data to test
-        test_collection = None
-        for col in collections.collections:
-            try:
-                info = await client.get_collection(col.name)
-                if info.points_count > 100:  # Find one with decent amount of data
-                    test_collection = col.name
-                    break
-            except:
-                pass
-        
-        if test_collection:
-            print(f"Testing on {test_collection}...")
-            try:
-                # Test OrderBy
-                results, _ = await client.scroll(
-                    collection_name=test_collection,
-                    order_by=OrderBy(key="timestamp", direction="desc"),
-                    limit=3,
-                    with_payload=["timestamp", "text"]
-                )
-                
-                print(f"✅ OrderBy works! Found {len(results)} recent conversations:")
-                for r in results:
-                    ts = r.payload.get('timestamp', 'N/A')
-                    text = r.payload.get('text', '')[:60] + '...'
-                    print(f"  - {ts}: {text}")
-                    
-            except Exception as e:
-                print(f"❌ OrderBy test failed: {e}")
-
-if __name__ == "__main__":
-    asyncio.run(add_timestamp_indexes())