Upgrade & backup

Before any upgrade: back up

Your memory is one directory, ~/.tam/ (older installs: ~/.claude-memory/). The important file is ~/.tam/memory.db.

Simple copy (safest): close your AI clients and stop the background services so nothing writes, then copy the directory.

npx -y total-agent-memory dashboard stop     # npx installs; other installs: stop the services your installer added
cp -a ~/.tam ~/tam-backup-$(date +%Y%m%d)

Live copy of the database without stopping anything, with the SQLite command-line tool:

sqlite3 ~/.tam/memory.db ".backup '$HOME/tam-memory-$(date +%Y%m%d).db'"

Portable export: ask the agent to run memory_export. It writes knowledge, sessions and relations as JSON, optionally per project. Use it to move records between machines or keep a human-readable archive; the database copy above is the complete backup.

The clone installer’s ./update.sh also snapshots the database before it changes anything and keeps the last seven snapshots in ~/.tam/backups/.

Upgrade

Installed with	Upgrade command
npx	npx -y total-agent-memory upgrade
Claude Code plugin	update the plugin from Claude Code’s /plugin menu
pipx	pipx upgrade total-agent-memory
pip / uv	pip install -U total-agent-memory
Homebrew	brew upgrade total-memory
Docker	pull the new tag, e.g. docker pull ghcr.io/vbcherepanov/total-agent-memory:14.8.0, and restart with it
Clone + install.sh	cd ~/total-agent-memory && ./update.sh

update.sh checks disk space, snapshots the database, pulls the source, reinstalls dependencies only if they changed, runs the test suite (and stops if it fails), applies migrations and reloads the background services.

After upgrading, restart your client or reconnect the server (Claude Code: /mcp → Reconnect). Database migrations run automatically when the server starts.

To pin a version instead of taking the latest: npx -y total-agent-memory install --server-version 14.8.0, or pip install total-agent-memory==14.8.0.

Restore

1. Close your clients and stop the background services.
2. Move the current directory aside: mv ~/.tam ~/.tam.broken.
3. Copy the backup back: cp -a ~/tam-backup-20260925 ~/.tam (or copy a .db backup to ~/.tam/memory.db).
4. Start your client again.

Restoring an older database into a newer TAM is fine; migrations bring it forward on start. Going back to an older TAM with a database a newer version has migrated is not supported; restore the backup you took before upgrading instead.

Upgrading from 14.7.x to 14.8.0

Nothing to do. There is no migration and no configuration change; the plugin, the hooks, the skill and every tool schema are the same as in 14.7.0.

• Recall changes you will see. The graph tier now fires on stores with a knowledge graph (before, it read only the relations table, which memory_relate alone writes), the multi-representation tier scores every representation row instead of the first 100, and advice-shaped questions (“how should I…”, “recommend…”) also search the project’s convention records and favour the user’s own turns. To compare with the old behaviour, MEMORY_RECALL_TIER_WEIGHTS=graph=0,multi_repr=0,directives=0 MEMORY_RECALL_USER_TURN_BOOST=1.0.
• New, opt-in: MEMORY_LLM_FALLBACK_PROVIDERS (a chain of LLM providers for the enrichment phases), MEMORY_RECALL_TIER_WEIGHTS (the fusion weights; multi_query=0.8 switches on the new multi-query tier, measured neutral and off by default), MEMORY_CROSS_RERANK_WINDOW=100 (1.8 more points of R@10 on LoCoMo at twice the latency on a CPU).
• New, on by default: session_end also saves its summary, next steps and pitfalls as a note record (MEMORY_SESSION_NOTES=off disables it), and the hourly reflection job consolidates idle projects within MEMORY_CONSOLIDATION_BUDGET_SEC (120 s; 0 switches it off).

Upgrading from 14.6.x to 14.7.0

Nothing to do. There is no migration and no configuration change.

• New, opt-in: memory_recall(mode="context", fill_budget=true) fills context_max_chars with whole records instead of excerpts of the top limit hits. It is off by default; other modes are unchanged. See memory_recall.
• Code records saved without the code model. When the code embedding model could not load (offline, or after macOS purged the model cache), earlier versions labelled the record with the code model and semantic search skipped it. 14.7.0 stores such a record in the text space.
• Team server: credential redaction no longer changes UUIDs whose first groups are all digits, so memory_save no longer fails with “request_id: Input should be a valid UUID”.

Upgrading from 14.5.x to 14.6.0

Most installs need nothing. Check these points:

• Existing installs stay personal. On the first start of 14.6.0, an existing install (a memory.db, or a registered memory MCP entry) is recorded as personal mode without a prompt. No behaviour or data changes. A company server is opt-in with tam setup --mode company; see Setup wizard.
• Docker and LAN access. The local dashboard and the MCP HTTP transport now answer only to localhost, 127.0.0.1, [::1] and their configured bind address. Clients that reach them by another name or IP get 421. List those names, comma-separated, in DASHBOARD_ALLOWED_HOSTS and MCP_HTTP_ALLOWED_HOSTS (both are passed through docker-compose.team.yml). See Configuration.
• /healthz on the MCP HTTP port is trimmed to status and version. Monitors that read the memory directory, process ID or session ID from it must stop doing so.
• Scripts moved from bin/ to scripts/ in a clone. Update cron jobs, aliases or CI steps that call bin/memory-bench, bin/memory-perf-gate, bin/cm-import or bin/consolidation-daemon.
• Re-render the consolidation LaunchAgent if you use it. A plist rendered from scripts/com.claude-memory.consolidation.plist before 14.6.0 points at bin/consolidation-daemon, which no longer exists. Render it and load it again.
• Clients registered in the wrong files. Earlier installers wrote some clients’ MCP entry where the client never reads it (Claude Code without the claude CLI or on Windows, Cline, OpenCode, Continue). If the first start logs misplaced config files, run tam setup --reconfigure to register those clients in the right place. Nothing is rewritten silently.
• The npm wrapper 1.9.0 needs server 14.6.0 or later for connect, because it registers clients with tam setup register.
• Move API keys out of client configs. If the first start logs clients that keep an API key in plain text, run tam setup --reconfigure and press Enter at the key prompt. The key moves into the encrypted settings file. Then run tam redact-existing, and add --apply if it finds credentials stored by earlier versions. Keep <memory dir>/master.key with your backups. See Settings page and Privacy.
• Long records are cut in search answers at 6000 characters. Agents that need the whole record call memory_get. Change the limit with MEMORY_RECALL_MAX_RESULT_CHARS or on the Settings page.
• Team server: the dashboard encrypts provider keys with TAM_TEAM_MASTER_KEY or <data dir>/master.key. Back up that key separately; tam-team backup copies the encrypted values but not the key. See The master key.

The full list of changes is in the changelog.

Upgrading from 11.x or older

Every channel moves ~/.claude-memory/ to ~/.tam/ on first run and leaves a symlink, so old scripts keep working. The old command names (claude-total-memory, ctm-lookup) still work as aliases. No manual data move is needed.

Moving to another computer

Copy ~/.tam/memory.db to the same place on the new machine before first use, then install TAM there. If the new machine uses a different embedding model setting, rebuild vectors with memory_rebuild_embeddings.