Skip to content

v0.3.7 — backup / backups / restore + safer reset

Choose a tag to compare

View all tags
@kooroot kooroot released this 15 Apr 06:45
· 45 commits to main since this release
v0.3.7
0202e71

First-class backup management replaces v0.3.6's ad-hoc `*.bak-` files. Three new commands plus a safer reset flow that asks before deleting irrecoverable data.

Upgrade

bun install -g @kooroot/engram@latest

New commands

`engram backup`

engram backup                         # auto-name (timestamp), keep 5
engram backup --label pre-experiment  # human-readable suffix
engram backup --keep 10               # override retention

What it does:

  • WAL-checkpoints both DBs so the file copy reflects all pending writes
  • Copies `engram.db` + `engram-vec.db` into `~/.engram/backups/_/`
  • Writes `meta.json` with timestamp, label, namespace, row counts, host
  • Auto-prunes oldest beyond `--keep` (default 5; or `ENGRAM_BACKUP_KEEP` env var)

`engram backups`

Lists all backups newest-first with timestamp + row counts. Shows the backup root dir and the active retention setting.

`engram restore [id]`

engram restore                        # interactive picker
engram restore <id-or-label>          # restore specific
engram restore --latest               # restore most recent
engram restore -y                     # skip confirm
engram restore --no-safety-backup     # skip safety net (DANGEROUS)

Always creates a safety backup of the current state (labelled `pre-restore`) before overwriting, so the restore itself is undoable. Closes DB handles, removes `-wal`/`-shm` files, copies the backup over the current DB files.

Reset rewritten

The static `--backup` flag is replaced with an interactive question. Backup is the safe default:

Invocation Behavior
`engram reset` Prompts: "Backup current state before deleting? Yes / No / Cancel"
`engram reset --yes` Skips prompts, defaults to backup ON (safe CI default)
`engram reset --yes --no-backup` Silent, no backup (true CI nuke mode)
`engram reset --no-backup` Asks for confirm only, no backup

When backup is on, reset calls the same backup pipeline with label `pre-reset`, so the deletion is reversible via `engram restore`.

Storage layout

~/.engram/
├── engram.db
├── engram-vec.db
├── engram.env
└── backups/
    ├── 2026-04-15T15-30-00-000Z_pre-reset/
    │   ├── engram.db
    │   ├── engram-vec.db
    │   └── meta.json   (ts, label, namespace, totals, source)
    └── ...

Migration note

Old v0.3.6 `*.bak-` files in `~/.engram/` root are NOT migrated. They remain readable (just SQLite files) but won't appear in `engram backups`. Move them into `backups/` with a hand-written `meta.json`, or delete them.

Verified (live)

  • `engram backup --label X` → folder + meta.json created
  • `engram backups` → entries with totals + retention info
  • `engram reset --yes` → auto-backup as `pre-reset`, then deletes
  • `engram reset --yes --no-backup` → silent, no backup
  • `engram restore --help` → both `--latest` and picker modes shown

Compatibility

  • Node.js ≥ 20
  • Existing 79/79 tests still pass; backup/restore are purely additive
  • Engram config (`engram.env`), MCP registrations, and AI instruction files (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`) are NEVER touched by reset/backup/restore
Assets 2
Loading