--- title: "Upgrading" image: "https://recall.edheltzel.codes/og.png" --- > Documentation Index > Fetch the complete documentation index at: https://recall.edheltzel.codes/llms.txt > Use this file to discover all available pages before exploring further. # Upgrading ## Migration note: `recall-*` skills renamed to `do-recall-*` All nine Agent Skills gained a `do-` prefix — `recall-dump` is now `do-recall-dump`, `recall-scout` is now `do-recall-scout`, and so on. Same bodies, same behavior; only the names changed. `install.sh` / `update.sh` remove the retired `recall-*` skill links and canonicals automatically on the next run (and `uninstall.sh` removes both eras). One thing the installer can't reach: **your own files**. If a personal rules file (e.g. `~/.claude/rules/memory.md`) or project doc invokes `/recall-dump` or another old skill name, update it to the `/do-recall-*` form by hand. ## Migration note: `/Recall:*` slash commands → Agent Skills (historical) The `/Recall:*` Claude Code slash commands were retired in favor of [Agent Skills](https://recall.edheltzel.codes/docs/reference/agent-skills/) (issue #228) — same bodies, one namespace across Claude Code, Pi, and omp. `install.sh` / `update.sh` remove the stale `~/.claude/commands/Recall/` symlinks automatically on the next run. If a personal rules file or project doc still references a `/Recall:*` command, update it to the current `/do-recall-*` skill form by hand. ## Adding native omp capture Existing omp skill links do not enable automatic capture. Build and link the native package using [omp Integration](https://recall.edheltzel.codes/docs/integrations/omp/), then restart omp. Existing MCP configuration and skill links stay unchanged. ## Check for a new release From inside Claude Code: ``` /do-recall-update ``` This is a **check-only** command — it prints the current vs. latest version and the exact command to run. It never rebuilds mid-session (that would corrupt hooks tied to the running `recall` binary). From a shell: ```bash cd /path/to/Recall ./packaging/update.sh --check ``` ## Using `update.sh` (recommended) Exit Claude Code first, then: ```bash cd /path/to/Recall ./packaging/update.sh ``` For local-tarball upgrades, follow [Installation → Local tarball](https://recall.edheltzel.codes/docs/installation/#local-tarball). ### First update from an older updater If your installed release predates Claude MCP reconciliation, its already-running updater cannot use lifecycle functions that arrive during its own pull. Complete that first update with: ```bash recall update recall install ``` Run `recall install` once after that first `recall update`. Later updates reload changed lifecycle files before refreshing runtime configuration. `update.sh` performs the full lifecycle: 1. Fetches the latest release tag from GitHub and compares to `package.json`. Exits 0 if already current (unless `--force`). 2. Creates a timestamped [backup](https://recall.edheltzel.codes/docs/installation/#backup-and-restore) and records the git `PRE_SHA` in its manifest. 3. `git fetch --tags origin && git pull --ff-only origin main` (aborts on a dirty tree; resolve manually and re-run). 4. `bun install && bun run build`. 5. Re-links the global binaries. 6. `recall init` applies any pending SQLite migrations (`PRAGMA user_version`-driven, non-destructive). 7. Copies refreshed hooks, shared lib files, agent skills, and `FOR_CLAUDE.md`; reconciles Claude MCP ownership under the [Claude integration rules](https://recall.edheltzel.codes/docs/integrations/claude-code/#migrating-an-existing-install); refreshes detected hosts through the shared installer helpers; and runs the shared Claude/Pi `## MEMORY` ownership migration. Marked sections and normalized exact legacy-generated bodies become syntax-free `Recall_GUIDE.md` pointers; unmarked customized/external sections are preserved, while marked sections remain Recall-owned. A Recall-specific `~/.claude/rules/memory.md` leaves `CLAUDE.md` unchanged. For Pi, refresh means re-registering the native Recall package and separately converging `pi-mcp-adapter`, `mcp.json`, and the guide; it does not create a cross-host bundle. Canonical runtime files refresh in place; a foreign file at a managed host link is moved into the timestamped collision backup before replacement. 8. Renames legacy Claude hook entries, registers missing installer-owned hooks through `recall_register_all_hooks` (existing names are skipped), and removes stale managed hook symlinks. 9. Verifies via `recall --version` and `recall stats`. 10. After verification succeeds, refreshes the managed quarterly aging cron according to [Quarterly aging](https://recall.edheltzel.codes/docs/installation/#quarterly-aging-cron). The OpenCode integration now follows the current OpenCode 1.18.x contract: restart OpenCode after an update so its plugin reloads, then verify `opencode --version` and `opencode export `. Recall normalizes the JSON export; the retired `opencode session export -f markdown -o ...` form is not used. ### Update flags | Flag | Purpose | |------|---------| | `--check` | Version check only; print recipe and exit | | `--dry-run` | Narrate every step with `[dry-run]` markers, touch nothing | | `--force` | Run even if already at latest (repair path) | | `--no-migrate` | Skip `recall init` migration step | | `--no-confirm` | Non-interactive | | `--no-gum` | Skip optional gum setup and use the bash interface for this run | | `--help` | Show usage | ### Rollback If `update.sh` fails at any step, it writes a rollback recipe to `~/.agents/Recall/backups//ROLLBACK.txt` with the exact commands to revert: ``` git reset --hard bun install && bun run build ./packaging/install.sh restore ``` **DB schema downgrades are not supported.** If a migration applied to your DB, reverting the repo alone does not revert the DB. Delete `~/.agents/Recall/recall.db` and restore it from the backup dir if you need to fully roll back. ## Manual update If you prefer to run each step yourself (or `update.sh` is not available on older installs): ```bash cd /path/to/Recall git pull bun install bun run build bun link recall init ``` Then re-run `./packaging/install.sh` to refresh hooks and agent skills — it's idempotent. ## v0.7.22 Migration Notes Purely additive hardening — no schema changes, no user action required. ### Full version in `recall --help` and `recall stats` `DISPLAY_NAME` in `src/version.ts` was truncating the version to `major.minor` (showing "Recall 0.7" for any 0.7.x install). With meaningful patch cadence (0.7.11 → 0.7.2 → 0.7.21 → 0.7.22), the truncation hid which patch was actually running and made triage harder. `recall --help` and `recall stats` now show the full `X.Y.Z`. ### Post-link symlink verification `recall_link_global` (new in `lib/install-lib.sh`) runs `bun link` → **verifies** that `~/.bun/bin/recall` and `recall-mcp` exist, are symlinks, and resolve to readable files → falls back to `npm link` on failure. `install.sh` Step 4 and `update.sh` `step_link_global` both delegate to it. Catches the silent-no-op case where `bun link` exits 0 without refreshing the bin symlinks, which was the root cause of the "I ran `./packaging/update.sh` and then `recall` wasn't executable" class of issue. ## v0.7.21 Migration Notes Purely additive — no schema changes. ### `update.sh` now re-runs `bun link` after rebuild v0.7.2's `update.sh` ran `bun install && bun run build` but never touched the global symlinks in `~/.bun/bin/`. If a prior `bun unlink`, `bun upgrade`, or homedir prune had removed them, rebuild didn't restore them — and the MCP server entry in `settings.json` (which points at `/Users/$USER/.bun/bin/recall-mcp`) failed silently on the next Claude Code / OpenCode / Pi restart. Especially insidious because a long-running `recall-mcp` process holds the deleted inode alive: the current session works, but the next restart drops the inode and MCP breaks with no diagnostic. v0.7.21 runs `step_link_global` between build and migrate. No user action needed — next `./packaging/update.sh` run self-heals. ## v0.7.2 Migration Notes Additive — no schema changes. Introduces the shipping `uninstall.sh` and `update.sh` and the shared `lib/install-lib.sh` library. `install.sh` was refactored (1078 → 225 lines) to source the shared lib; external behavior is identical. See [architecture.md](https://recall.edheltzel.codes/docs/architecture/#lifecycle-scripts-v072) for the lifecycle-script anatomy and [`CHANGELOG.md`](https://github.com/edheltzel/Recall/blob/main/CHANGELOG.md#072--2026-04-19--install-lifecycle) for the full release notes. ## v0.7.11 Migration Notes Hotfix — no user action required. `initDb()` now runs `applyMigrations` before `CREATE_INDEXES`, which fixes `install.sh` crashing for anyone upgrading from a 0.6.x database that still had `PRAGMA user_version = 7`. ## v0.7.0 Migration Notes ### Schema changes (migration 7 → 8) Adds an `importance INTEGER` (1-10) column to `messages`, `decisions`, `learnings`, and `loa_entries`. Non-destructive — existing rows receive the default value (5 for most tables, 8 for LoA with a floor of 5). Runs automatically on `recall init` or `./packaging/install.sh`. ### Recommended: run `recall onboard` post-upgrade v0.7.0 introduces a tiered session-start context (L0 identity + L1 importance-ranked). L0 uses the shared resolver documented under [Identity & Onboarding](https://recall.edheltzel.codes/docs/reference/cli/#identity--onboarding); on a new install its global path is `~/.agents/Recall/MEMORY/identity.md`. If no identity exists, that tier is empty and you're only getting half the v2 design. ```bash recall onboard # Interactive 7-question interview recall benchmark run B # Confirm v2_l0_chars > 0 after onboarding ``` ### New hooks v0.7.0 adds two hooks copied into `~/.claude/hooks/` by the installer: | Hook | Type | Purpose | |------|------|---------| | `RecallStart.ts` | SessionStart | Injects L0 + L1 tiers at session start | | `RecallPreCompact.ts` | PreCompact | Flushes in-flight messages before compaction | If you update hooks manually, copy these alongside `RecallExtract.ts` and `RecallBatchExtract.ts`: ```bash cp hooks/RecallStart.ts ~/.claude/hooks/ cp hooks/RecallPreCompact.ts ~/.claude/hooks/ ``` ### New commands | Command | Purpose | |---------|---------| | `recall onboard` | Interactive L0 identity interview | | `recall importance backfill` | Backfill importance scores from confidence | | `recall pin ` / `recall unpin
` | Manual importance control | | `recall benchmark run/list/report` | Phase 2 benchmark harness | ### New environment variable `RECALL_IDENTITY_PATH` overrides the L0 identity file path. Honored by both `RecallStart` (read) and `recall onboard` (write). ### MCP: `memory_add` accepts `importance` Optional integer 1-10 parameter. Defaults to 5 (or 8 for LoA, with floor 5). --- ## v0.6.0 Migration Notes ### Schema changes (migration 5 → 6) Migration 5→6 adds a `confidence` column (high/medium/low, DEFAULT 'medium') to both the `decisions` and `learnings` tables. This migration is non-destructive — existing rows receive the default value and no data is removed. ### New hooks/lib/ directory v0.6.0 introduces a `hooks/lib/` directory containing shared utilities imported by `RecallExtract.ts` and `RecallBatchExtract.ts`. If you update the hooks manually rather than via `./packaging/install.sh`, you must copy this directory: ```bash cp -r hooks/lib/ ~/.claude/hooks/lib/ ``` Without `hooks/lib/`, the hook scripts will fail to resolve imports at runtime. ### New commands | Command | Purpose | |---------|---------| | `recall decision list` | List decisions with status and confidence | | `recall decision update ` | Update a decision's status (supersede/revert) | | `recall prune` | Preview and remove stale records (dry-run by default; use `--execute` to commit) | ### New MCP tool `decision_update` — update the status and/or confidence of a stored decision. Accepts `id`, `status` (active/superseded/reverted), and optional `confidence` (high/medium/low). --- ## Database Migrations Recall uses SQLite's `PRAGMA user_version` for schema version tracking. When you run `recall init` or `./packaging/install.sh`, the migration system: 1. Reads the current `PRAGMA user_version` from your database 2. Compares it against the expected version in the codebase 3. Applies any pending migrations sequentially 4. Updates `PRAGMA user_version` to the new version Migrations are non-destructive — they add tables and indexes, never drop existing data. ```mermaid graph TD A[git pull] --> B[./packaging/install.sh] B --> C[bun install] C --> D[bun run build] D --> E[bun link] E --> F[recall init] F --> G{PRAGMA user_version} G -->|Current < Expected| H[Apply Migrations] G -->|Current = Expected| I[No Changes Needed] H --> J[Update user_version] J --> K[Done] I --> K style A fill:#3B82F6,color:#fff style H fill:#F59E0B,color:#fff style K fill:#10B981,color:#fff ``` ## Backup and Restore See [Installation → Backup and Restore](https://recall.edheltzel.codes/docs/installation/#backup-and-restore) for snapshot coverage, retention, listing and restoration, and manual database backups. Source: https://recall.edheltzel.codes/docs/upgrading/index.mdx