---
title: "Updates & Backups"
tier: "2"
status: "verified"
version: "1.2.0"
last-verified: "2026-06-17"
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](https://github.com/DDS-Solutions/Tadpole-OS/blob/main/server-rs/src/agent/openai.rs#L336-L361) and [openai.rs:L596-614](https://github.com/DDS-Solutions/Tadpole-OS/blob/main/server-rs/src/agent/openai.rs#L596-L614).

---

## 3. Database Maintenance & UI

### 3.1 SQLite Database

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

**[Command] Backup SQLite Database**
```powershell
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**
```powershell
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**
```powershell
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**
```powershell
diff .env .env.example
```

New variables may have been added. See [[Configuration|§1]] 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|§5]] for persistence and storage path settings.*
→ *See [[Installation|§3]] for compilation after updates.*

---

**Complete Lexicon**: For the authoritative technical breakdown, see the main repository [`GLOSSARY.md`](https://github.com/DDS-Solutions/Tadpole-OS/blob/main/docs/GLOSSARY.md). Every `[[Glossary#term|term]]` link on this page resolves to an entry there.

<!-- Last verified against commit b1c347b1 on 2026-06-11 -->
[//]: # (wiki-page: Updates-&-Backups)


[//]: # (Metadata: [wiki-admin])
