Context Database Backup & Restore

INSTRUCTIONS FOR CLAUDE: Execute the appropriate backup script command based on arguments.

This command manages GCP Cloud Storage backups for the CODITECT context database.

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Files Backed Up

• org.db (~233MB) - SQLite org database (Tier 2: CRITICAL - decisions, skill_learnings, error_solutions)
• sessions.db (~10GB) - SQLite sessions database (Tier 3: messages, tool_analytics, token_economics)
• context.db (legacy) - Deprecated, kept for backward compatibility
• unified_messages.jsonl (~112MB) - Deduplicated messages
• unified_hashes.json (~5MB) - Hash index
• unified_stats.json - Statistics

GCP Bucket

Location: gs://coditect-cloud-infra-context-backups/coditect-core/ Retention: 90 days automatic cleanup

Usage

Default: Run Backup

# Execute backup script
./scripts/backup-context-db.sh

Check Status

When user includes --status:

./scripts/backup-context-db.sh --status

Restore from Backup

When user includes --restore:

# Restore from specific date
./scripts/backup-context-db.sh --restore YYYY-MM-DD

# Restore latest backup
./scripts/backup-context-db.sh --restore latest

Dry Run (Preview)

When user includes --dry-run:

./scripts/backup-context-db.sh --dry-run

List All Backups

./scripts/backup-context-db.sh --list

Automatic Execution

Execute the appropriate command based on user arguments:

import subprocess
import sys
from pathlib import Path

def find_script():
    """Find backup-context-db.sh from anywhere."""
    script_name = "scripts/backup-context-db.sh"

    candidates = [
        script_name,
        f"submodules/core/coditect-core/{script_name}",
        f".coditect/{script_name}",
        f".claude/{script_name}",
    ]

    cwd = Path.cwd()

    # Check candidates from current directory
    for candidate in candidates:
        if (cwd / candidate).exists():
            return str(cwd / candidate)

    # Walk UP directory tree
    current = cwd
    for _ in range(10):
        for candidate in candidates:
            if (current / candidate).exists():
                return str(current / candidate)
        if current.parent == current:
            break
        current = current.parent

    return script_name

script_path = find_script()

# Build command with arguments
# Parse $ARGUMENTS from slash command invocation
args = "$ARGUMENTS".strip().split() if "$ARGUMENTS".strip() else []

cmd = [script_path] + args
result = subprocess.run(cmd, capture_output=False, text=True)
sys.exit(result.returncode)

Command Examples

# Run backup
/db-backup

# Check backup status
/db-backup --status

# Preview backup without uploading
/db-backup --dry-run

# Restore latest backup
/db-backup --restore latest

# Restore from specific date
/db-backup --restore 2025-12-15

# List all available backups
/db-backup --list

Prerequisites

• gcloud CLI installed and authenticated
• gsutil available (comes with gcloud SDK)
• GCP project with storage permissions

First-Time Setup

If bucket doesn't exist:

./scripts/backup-context-db.sh --setup

This creates the GCP bucket with 90-day lifecycle retention policy.

Output Example

Backup Output

==============================================
  CODITECT Context Database Backup
==============================================

Destination: gs://coditect-cloud-infra-context-backups/coditect-core/2025-12-15/12-09-31
Timestamp:   2025-12-15/12-09-31

Files to backup:
  - org.db (233MB) [TIER 2 CRITICAL]
  - sessions.db (10GB) [TIER 3]
  - unified_messages.jsonl (111.7MB)
  - unified_hashes.json (5.0MB)
  - unified_stats.json (0.0MB)

[INFO] Uploading files...
[OK] Uploaded: org.db
[OK] Uploaded: sessions.db
[OK] Uploaded: unified_messages.jsonl
[OK] Uploaded: unified_hashes.json
[OK] Uploaded: unified_stats.json

[OK] Backup complete!

Backup location: gs://coditect-cloud-infra-context-backups/coditect-core/2025-12-15/12-09-31
To restore: ./scripts/backup-context-db.sh --restore 2025-12-15

Status Output

==============================================
  CODITECT Backup Status
==============================================

Bucket: gs://coditect-cloud-infra-context-backups

Latest backup: 2025-12-15/12-09-31

Recent backups:
  - 2025-12-15
  - 2025-12-14
  - 2025-12-13

Local files:
  - org.db: 233MB (modified: 2026-01-26 07:00) [TIER 2 CRITICAL]
  - sessions.db: 10GB (modified: 2026-01-26 07:00) [TIER 3]
  - unified_messages.jsonl: 111.7MB (modified: 2026-01-26 07:00)

Integration with Hooks

The backup can be triggered automatically after /cx command using the hook:

# hooks/post-cx-backup.sh
# Runs backup after context extraction completes

Troubleshooting

"gcloud CLI not found"

• Install from: https://cloud.google.com/sdk/docs/install

"Not authenticated with gcloud"

• Run: gcloud auth login

"Bucket does not exist"

• Run: ./scripts/backup-context-db.sh --setup

"Permission denied"

• Check GCP IAM permissions for storage access

---

Action Policy

<default_behavior> This command executes immediately with the specified operation:

• No arguments: Runs full backup to GCP
• --status: Shows current backup state
• --restore: Restores from specified backup
• --dry-run: Previews without making changes </default_behavior>

After execution, verify: - Backup: Files uploaded successfully to GCS - Restore: Local files match backup versions - Status: Accurate reporting of backup state

Success Output

When backup operation completes:

✅ COMMAND COMPLETE: /db-backup
Operation: <backup|restore|status>
Destination: gs://coditect-cloud-infra-context-backups/...
Files: N uploaded/restored
Size: X.X MB total
Timestamp: YYYY-MM-DD/HH-MM-SS

Completion Checklist

Before marking complete:

• GCP authenticated
• Files identified
• Operation executed
• Verification passed

Failure Indicators

This command has FAILED if:

• ❌ gcloud not found
• ❌ Authentication failed
• ❌ Bucket not accessible
• ❌ Upload/download failed

When NOT to Use

Do NOT use when:

• No GCP access configured
• Network unavailable
• Files already backed up recently

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip status check	Unknown state	Run --status first
No verification	Corrupt backup	Verify after restore
Ignore errors	Lost data	Check output

Principles

This command embodies:

• #3 Complete Execution - Full backup workflow
• #9 Based on Facts - Verify operations
• #6 Clear, Understandable - Clear output

Full Standard: CODITECT-STANDARD-AUTOMATION.md