claude-self-reflect 7.1.9 → 7.1.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-self-reflect",
-  "version": "7.1.9",
+  "version": "7.1.10",
   "description": "Give Claude perfect memory of all your conversations - Installation wizard for Python MCP server",
   "keywords": [
     "claude",
@@ -39,6 +39,7 @@
     "scripts/auto-migrate.cjs",
     "scripts/migrate-to-unified-state.py",
     "scripts/csr-status",
+    "scripts/ralph/**",
     "mcp-server/src/**/*.py",
     "mcp-server/pyproject.toml",
     "mcp-server/run-mcp.sh",

package/scripts/ralph/backup_and_restore.sh

@@ -0,0 +1,309 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Memory Integration - Backup and Restore Script
+# =============================================================================
+# Usage:
+#   ./backup_and_restore.sh backup           # Create full backup
+#   ./backup_and_restore.sh restore <dir>    # Restore from backup directory
+#   ./backup_and_restore.sh verify <dir>     # Verify backup integrity
+#   ./backup_and_restore.sh list             # List available backups
+# =============================================================================
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+BACKUP_BASE="$HOME/.claude-self-reflect/backups"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+
+# =============================================================================
+# BACKUP FUNCTION
+# =============================================================================
+do_backup() {
+    local BACKUP_DIR="$BACKUP_BASE/$(date +%Y%m%d_%H%M%S)_pre_ralph_memory"
+    mkdir -p "$BACKUP_DIR"
+
+    log_info "Creating backup at: $BACKUP_DIR"
+
+    # 1. Stop services for consistent backup
+    log_info "Stopping services for consistent backup..."
+    docker stop claude-reflection-batch-watcher claude-reflection-batch-monitor 2>/dev/null || true
+    sleep 2
+
+    # 2. Backup Qdrant data volume
+    log_info "Backing up Qdrant data volume..."
+    if docker volume inspect qdrant_data > /dev/null 2>&1; then
+        docker run --rm \
+            -v qdrant_data:/data:ro \
+            -v "$BACKUP_DIR":/backup \
+            alpine tar czf /backup/qdrant_data.tar.gz -C /data .
+        log_info "Qdrant backup: $(du -h "$BACKUP_DIR/qdrant_data.tar.gz" | cut -f1)"
+    else
+        log_warn "Qdrant volume not found, skipping"
+    fi
+
+    # 3. Backup CSR config directory
+    log_info "Backing up CSR config..."
+    if [ -d "$HOME/.claude-self-reflect/config" ]; then
+        tar czf "$BACKUP_DIR/csr_config.tar.gz" -C "$HOME/.claude-self-reflect" config
+    else
+        log_warn "CSR config not found, skipping"
+    fi
+
+    # 4. Backup batch queue
+    if [ -d "$HOME/.claude-self-reflect/batch_queue" ]; then
+        tar czf "$BACKUP_DIR/csr_batch_queue.tar.gz" -C "$HOME/.claude-self-reflect" batch_queue
+    fi
+
+    # 5. Backup batch state
+    if [ -d "$HOME/.claude-self-reflect/batch_state" ]; then
+        tar czf "$BACKUP_DIR/csr_batch_state.tar.gz" -C "$HOME/.claude-self-reflect" batch_state
+    fi
+
+    # 6. Save git state
+    log_info "Saving git state..."
+    cd "$PROJECT_ROOT"
+    echo "$(git rev-parse HEAD)" > "$BACKUP_DIR/git_head.txt"
+    echo "$(git branch --show-current)" > "$BACKUP_DIR/git_branch.txt"
+    git diff > "$BACKUP_DIR/git_diff.patch" 2>/dev/null || true
+    git diff --cached > "$BACKUP_DIR/git_staged.patch" 2>/dev/null || true
+
+    # 7. Restart services
+    log_info "Restarting services..."
+    docker start claude-reflection-batch-watcher claude-reflection-batch-monitor 2>/dev/null || true
+
+    # 8. Create manifest
+    cat > "$BACKUP_DIR/manifest.json" << EOF
+{
+    "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+    "git_commit": "$(cat "$BACKUP_DIR/git_head.txt")",
+    "git_branch": "$(cat "$BACKUP_DIR/git_branch.txt")",
+    "qdrant_backup": $([ -f "$BACKUP_DIR/qdrant_data.tar.gz" ] && echo "true" || echo "false"),
+    "config_backup": $([ -f "$BACKUP_DIR/csr_config.tar.gz" ] && echo "true" || echo "false"),
+    "project_root": "$PROJECT_ROOT"
+}
+EOF
+
+    log_info "Backup complete!"
+    echo ""
+    echo "Backup directory: $BACKUP_DIR"
+    echo "Files:"
+    ls -lh "$BACKUP_DIR"
+    echo ""
+    echo "To restore: $0 restore $BACKUP_DIR"
+}
+
+# =============================================================================
+# RESTORE FUNCTION
+# =============================================================================
+do_restore() {
+    local BACKUP_DIR="$1"
+
+    if [ -z "$BACKUP_DIR" ]; then
+        log_error "Usage: $0 restore <backup_directory>"
+        exit 1
+    fi
+
+    if [ ! -d "$BACKUP_DIR" ]; then
+        log_error "Backup directory not found: $BACKUP_DIR"
+        exit 1
+    fi
+
+    if [ ! -f "$BACKUP_DIR/manifest.json" ]; then
+        log_error "Invalid backup: manifest.json not found"
+        exit 1
+    fi
+
+    log_warn "This will restore system state from backup."
+    log_warn "Current changes will be lost!"
+    echo ""
+    read -p "Are you sure? (type 'yes' to confirm): " confirm
+    if [ "$confirm" != "yes" ]; then
+        log_info "Restore cancelled"
+        exit 0
+    fi
+
+    echo ""
+    log_info "Starting restore from: $BACKUP_DIR"
+
+    # 1. Stop all services
+    log_info "Stopping all services..."
+    docker stop claude-reflection-batch-watcher claude-reflection-batch-monitor claude-reflection-qdrant 2>/dev/null || true
+    sleep 3
+
+    # 2. Restore Qdrant data
+    if [ -f "$BACKUP_DIR/qdrant_data.tar.gz" ]; then
+        log_info "Restoring Qdrant data..."
+        docker run --rm \
+            -v qdrant_data:/data \
+            -v "$BACKUP_DIR":/backup \
+            alpine sh -c "rm -rf /data/* && tar xzf /backup/qdrant_data.tar.gz -C /data"
+    fi
+
+    # 3. Restore CSR config
+    if [ -f "$BACKUP_DIR/csr_config.tar.gz" ]; then
+        log_info "Restoring CSR config..."
+        rm -rf "$HOME/.claude-self-reflect/config"
+        tar xzf "$BACKUP_DIR/csr_config.tar.gz" -C "$HOME/.claude-self-reflect/"
+    fi
+
+    # 4. Restore batch queue
+    if [ -f "$BACKUP_DIR/csr_batch_queue.tar.gz" ]; then
+        rm -rf "$HOME/.claude-self-reflect/batch_queue"
+        tar xzf "$BACKUP_DIR/csr_batch_queue.tar.gz" -C "$HOME/.claude-self-reflect/"
+    fi
+
+    # 5. Restore batch state
+    if [ -f "$BACKUP_DIR/csr_batch_state.tar.gz" ]; then
+        rm -rf "$HOME/.claude-self-reflect/batch_state"
+        tar xzf "$BACKUP_DIR/csr_batch_state.tar.gz" -C "$HOME/.claude-self-reflect/"
+    fi
+
+    # 6. Restore git state
+    log_info "Restoring git state..."
+    cd "$PROJECT_ROOT"
+    ORIGINAL_COMMIT=$(cat "$BACKUP_DIR/git_head.txt")
+    git reset --hard "$ORIGINAL_COMMIT"
+
+    # 7. Restart services
+    log_info "Restarting services..."
+    docker start claude-reflection-qdrant 2>/dev/null || true
+    sleep 5
+    docker start claude-reflection-batch-watcher claude-reflection-batch-monitor 2>/dev/null || true
+
+    log_info "Restore complete!"
+    echo ""
+    echo "Verifying services..."
+    docker ps --filter "name=claude" --format "table {{.Names}}\t{{.Status}}"
+}
+
+# =============================================================================
+# VERIFY FUNCTION
+# =============================================================================
+do_verify() {
+    local BACKUP_DIR="$1"
+
+    if [ -z "$BACKUP_DIR" ]; then
+        log_error "Usage: $0 verify <backup_directory>"
+        exit 1
+    fi
+
+    if [ ! -d "$BACKUP_DIR" ]; then
+        log_error "Backup directory not found: $BACKUP_DIR"
+        exit 1
+    fi
+
+    echo "=========================================="
+    echo "Verifying backup: $BACKUP_DIR"
+    echo "=========================================="
+    echo ""
+
+    local ALL_OK=true
+
+    # Check manifest
+    if [ -f "$BACKUP_DIR/manifest.json" ]; then
+        log_info "✓ Manifest found"
+        cat "$BACKUP_DIR/manifest.json" | python3 -m json.tool 2>/dev/null || log_warn "Manifest is not valid JSON"
+    else
+        log_error "✗ Manifest missing"
+        ALL_OK=false
+    fi
+
+    # Check Qdrant backup
+    if [ -f "$BACKUP_DIR/qdrant_data.tar.gz" ]; then
+        local SIZE=$(du -h "$BACKUP_DIR/qdrant_data.tar.gz" | cut -f1)
+        log_info "✓ Qdrant backup ($SIZE)"
+        # Verify tar integrity
+        tar tzf "$BACKUP_DIR/qdrant_data.tar.gz" > /dev/null 2>&1 && log_info "  ✓ Archive integrity OK" || { log_error "  ✗ Archive corrupted"; ALL_OK=false; }
+    else
+        log_warn "✗ Qdrant backup missing"
+    fi
+
+    # Check config backup
+    if [ -f "$BACKUP_DIR/csr_config.tar.gz" ]; then
+        local SIZE=$(du -h "$BACKUP_DIR/csr_config.tar.gz" | cut -f1)
+        log_info "✓ Config backup ($SIZE)"
+    else
+        log_warn "○ Config backup missing (optional)"
+    fi
+
+    # Check git state
+    if [ -f "$BACKUP_DIR/git_head.txt" ]; then
+        log_info "✓ Git state saved: $(cat "$BACKUP_DIR/git_head.txt" | head -c 8)..."
+    else
+        log_error "✗ Git state missing"
+        ALL_OK=false
+    fi
+
+    echo ""
+    if $ALL_OK; then
+        log_info "Backup verification: PASSED"
+    else
+        log_error "Backup verification: FAILED"
+        exit 1
+    fi
+}
+
+# =============================================================================
+# LIST FUNCTION
+# =============================================================================
+do_list() {
+    echo "=========================================="
+    echo "Available Backups"
+    echo "=========================================="
+
+    if [ ! -d "$BACKUP_BASE" ]; then
+        log_info "No backups found at $BACKUP_BASE"
+        exit 0
+    fi
+
+    for dir in "$BACKUP_BASE"/*; do
+        if [ -d "$dir" ] && [ -f "$dir/manifest.json" ]; then
+            local NAME=$(basename "$dir")
+            local CREATED=$(python3 -c "import json; print(json.load(open('$dir/manifest.json'))['created'])" 2>/dev/null || echo "unknown")
+            local SIZE=$(du -sh "$dir" | cut -f1)
+            echo "  $NAME  ($SIZE, created: $CREATED)"
+        fi
+    done
+
+    echo ""
+    echo "To verify: $0 verify <backup_directory>"
+    echo "To restore: $0 restore <backup_directory>"
+}
+
+# =============================================================================
+# MAIN
+# =============================================================================
+case "$1" in
+    backup)
+        do_backup
+        ;;
+    restore)
+        do_restore "$2"
+        ;;
+    verify)
+        do_verify "$2"
+        ;;
+    list)
+        do_list
+        ;;
+    *)
+        echo "Usage: $0 {backup|restore|verify|list}"
+        echo ""
+        echo "Commands:"
+        echo "  backup           Create full backup of Docker volumes and git state"
+        echo "  restore <dir>    Restore from specified backup directory"
+        echo "  verify <dir>     Verify backup integrity"
+        echo "  list             List available backups"
+        exit 1
+        ;;
+esac

package/scripts/ralph/install_hooks.sh

@@ -0,0 +1,244 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Memory Integration - Hook Installation Script
+# =============================================================================
+# Installs Ralph memory hooks into Claude Code's hook system.
+#
+# Usage:
+#   ./install_hooks.sh           # Install hooks
+#   ./install_hooks.sh --check   # Check installation status
+#   ./install_hooks.sh --remove  # Remove hooks
+# =============================================================================
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+CLAUDE_HOOKS_DIR="$HOME/.claude/hooks"
+CLAUDE_SETTINGS="$HOME/.claude/settings.json"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+
+check_installation() {
+    echo "=========================================="
+    echo "Ralph Memory Integration - Status Check"
+    echo "=========================================="
+
+    local all_ok=true
+
+    # Check hooks directory
+    if [ -d "$CLAUDE_HOOKS_DIR" ]; then
+        log_info "✓ Hooks directory exists: $CLAUDE_HOOKS_DIR"
+    else
+        log_warn "○ Hooks directory not found: $CLAUDE_HOOKS_DIR"
+        all_ok=false
+    fi
+
+    # Check for our hooks symlinks or copies
+    if [ -f "$CLAUDE_HOOKS_DIR/ralph-session-start.py" ] || [ -L "$CLAUDE_HOOKS_DIR/ralph-session-start.py" ]; then
+        log_info "✓ SessionStart hook installed"
+    else
+        log_warn "○ SessionStart hook not installed"
+        all_ok=false
+    fi
+
+    if [ -f "$CLAUDE_HOOKS_DIR/ralph-session-end.py" ] || [ -L "$CLAUDE_HOOKS_DIR/ralph-session-end.py" ]; then
+        log_info "✓ SessionEnd hook installed"
+    else
+        log_warn "○ SessionEnd hook not installed"
+        all_ok=false
+    fi
+
+    # Check settings.json for hook configuration
+    if [ -f "$CLAUDE_SETTINGS" ]; then
+        if grep -q "ralph" "$CLAUDE_SETTINGS" 2>/dev/null; then
+            log_info "✓ Settings.json contains Ralph configuration"
+        else
+            log_warn "○ Settings.json does not contain Ralph configuration"
+            all_ok=false
+        fi
+    else
+        log_warn "○ Settings.json not found"
+        all_ok=false
+    fi
+
+    # Check source hooks exist
+    if [ -f "$PROJECT_ROOT/src/runtime/hooks/session_start_hook.py" ]; then
+        log_info "✓ Source hooks available"
+    else
+        log_error "✗ Source hooks missing!"
+        all_ok=false
+    fi
+
+    echo ""
+    if $all_ok; then
+        log_info "All hooks properly installed"
+    else
+        log_warn "Some hooks are missing. Run: $0 to install"
+    fi
+}
+
+install_hooks() {
+    echo "=========================================="
+    echo "Ralph Memory Integration - Installing"
+    echo "=========================================="
+
+    # Create hooks directory if needed
+    mkdir -p "$CLAUDE_HOOKS_DIR"
+    log_info "Created hooks directory: $CLAUDE_HOOKS_DIR"
+
+    # Create symlinks to our hooks
+    ln -sf "$PROJECT_ROOT/src/runtime/hooks/session_start_hook.py" "$CLAUDE_HOOKS_DIR/ralph-session-start.py"
+    ln -sf "$PROJECT_ROOT/src/runtime/hooks/session_end_hook.py" "$CLAUDE_HOOKS_DIR/ralph-session-end.py"
+    log_info "Created hook symlinks"
+
+    # Create or update settings.json with hook configuration
+    if [ ! -f "$CLAUDE_SETTINGS" ]; then
+        echo '{}' > "$CLAUDE_SETTINGS"
+    fi
+
+    # Use Python to safely merge hook configuration
+    python3 << PYTHON
+import json
+from pathlib import Path
+
+settings_path = Path("$CLAUDE_SETTINGS")
+project_root = "$PROJECT_ROOT"
+
+# Load existing settings
+try:
+    settings = json.loads(settings_path.read_text())
+except:
+    settings = {}
+
+# Ensure hooks section exists
+if 'hooks' not in settings:
+    settings['hooks'] = {}
+
+# Add Ralph hooks if not present
+ralph_hooks = {
+    "SessionStart": [{
+        "matcher": "startup|resume",
+        "hooks": [{
+            "type": "command",
+            "command": f"{project_root}/venv/bin/python3 {project_root}/src/runtime/hooks/session_start_hook.py 2>/dev/null || true"
+        }]
+    }],
+    "SessionEnd": [{
+        "hooks": [{
+            "type": "command",
+            "command": f"{project_root}/venv/bin/python3 {project_root}/src/runtime/hooks/session_end_hook.py 2>/dev/null || true"
+        }]
+    }]
+}
+
+# Merge (don't overwrite existing hooks)
+for hook_type, hook_configs in ralph_hooks.items():
+    if hook_type not in settings['hooks']:
+        settings['hooks'][hook_type] = []
+
+    # Check if Ralph hook already exists
+    existing = settings['hooks'][hook_type]
+    ralph_cmd = f"{project_root}/src/runtime/hooks"
+
+    has_ralph = any(
+        ralph_cmd in str(h.get('hooks', []))
+        for h in existing
+    )
+
+    if not has_ralph:
+        settings['hooks'][hook_type].extend(hook_configs)
+        print(f"  Added {hook_type} hook")
+    else:
+        print(f"  {hook_type} hook already exists")
+
+# Write back
+settings_path.write_text(json.dumps(settings, indent=2))
+print("Settings updated successfully")
+PYTHON
+
+    log_info "Hook configuration added to settings.json"
+
+    echo ""
+    log_info "Installation complete!"
+    echo ""
+    echo "To verify: $0 --check"
+    echo ""
+    echo "NOTE: The hooks will activate when:"
+    echo "  1. You start a Ralph loop with /ralph-wiggum:ralph-loop"
+    echo "  2. The hooks detect .claude/ralph-loop.local.md"
+    echo "  3. Session events (start/end) trigger memory operations"
+}
+
+remove_hooks() {
+    echo "=========================================="
+    echo "Ralph Memory Integration - Removing"
+    echo "=========================================="
+
+    # Remove symlinks
+    rm -f "$CLAUDE_HOOKS_DIR/ralph-session-start.py"
+    rm -f "$CLAUDE_HOOKS_DIR/ralph-session-end.py"
+    log_info "Removed hook symlinks"
+
+    # Remove from settings.json
+    if [ -f "$CLAUDE_SETTINGS" ]; then
+        python3 << PYTHON
+import json
+from pathlib import Path
+
+settings_path = Path("$CLAUDE_SETTINGS")
+project_root = "$PROJECT_ROOT"
+
+try:
+    settings = json.loads(settings_path.read_text())
+except:
+    exit(0)
+
+if 'hooks' not in settings:
+    exit(0)
+
+# Remove Ralph-related hooks
+for hook_type in ['SessionStart', 'SessionEnd']:
+    if hook_type in settings['hooks']:
+        settings['hooks'][hook_type] = [
+            h for h in settings['hooks'][hook_type]
+            if project_root not in str(h)
+        ]
+        if not settings['hooks'][hook_type]:
+            del settings['hooks'][hook_type]
+
+if not settings['hooks']:
+    del settings['hooks']
+
+settings_path.write_text(json.dumps(settings, indent=2))
+print("Settings updated")
+PYTHON
+        log_info "Removed hook configuration from settings.json"
+    fi
+
+    echo ""
+    log_info "Removal complete!"
+}
+
+# =============================================================================
+# MAIN
+# =============================================================================
+case "${1:-}" in
+    --check)
+        check_installation
+        ;;
+    --remove)
+        remove_hooks
+        ;;
+    *)
+        install_hooks
+        ;;
+esac

package/scripts/ralph/test_with_rollback.sh

@@ -0,0 +1,195 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Memory Integration - Test Runner with Automatic Rollback
+# =============================================================================
+# Runs all integration tests and automatically rolls back if any fail.
+#
+# Usage:
+#   ./test_with_rollback.sh <backup_directory>
+#
+# Example:
+#   ./test_with_rollback.sh ~/.claude-self-reflect/backups/20260104_120000_pre_ralph_memory
+# =============================================================================
+
+set -e  # Exit on any error
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+BACKUP_DIR="$1"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+
+# Validate backup directory
+if [ -z "$BACKUP_DIR" ]; then
+    echo "Usage: $0 <backup_directory>"
+    echo ""
+    echo "Create a backup first:"
+    echo "  ./backup_and_restore.sh backup"
+    exit 1
+fi
+
+if [ ! -d "$BACKUP_DIR" ]; then
+    log_error "Backup directory not found: $BACKUP_DIR"
+    exit 1
+fi
+
+if [ ! -f "$BACKUP_DIR/manifest.json" ]; then
+    log_error "Invalid backup: manifest.json not found"
+    exit 1
+fi
+
+echo "=========================================="
+echo "Ralph Memory Integration Test Runner"
+echo "=========================================="
+echo "Backup: $BACKUP_DIR"
+echo "Project: $PROJECT_ROOT"
+echo "=========================================="
+echo ""
+
+cd "$PROJECT_ROOT"
+
+# Activate virtual environment if it exists
+if [ -d "$PROJECT_ROOT/venv" ]; then
+    source "$PROJECT_ROOT/venv/bin/activate"
+    log_info "Using venv Python: $(which python)"
+fi
+
+# =============================================================================
+# ROLLBACK FUNCTION
+# =============================================================================
+rollback() {
+    echo ""
+    echo -e "${RED}=========================================="
+    echo "TESTS FAILED - INITIATING AUTOMATIC ROLLBACK"
+    echo "==========================================${NC}"
+    echo ""
+
+    # Use the backup_and_restore script for actual restore
+    "$SCRIPT_DIR/backup_and_restore.sh" restore "$BACKUP_DIR" << EOF
+yes
+EOF
+
+    echo ""
+    log_error "ROLLBACK COMPLETE - System restored to pre-implementation state"
+    exit 1
+}
+
+# Trap errors and rollback
+trap rollback ERR
+
+# =============================================================================
+# RUN TESTS
+# =============================================================================
+
+log_info "Running tests with automatic rollback on failure..."
+echo ""
+
+# Test 1: Check directory structure
+log_info "Test 1: Checking directory structure..."
+[ -d "src/runtime/hooks" ] || { log_error "Missing: src/runtime/hooks/"; exit 1; }
+echo "  ✓ src/runtime/hooks/ exists"
+
+# Test 2: Check ralph_state module
+log_info "Test 2: Testing ralph_state module..."
+python3 -c "
+from src.runtime.hooks.ralph_state import RalphState, load_state, save_state, is_ralph_session
+import tempfile
+from pathlib import Path
+
+# Test create
+state = RalphState.create_new('Test task', 'Test complete')
+assert state.task == 'Test task', 'Task mismatch'
+assert state.iteration == 1, 'Iteration should be 1'
+assert state.session_id.startswith('ralph_'), 'Invalid session ID'
+
+# Test roundtrip
+with tempfile.TemporaryDirectory() as tmpdir:
+    path = Path(tmpdir) / '.ralph_state.md'
+    state.failed_approaches = ['Approach A']
+    state.learnings = ['Learning 1']
+    save_state(state, path)
+
+    loaded = load_state(path)
+    assert loaded.task == state.task, 'Roundtrip failed: task'
+    assert 'Approach A' in loaded.failed_approaches, 'Roundtrip failed: approaches'
+
+print('  ✓ RalphState module working correctly')
+"
+
+# Test 3: SessionStart hook
+log_info "Test 3: Testing session_start_hook..."
+echo '{"session_id": "test123", "source": "startup"}' | timeout 10 python3 src/runtime/hooks/session_start_hook.py 2>&1 || true
+echo "  ✓ session_start_hook exits cleanly"
+
+# Test 4: SessionEnd hook
+log_info "Test 4: Testing session_end_hook..."
+echo '{"session_id": "test123", "reason": "clear"}' | timeout 10 python3 src/runtime/hooks/session_end_hook.py 2>&1 || true
+echo "  ✓ session_end_hook exits cleanly"
+
+# Test 5: PreCompact hook enhancement
+log_info "Test 5: Checking precompact-hook.sh enhancement..."
+if grep -q "RALPH MEMORY INTEGRATION" src/runtime/precompact-hook.sh 2>/dev/null; then
+    echo "  ✓ precompact-hook.sh contains Ralph integration"
+else
+    log_warn "  ○ precompact-hook.sh not yet enhanced (may be pending)"
+fi
+
+# Test 6: Qdrant connectivity
+log_info "Test 6: Checking Qdrant connectivity..."
+curl -sf http://localhost:6333/collections > /dev/null && echo "  ✓ Qdrant accessible" || log_warn "  ○ Qdrant not accessible (may not be required)"
+
+# Test 7: Run pytest unit tests
+log_info "Test 7: Running pytest unit tests..."
+if [ -f "tests/ralph/test_ralph_integration.py" ]; then
+    python -m pytest tests/ralph/test_ralph_integration.py -v --tb=short -k "not Compaction" 2>&1 || { log_error "Pytest unit tests failed"; exit 1; }
+    echo "  ✓ Pytest unit tests passed"
+else
+    log_warn "  ○ Integration tests not yet created"
+fi
+
+# Test 8: Run CRITICAL compaction scenario tests (requires CSR running)
+log_info "Test 8: Running CRITICAL compaction scenario tests..."
+if curl -sf http://localhost:6333/collections > /dev/null 2>&1; then
+    # CSR is available, run compaction tests
+    python -m pytest tests/ralph/test_ralph_integration.py -v --tb=short -k "Compaction" 2>&1 || {
+        log_error "CRITICAL: Compaction scenario tests failed!"
+        log_error "These tests verify the core value proposition:"
+        log_error "  - PreCompact backs up state to CSR"
+        log_error "  - State recovery after compaction"
+        log_error "  - Cross-session memory works"
+        exit 1
+    }
+    echo "  ✓ Compaction scenario tests passed"
+else
+    log_warn "  ○ CSR not available, skipping compaction tests"
+    log_warn "    (Start Qdrant to run: docker start claude-reflection-qdrant)"
+fi
+
+# Test 9: Docker services still healthy
+log_info "Test 9: Checking Docker services..."
+docker ps --filter "name=claude-reflection-qdrant" --format "{{.Status}}" | grep -q "Up" && echo "  ✓ Qdrant container healthy" || log_warn "  ○ Qdrant container not running"
+docker ps --filter "name=claude-reflection-batch-watcher" --format "{{.Status}}" | grep -q "Up" && echo "  ✓ Batch watcher healthy" || log_warn "  ○ Batch watcher not running"
+
+echo ""
+echo -e "${GREEN}=========================================="
+echo "ALL TESTS PASSED"
+echo "==========================================${NC}"
+echo ""
+echo "The implementation is verified and safe."
+echo ""
+echo "Next steps:"
+echo "  1. Review changes:        git diff main"
+echo "  2. Commit:                git add -A && git commit -m 'feat: add Ralph memory integration hooks'"
+echo "  3. Push:                  git push -u origin feat/ralph-csr-integration"
+echo "  4. Create PR:             gh pr create"
+echo ""
+echo "Backup retained at: $BACKUP_DIR"
+echo "(You can delete it after merge: rm -rf $BACKUP_DIR)"