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 (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, 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:

cd /path/to/Recall
./packaging/update.sh --check

Using update.sh (recommended)

Exit Claude Code first, then:

cd /path/to/Recall
./packaging/update.sh

For local-tarball upgrades, follow 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:

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 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; 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.

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 <session-id>. Recall normalizes the JSON export; the retired opencode session export -f markdown -o ... form is not used.

Update flags

Rollback

If update.sh fails at any step, it writes a rollback recipe to ~/.agents/Recall/backups/<TIMESTAMP>/ROLLBACK.txt with the exact commands to revert:

git reset --hard <PRE_SHA>
bun install && bun run build
./packaging/install.sh restore <TIMESTAMP>

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):

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 for the lifecycle-script anatomy and CHANGELOG.md 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; 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.

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:

If you update hooks manually, copy these alongside RecallExtract.ts and RecallBatchExtract.ts:

cp hooks/RecallStart.ts ~/.claude/hooks/
cp hooks/RecallPreCompact.ts ~/.claude/hooks/

New commands

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:

cp -r hooks/lib/ ~/.claude/hooks/lib/

Without hooks/lib/, the hook scripts will fail to resolve imports at runtime.

New commands

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.

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 for snapshot coverage, retention, listing and restoration, and manual database backups.