Updates & Backups

---

title: "Updates & Backups" tier: "2" status: "verified" version: "1.1.165" last-verified: "2026-06-11" commit: "b1c347b1" network-badge: "none" risk-tags:

• "RISK: MEDIUM"
• "RISK: HIGH"

---

💾 Updates & Backups

This page covers backup strategies, hardware recovery, and maintenance procedures for your Tadpole OS local node.

---

1. Directory Structure & Backup Paths

Include the following folders in your regular office backup routine:

Path	Description	Risk if Lost
data/tadpole.db	SQLite database with agent profiles, project logs, and configurations	Critical — all operational data
data/memory.lance/	Local vector databases for document search	Medium — can be re-indexed from source files
.env	Port definitions, API key references, and local path configurations	Critical — contains security-sensitive values
data/workflows/	SOP markdown files for agent enforcement	Medium — recreatable from business documentation
data/skills/	Custom skill manifest JSON files	Medium — skill logic can be reconstructed

Important

The data/memory.lance/ directory is only present when the engine is built with the vector-memory [RISK: MEDIUM] feature flag.

Caution

The .env file contains sensitive credentials. Store backups in an encrypted location and never commit to version control.

---

2. Automatic Hardware Recovery

If your local computer runs low on GPU memory (VRAM) while loading a local Ollama model, the engine automatically:

1. Detects the out-of-memory condition.
2. Intercepts the error and dynamically down-ranks the active model by appending a :q4_K_M quantization suffix.
3. Reroutes the generation request, preserving project progress and resuming the active mission.

This prevents out-of-memory crashes on typical office hardware (8–16 GB VRAM). Quoted in the source code at openai.rs:L336-361 and openai.rs:L596-614.

---

3. Database Maintenance & UI

3.1 SQLite Database

The primary database (data/tadpole.db) stores agent configurations and mission states.

[Command] Backup SQLite Database

copy data\tadpole.db data\tadpole.db.backup

3.2 Vector Database (LanceDB)

The vector database at data/memory.lance/ can be regenerated by re-indexing your workspace files.

[Command] Backup LanceDB Vector Store

xcopy /E /I data\memory.lance data\memory.lance.backup

3.3 Backup User Interface

Monitor and trigger backups via the following dashboard elements:

• [Button] Backup Now

  • Default state: Enabled.
  • Visible location: Bottom actions corner of the Updates & Backups admin panel.
  • Observable side effect: Bundles the SQLite database and environment variables into a zip file, storing it in data/backups/.
  • Keyboard shortcut: None.
  • Missing in build: Always present.

• [Card] Last Backup

  • Default state: Renders timestamp and status of the latest sync.
  • Visible location: Updates & Backups dashboard card.
  • Observable side effect: Updates to green SUCCESS status once file copy completes.
  • Keyboard shortcut: None.
  • Missing in build: Always present.

• [Metric] Backup Size

  • Default state: Shows file size in kilobytes (KB) or megabytes (MB).
  • Visible location: Next to the backup status indicator.
  • Observable side effect: Reflects database size on disk.
  • Keyboard shortcut: None.
  • Missing in build: Always present.

---

4. Update Procedure

4.1 Pulling Latest Changes

[Command] Pull Code & Build Backend

git pull origin main
npm install
cd server-rs
cargo build --release

4.2 Database Migrations

Database schema upgrades are applied deterministically on boot. The engine executes pending migration scripts inside the migrations/ directory on startup using sqlx::migrate!(). No manual CLI command line flags are required.

4.3 Environment Variable Updates

After updates, compare your .env against the latest .env.example:

[Command] Check Env Var Differences

diff .env .env.example

New variables may have been added. See Configuration for the complete reference.

---

5. Legacy JSON Backup Mode

For backward compatibility, the engine supports a legacy JSON backup mode:

• LEGACY_JSON_BACKUP [RISK: MEDIUM] — default false. When enabled, keeps old JSON backup files active alongside the SQLite database.

Tip

This mode is primarily for migration purposes. Disable it once you've confirmed the SQLite database is operating correctly.

---

6. Scheduled Backup Recommendations

Frequency	What to Back Up	Method
Daily	data/tadpole.db	Automated script or Windows Task Scheduler
Weekly	data/memory.lance/, data/workflows/, data/skills/	Folder copy to backup drive
On Change	.env	Manual copy to encrypted storage
Before Updates	Full data/ directory	Complete snapshot before git pull

→ See Configuration for persistence and storage path settings. → See Installation for compilation after updates.

---

Complete Lexicon: For the authoritative technical breakdown, see the main repository GLOSSARY.md. Every [[Glossary#term|term]] link on this page resolves to an entry there.