longsizhuo/openinvest/invest-backup

Invest Backup Skill

<skill-dir> is this skill's own directory — the folder that holds this SKILL.md (Claude Code

shows it as the skill's base directory; Hermes / Codex / OpenClaw install it inside the plugin).

run.sh below always means <skill-dir>/scripts/run.sh.

Why this skill exists

openInvest's real data (holdings/strategy/user profile/committee records under memory/, trade ledger/job history under db/) is entirely `.gitignore`d — deliberately (privacy: it contains real assets/salary/trades), but the price is that git can't help at all. There was an incident on 2026-07-08: a one-off migration script named migrate_profile.py (with no safety guard whatsoever) was run directly once, overwriting user.md / strategy.md / portfolio.md with hard-coded demo defaults; daily_report then exited early every day because target_assets had become empty, emails stopped entirely from that point on, and the user had no idea until they noticed the missing emails and traced it back.

In any of the following scenarios, proactively use this skill:

• Before running any unfamiliar migration / init / bulk script that writes to memory/ or db/ → backup first
• The user says holdings, strategy, or committee records look wrong / wiped → backup first (even if the current state is already broken, save the "broken state" — otherwise you lose even the diagnostic material), then investigate
• Migrating to a new machine / reinstalling the deployment → backup to package, restore on the new machine

Usage

<skill-dir>/scripts/run.sh backup [output_dir]   # defaults to $INVEST_ROOT/.backups/
<skill-dir>/scripts/run.sh restore <zip_path> [--force]
<skill-dir>/scripts/run.sh list

• backup: packs memory/, db/*.sqlite, db/*.db, .env, user_profile.json* into a single UTC-timestamped zip. The data directory is resolved via openinvest.paths.INVEST_ROOT (same precedence order as the rest of the backend: INVEST_HOME env → repo-marker detection → cwd) instead of re-guessing paths in shell.
• restore: unpacks a zip back into the data directory. By default it refuses to overwrite a `portfolio.md` that already contains real holdings/cash (same criterion as the 2026-05-10 incident defense in lifecycle_cmds.py:_write_v2_portfolio: cash > 0 in any currency, or non-empty holdings, counts as real data) — to confirm the overwrite you must explicitly pass --force. With or without --force, the current state is automatically backed up before restoring, so the operation itself is reversible. Stop the scheduler and any web / MCP process first: running processes hold open SQLite connections and the old -shm for the live databases, and restore overwrites trades.db (and possibly its -wal) underneath them — restoring over a live database is not safe.
• `backup` is safe to run while the scheduler is running (restore is not — see above). It first flushes (checkpoints) the WAL of the SQLite databases into their main files, and any *.db-wal that could not be flushed is packed too — trades that exist only in the write-ahead log are not lost. (Backends older than this behaviour skip the flush with a warning on stderr; the *.db-wal files are still packed.)
• list: lists existing backups, newest first, with sizes — both manual openinvest-backup-*.zip and the backend's daily automatic auto_*.zip (scheduler job backup, 03:30 Asia/Shanghai, keeps the latest 14; no .backtest* on weekdays, Sunday's auto_*_full.zip includes it; restore accepts either).

What is not included

• The memory/.backtest* family of directories (about 240 MB zipped as of 2026-10, ~90% of a full backup). The historical backtest caches in there are regenerable with scripts like scripts/backtest_committee.py, but memory/.backtest/ also holds the forward paper fleet (from 2026-07-24), which cannot be re-run. The manual backup therefore does not exclude them (it means "the entire data directory"). The backend's automatic auto_*.zip leaves them out on weekdays and includes them once a week (Sunday, Asia/Shanghai) as auto_*_full.zip.
• db/*.sqlite-journal, *.db-shm: SQLite runtime temp files — rebuilt automatically after a restore. (*.db-wal is packed: it holds committed writes that have not reached the main file yet; backup checkpoints first so it is normally empty.)
• *.lock: fcntl file locks, cleared automatically on process restart, no need to keep.

Relationship to migrate_profile.py-class incidents

This skill only solves "can it be recovered once lost" — it does not solve "why did it get overwritten". If you see a script in this repo like migrate_profile.py that calls store.write(...) directly with no safety guard, follow the pattern of _write_v2_portfolio in src/openinvest/skill_cmds/lifecycle_cmds.py (check for existing real data before overwriting; on refusal require explicit force=True; auto-backup before overwriting) and retrofit the same guard — that is the real fix; this skill is only the last safety net.