Skip to Content

Comprehensive Backup/Restore - Agent Handover Summary

Comprehensive Backup/Restore - Agent Handover Summary

Created: 2025-10-16
Prepared By: SAM AI
Requested By: Anthony (User)
Status: Ready for Implementation

🎯 Executive Summary

What: Complete backup/restore system for entire SAM AI ecosystem (65+ models, PostgreSQL graph, ChromaDB vectors)

Why: Current system only backs up 3% of data (configs/metadata). User needs ONE backup file that contains EVERYTHING and is 100% restorable.

How: ZIP bundle containing Excel export of all Odoo models + PostgreSQL dump + ChromaDB directory

Who Should Implement:
- Primary: /developer agent (implementation)
- Review: /cto agent (infrastructure validation)
- Testing: /qa-guardian agent
- Docs: /docs agent

📄 Complete Specification Location

Full Technical Spec: COMPREHENSIVE_BACKUP_RESTORE_SPEC.md

This file contains:
- Complete model inventory (65+ models categorized)
- Export workflow (10 steps with code samples)
- Import workflow (8 steps with code samples)
- Safety mechanisms (version check, rollback, dry-run)
- ZIP bundle structure
- Implementation checklist
- Testing requirements
- Success criteria

🔑 Key Requirements (TL;DR)

Export System

New Method: ai_brain/models/ai_memory_config.py::action_export_complete_backup()

What it does:
1. Exports ALL 65 Odoo models to multi-sheet Excel
2. Runs pg_dump to export PostgreSQL graph database
3. Copies and zips ChromaDB directory
4. Creates metadata JSON with versions/counts
5. Bundles everything into single ZIP file
6. Returns download link to user

Result: sam_ai_complete_backup_20250116_143022.zip (single file, fully restorable)

Import System

Enhanced Method: ai_brain/models/ai_memory_import_wizard.py::action_import_complete_backup()

What it does:
1. User uploads ZIP file
2. Extracts and validates metadata
3. Checks version compatibility
4. Imports Odoo models (in dependency order)
5. Restores PostgreSQL graph database
6. Restores ChromaDB vector embeddings
7. Verifies data integrity
8. Shows detailed results

Result: Complete SAM AI system restored from backup

🏗️ ZIP Bundle Structure

sam_ai_complete_backup_20250116_143022.zip
│
├── metadata.json                     # Versions, counts, checksums
├── restore_instructions.md           # Human guide
│
├── odoo_data/
│   ├── ai_brain_backup.xlsx         # ALL 65 models (multi-sheet)
│   └── model_list.json              # Model inventory
│
├── databases/
│   ├── postgres_graph_dump.sql      # Apache AGE graph
│   └── chroma_data.zip              # Vector embeddings
│
└── logs/
    └── export_log.txt               # Export process log

📊 Data Scope

Currently Backed Up (3%)

  • ✅ Memory configs
  • ✅ Conversation import records
  • ✅ Extractor plugins

Will Be Backed Up (100%)

  • ✅ ALL 65 Odoo models (conversations, messages, workflows, nodes, SAM personality, user profiles, etc.)
  • ✅ PostgreSQL graph database (Apache AGE)
  • ✅ ChromaDB vector embeddings (full directory)

See specification for complete model list (9 categories, 65+ models)

🛠️ Technical Dependencies

Required Tools

  • Python libraries:
  • xlsxwriter (already installed)
  • openpyxl (already installed)
  • subprocess (stdlib)
  • shutil (stdlib)
  • zipfile (stdlib)

  • json (stdlib)

  • PostgreSQL client tools:

  • pg_dump (for export)
  • psql (for import)
  • Action Required: Verify installed on server

Required Access

  • PostgreSQL database credentials (from ai.memory.config)
  • ChromaDB persist directory (read/write access)
  • Temp directory space (2-3x data size)

⚠️ Critical Infrastructure Questions

FOR /cto AGENT TO ANSWER BEFORE IMPLEMENTATION:

  1. ✅ Are PostgreSQL client tools (pg_dump, psql) installed?
  2. ✅ What PostgreSQL version is running?
  3. ✅ Where is ChromaDB persist directory? (default: ./chroma_data)
  4. ✅ How much disk space available for temp files?
  5. ✅ What's current size of PostgreSQL database?
  6. ✅ What's current size of ChromaDB directory?
  7. ⚠️ Should backup ZIP be encrypted?
  8. ⚠️ Should sensitive credentials be included in backup?
  9. ✅ Where should long-term backups be stored?
  10. ✅ What's acceptable export/import time? (current estimate: 5-10 min export, 10-15 min import)

🎯 Implementation Phases

Phase 1: Export System (Day 1-2)

File: ai_brain/models/ai_memory_config.py

Tasks:
- [ ] Implement _export_all_odoo_models() - Export 65 models to Excel
- [ ] Implement _export_postgres_graph() - Run pg_dump
- [ ] Implement _export_chroma_data() - Copy ChromaDB directory
- [ ] Implement _generate_metadata() - Create metadata JSON
- [ ] Implement _create_zip_bundle() - Bundle everything
- [ ] Add error handling and logging
- [ ] Test on small dataset
- [ ] Test on production-size dataset

Phase 2: Import System (Day 2-3)

File: ai_brain/models/ai_memory_import_wizard.py

Tasks:
- [ ] Implement _import_all_odoo_models() - Import from Excel
- [ ] Implement _import_postgres_graph() - Run psql restore
- [ ] Implement _import_chroma_data() - Unzip ChromaDB
- [ ] Implement version compatibility check
- [ ] Implement dry-run mode (preview before import)
- [ ] Implement rollback on failure
- [ ] Add progress tracking
- [ ] Test on fresh database
- [ ] Test on existing database (merge mode)

Phase 3: Testing & Documentation (Day 3)

Files: Test suite + user docs

Tasks:
- [ ] Test export/import roundtrip (data integrity)
- [ ] Test version mismatch scenarios
- [ ] Test failure scenarios (disk space, connection errors)
- [ ] Create user guide (how to backup/restore)
- [ ] Create troubleshooting guide
- [ ] Create video walkthrough (optional)

✅ Success Criteria

Export:
- ✅ Single ZIP file contains 100% of data
- ✅ Export completes in < 10 minutes
- ✅ ZIP is compressed (< 1GB for typical dataset)
- ✅ No data loss
- ✅ Clear error messages on failure

Import:
- ✅ Restore completes in < 15 minutes
- ✅ 100% data restored (verified by record counts)
- ✅ All relationships intact (Many2one, One2many)
- ✅ PostgreSQL graph intact
- ✅ ChromaDB vectors intact
- ✅ Version mismatch handled gracefully
- ✅ Rollback works on any failure

🔒 Safety Mechanisms

1. Version Compatibility Check

  • Validates Odoo version match
  • Validates module version compatibility
  • Warns on version mismatches
  • Blocks incompatible backups

2. Dry-Run Mode

  • User can preview import without changes
  • Shows what WOULD be imported
  • Shows record counts
  • Shows version compatibility

3. Rollback on Failure

  • Database savepoint before import
  • Automatic rollback if any critical step fails
  • No partial imports (all-or-nothing)

4. Data Integrity Verification

  • Compares record counts (backup vs imported)
  • Verifies relationships
  • Checks for missing data

🚨 Known Risks & Mitigation

Risk Mitigation
Export timeout (large dataset) Add progress tracking, chunking
Disk space exhaustion Check available space before export
PostgreSQL connection failure Test connection first, clear error messages
Version incompatibility Add version check and migration logic
Corrupted ZIP Add checksum verification
Partial restore failure Implement rollback mechanism

Primary Implementation: /developer

Why:
- Expert in Odoo model operations
- Familiar with ai_brain architecture
- Can implement complex workflows
- Can handle error cases

What they need:
- This handover document
- Full technical spec
- Infrastructure answers from /cto
- Testing checklist

Infrastructure Review: /cto

Why:
- Understands server infrastructure
- Can verify PostgreSQL access
- Can validate disk space requirements
- Can answer security questions

What they need:
- Infrastructure questions section from spec
- Current system stats (DB sizes, disk space)

Quality Assurance: /qa-guardian

Why:
- Can create comprehensive test suite
- Can test edge cases
- Can verify data integrity

What they need:
- Implementation from /developer
- Test scenarios from spec

Documentation: /docs

Why:
- Can create user-friendly guides
- Can maintain ecosystem documentation

What they need:
- Working implementation
- Testing results

🎯 Next Steps (Your Action)

Option A: Start with /cto Review (RECOMMENDED)

/cto Please review the infrastructure questions in
C:\Working With AI\ai_sam\ai_sam\ai_brain\docs\COMPREHENSIVE_BACKUP_RESTORE_SPEC.md

Specifically:
1. Verify PostgreSQL client tools installed
2. Check disk space availability
3. Validate ChromaDB access
4. Answer security questions
5. Provide system stats (DB sizes)

Option B: Start with /developer Implementation

/developer Please implement comprehensive backup/restore system.

Specification: C:\Working With AI\ai_sam\ai_sam\ai_brain\docs\COMPREHENSIVE_BACKUP_RESTORE_SPEC.md
Handover: C:\Working With AI\ai_sam\ai_sam\ai_brain\docs\BACKUP_RESTORE_HANDOVER.md

Start with Phase 1 (Export System).

Option C: Ask SAM AI for Clarification
If you need any part of this explained or modified, just ask!

  1. Technical Specification (complete implementation guide):

  2. COMPREHENSIVE_BACKUP_RESTORE_SPEC.md

  3. Current Export Code (partial implementation):

  4. ai_memory_config.py (lines 169-360)

  5. Current Import Code (partial implementation):

  6. ai_memory_import_wizard.py

  7. Current Uninstall Wizard (reference):

  8. ai_memory_uninstall_wizard.py

⏱️ Estimated Timeline

If /developer starts today:
- Day 1: Implement export system (Phase 1)
- Day 2: Implement import system (Phase 2)
- Day 3: Testing and documentation (Phase 3)

Total: 2-3 days to production-ready

If infrastructure review needed first:
- Day 0: /cto answers infrastructure questions
- Day 1-3: Implementation as above

🎉 What You'll Get

When this is complete, you'll have:

  1. One button: "📥 Export Complete Backup"
  2. Downloads: sam_ai_complete_backup_20250116_143022.zip

  3. Contains: EVERYTHING (65 models + PostgreSQL + ChromaDB)

  4. One button: "📤 Import Previous Backup"

  5. Uploads: ZIP file

  6. Restores: EVERYTHING (100% restoration)

  7. Zero data loss:

  8. Every conversation, message, workflow, node, personality
  9. Every graph node, vector embedding

  10. Every configuration, credential, user profile

  11. Peace of mind:

  12. Uninstall modules without fear
  13. Migrate to new server easily
  14. Disaster recovery ready
  15. Development/staging sync easy

Ready to hand off? 🚀

Choose your next step (Option A, B, or C above) and let's get this implemented!

End of Handover Document ✅

Was this helpful?