claude-self-reflect 7.1.8 → 7.1.10

package/README.md

@@ -26,7 +26,7 @@ Give Claude perfect memory of all your conversations. Search past discussions in
 
 **100% Local by Default** • **20x Faster** • **Zero Configuration** • **Production Ready**
 
-> **Latest: v7.0 Automated Narratives** - 9.3x better search quality via AI-powered summaries. [Learn more →](#v70-automated-narrative-generation)
+> **Latest: v7.1.9 Cross-Project Iteration Memory** - Ralph loops now share memory across ALL projects automatically. [Learn more →](#ralph-loop-memory-integration-v719)
 
 ## Why This Exists
 
@@ -326,13 +326,13 @@ Claude: [Searches across ALL your projects]
 </details>
 
 <details>
-<summary><b>Ralph Loop Memory Integration (v7.1+)</b></summary>
+<summary><b>Ralph Loop Memory Integration (v7.1.9+)</b></summary>
 
 <div align="center">
 <img src="docs/images/ralph-loop-csr.png" alt="Ralph Loop with CSR Memory - From hamster wheel to upward spiral" width="800"/>
 </div>
 
-Use the [ralph-wiggum plugin](https://github.com/anthropics/claude-code-plugins/tree/main/ralph-wiggum) for long tasks? CSR automatically gives Ralph loops **cross-session memory**:
+Use the [ralph-wiggum plugin](https://github.com/anthropics/claude-code-plugins/tree/main/ralph-wiggum) for long tasks? CSR automatically gives Ralph loops **cross-session AND cross-project memory**:
 
 **Core Features:**
 - **Automatic backup** before context compaction
@@ -340,43 +340,53 @@ Use the [ralph-wiggum plugin](https://github.com/anthropics/claude-code-plugins/
 - **Failed approach tracking** - never repeat the same mistakes
 - **Success pattern learning** - reuse what worked before
 
+**v7.1.9 Cross-Project Iteration Memory (NEW!):**
+- **Global Hook System** - Hooks fire for ALL projects, not just CSR
+- **Stop Hook** - Captures iteration state after every Claude response
+- **PreCompact Hook** - Backs up Ralph state before context compaction
+- **Project Tagging** - Each entry tagged with `project_{name}` for cross-project visibility
+- **Automatic Storage** - No manual protocol needed, hooks capture everything
+
 **v7.1+ Enhanced Features:**
-- **Error Signature Deduplication** - Normalizes errors (removes line numbers, paths, timestamps) to avoid redundant storage
-- **Output Decline Detection** - Circuit breaker pattern that detects >70% drop in output length
-- **Confidence-Based Exit** - 0-100 scoring based on signals (tasks complete, tests passing, no errors)
-- **Anti-Pattern Injection** - "DON'T RETRY THESE" section surfaces failed approaches first
-- **Work Type Tracking** - Categorizes sessions as IMPLEMENTATION/TESTING/DEBUGGING/DOCUMENTATION
-- **Error-Centric Search** - Finds past sessions by error pattern, not just task description
+- **Error Signature Deduplication** - Normalizes errors (removes line numbers, paths, timestamps)
+- **Output Decline Detection** - Circuit breaker pattern detects >70% output drop
+- **Confidence-Based Exit** - 0-100 scoring (tasks complete, tests passing, no errors)
+- **Anti-Pattern Injection** - "DON'T RETRY THESE" surfaces failed approaches first
+- **Work Type Tracking** - IMPLEMENTATION/TESTING/DEBUGGING/DOCUMENTATION
+- **Error-Centric Search** - Find past sessions by error pattern
 
 **Setup (one-time):**
 ```bash
-./scripts/ralph/install_hooks.sh        # Install CSR hooks
+./scripts/ralph/install_hooks.sh        # Install CSR hooks globally
 ./scripts/ralph/install_hooks.sh --check  # Verify installation
 ```
 
 **How it works:**
-1. Start a Ralph loop: `/ralph-wiggum:ralph-loop "Build feature X"`
+1. Start a Ralph loop in ANY project: `/ralph-wiggum:ralph-loop "Build feature X"`
 2. Work naturally - state is tracked in `.claude/ralph-loop.local.md`
-3. When compaction occurs, state is backed up to CSR
-4. New sessions retrieve past learnings from CSR automatically
-5. Anti-patterns and winning strategies are surfaced first
+3. **Stop hook** captures each iteration automatically
+4. **PreCompact hook** backs up state before compaction
+5. All entries stored with project tags for cross-project search
 
-**Files created:**
-- `.ralph_past_sessions.md` - Injected context from past sessions (auto-generated)
+**Cross-Project Example:**
+```bash
+# In project-a: learned Docker fix
+# In project-b: CSR finds it automatically
+reflect_on_past("docker memory issue")
+# Returns: project_a session with Docker solution
+```
 
-**Verified proof (2026-01-04):**
+**Verified proof (2026-01-05):**
 ```
-# Session start hook injects past sessions:
-INFO: Found 2 relevant results:
-  - Anti-patterns: 0
-  - Winning strategies: 0
-  - Similar tasks: 2
-
-# Sessions stored in Qdrant:
-{
-  "tags": ["ralph_session", "outcome_completed"],
-  "timestamp": "2026-01-04T18:13:03.711262+00:00"
-}
+# Hook collection shows cross-project entries:
+Total entries: 23
+
+1. 05:25:06 📦 PreCompact | 📧 emailmon
+2. 05:22:00 🔄 Iteration  | 🔍 claude-self-reflect
+3. 05:13:51 🔄 Iteration  | 📧 emailmon
+
+# Entries include project tags:
+tags: ['__csr_hook_auto__', 'project_emailmon', 'ralph_iteration']
 ```
 
 [Full documentation →](docs/development/ralph-memory-integration.md)

package/mcp-server/src/reflection_tools.py

@@ -8,6 +8,7 @@ from typing import Optional, List, Dict, Any
 from datetime import datetime, timezone
 from pathlib import Path
 import uuid
+from xml.sax.saxutils import escape as xml_escape
 
 from fastmcp import Context
 from pydantic import Field
@@ -207,13 +208,108 @@ Timestamp: {metadata['timestamp']}"""
 <error>Conversation ID '{conversation_id}' not found in any project.</error>
 <suggestion>The conversation may not have been imported yet, or the ID may be incorrect.</suggestion>
 </conversation_file>"""
-            
+
         except Exception as e:
             logger.error(f"Failed to get conversation file: {e}", exc_info=True)
             return f"""<conversation_file>
 <error>Failed to locate conversation: {str(e)}</error>
 </conversation_file>"""
 
+    async def get_session_learnings(
+        self,
+        ctx: Context,
+        session_id: str,
+        limit: int = 50
+    ) -> str:
+        """Get all learnings from a specific Ralph session.
+
+        This enables iteration-level memory: retrieve what was learned
+        in previous iterations of the SAME Ralph loop session.
+        """
+        from qdrant_client import models
+
+        await ctx.debug(f"Getting learnings for session: {session_id}")
+
+        try:
+            # Check runtime preference from environment
+            prefer_local = os.getenv('PREFER_LOCAL_EMBEDDINGS', 'true').lower() == 'true'
+            embedding_type = "local" if prefer_local else "voyage"
+            collection_name = f"reflections_{embedding_type}"
+
+            # Filter by session tag - matches reflections stored with session_{id} tag
+            session_filter = models.Filter(
+                must=[
+                    models.FieldCondition(
+                        key="tags",
+                        match=models.MatchAny(any=[f"session_{session_id}"])
+                    )
+                ]
+            )
+
+            results, _ = await self.qdrant_client.scroll(
+                collection_name=collection_name,
+                scroll_filter=session_filter,
+                limit=limit,
+                with_payload=True,
+            )
+
+            if not results:
+                await ctx.debug(f"No learnings found for session {session_id}")
+                return f"""<session_learnings>
+<session_id>{session_id}</session_id>
+<count>0</count>
+<message>No learnings stored yet for this session. Use store_reflection() with tags=['session_{session_id}', 'iteration_N', 'ralph_iteration'] to store iteration learnings.</message>
+</session_learnings>"""
+
+            # Format results
+            learnings = []
+            for point in results:
+                payload = point.payload or {}
+                tags = payload.get("tags", [])
+                # Extract iteration number from tags if present
+                iteration = "unknown"
+                for tag in tags:
+                    if tag.startswith("iteration_"):
+                        iteration = tag.replace("iteration_", "")
+                        break
+
+                learnings.append({
+                    "content": payload.get("content", ""),
+                    "iteration": iteration,
+                    "timestamp": payload.get("timestamp", ""),
+                    "tags": tags
+                })
+
+            # Sort by timestamp (oldest first for chronological order)
+            learnings.sort(key=lambda x: x.get("timestamp", ""))
+
+            await ctx.debug(f"Found {len(learnings)} learnings for session {session_id}")
+
+            # Format as XML for structured output (escape special chars for safety)
+            learnings_xml = "\n".join([
+                f"""<learning iteration="{xml_escape(str(l['iteration']))}">
+<timestamp>{xml_escape(str(l['timestamp']))}</timestamp>
+<content>{xml_escape(str(l['content']))}</content>
+<tags>{xml_escape(', '.join(str(t) for t in l['tags']))}</tags>
+</learning>"""
+                for l in learnings
+            ])
+
+            return f"""<session_learnings>
+<session_id>{session_id}</session_id>
+<count>{len(learnings)}</count>
+<learnings>
+{learnings_xml}
+</learnings>
+</session_learnings>"""
+
+        except Exception as e:
+            logger.error(f"Failed to get session learnings: {e}", exc_info=True)
+            return f"""<session_learnings>
+<session_id>{session_id}</session_id>
+<error>Failed to retrieve learnings: {str(e)}</error>
+</session_learnings>"""
+
 
 def register_reflection_tools(
     mcp,
@@ -249,5 +345,21 @@ def register_reflection_tools(
         """Get the full JSONL conversation file path for a conversation ID.
         This allows agents to read complete conversations instead of truncated excerpts."""
         return await tools.get_full_conversation(ctx, conversation_id, project)
-    
+
+    @mcp.tool()
+    async def get_session_learnings(
+        ctx: Context,
+        session_id: str = Field(description="Ralph session ID to get learnings from (e.g., 'ralph_20260104_224757_iter1')"),
+        limit: int = Field(default=50, description="Maximum number of learnings to return")
+    ) -> str:
+        """Get all learnings from a specific Ralph session.
+
+        This enables iteration-level memory: retrieve what was learned
+        in previous iterations of the SAME Ralph loop session.
+
+        Use this at the START of each Ralph iteration to see what previous
+        iterations learned. Then use store_reflection() with session tags
+        to save learnings at the END of each iteration."""
+        return await tools.get_session_learnings(ctx, session_id, limit)
+
     logger.info("Reflection tools registered successfully")

package/mcp-server/src/standalone_client.py

@@ -188,13 +188,15 @@ class CSRStandaloneClient:
     def store_reflection(
         self,
         content: str,
-        tags: List[str] = None
+        tags: List[str] = None,
+        collection: str = None
     ) -> str:
         """Store a reflection/insight.
 
         Args:
             content: The reflection content
             tags: Optional tags for categorization
+            collection: Optional custom collection name (for hooks to use separate storage)
 
         Returns:
             ID of stored reflection
@@ -204,7 +206,11 @@ class CSRStandaloneClient:
         embeddings = self._get_embedding_manager()
 
         # Determine collection name
-        collection_name = f"reflections_{'local' if self.prefer_local else 'voyage'}"
+        # Hooks can specify a custom collection to keep their data separate
+        if collection:
+            collection_name = collection
+        else:
+            collection_name = f"reflections_{'local' if self.prefer_local else 'voyage'}"
 
         # Ensure collection exists
         try:
@@ -271,6 +277,66 @@ class CSRStandaloneClient:
         normalized = re.sub(r'_+', '_', normalized)
         return normalized.strip('_')
 
+    def get_session_learnings(
+        self,
+        session_id: str,
+        limit: int = 50,
+        collection: str = None
+    ) -> List[Dict[str, Any]]:
+        """Get all learnings from a specific Ralph session.
+
+        This enables iteration-level memory: retrieve what was learned
+        in previous iterations of the SAME Ralph loop session.
+
+        Args:
+            session_id: The session ID (e.g., "ralph_20260104_224757_iter1")
+            limit: Maximum number of reflections to return
+            collection: Optional custom collection (for hook-stored data)
+
+        Returns:
+            List of reflection payloads from this session, each containing:
+            - content: The reflection text
+            - tags: List of tags (includes iteration info)
+            - timestamp: When it was stored
+        """
+        from qdrant_client import models
+
+        client = self._get_client()
+        if collection:
+            collection_name = collection
+        else:
+            collection_name = f"reflections_{'local' if self.prefer_local else 'voyage'}"
+
+        # Filter by session tag - matches reflections stored with session_{id} tag
+        session_filter = models.Filter(
+            must=[
+                models.FieldCondition(
+                    key="tags",
+                    match=models.MatchAny(any=[f"session_{session_id}"])
+                )
+            ]
+        )
+
+        try:
+            results, _ = client.scroll(
+                collection_name=collection_name,
+                scroll_filter=session_filter,
+                limit=limit,
+                with_payload=True,
+            )
+
+            return [
+                {
+                    "content": point.payload.get("content", ""),
+                    "tags": point.payload.get("tags", []),
+                    "timestamp": point.payload.get("timestamp", ""),
+                }
+                for point in results
+            ]
+        except Exception as e:
+            logger.error(f"Error getting session learnings: {e}")
+            return []
+
     def test_connection(self) -> bool:
         """Test if CSR is accessible.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-self-reflect",
-  "version": "7.1.8",
+  "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