Update an existing agent without losing continuity

The safe beta pattern is: inspect the current local and registry state, preserve the current artifacts, make the change, append the new state into AMCS, and then request a new continuity certificate.

1. Check upgrade readiness first

Before changing anything, inspect the current local state and registry expectations.

iap-agent upgrade status --registry-base "https://registry.ia-protocol.com" --project-local --json
iap-agent registry status --registry-base "https://registry.ia-protocol.com" --identity-file ./.iap/identity/ed25519.json --json

If this already shows warnings or stale local state, fix that first.

2. Save the current artifacts

Before the update, preserve the current continuity material and the local state inputs.

Keep the last known-good identity anchor and continuity certificate files.
Back up the AMCS database.
Back up the project-local .iap directory.
Record the package version you are replacing.

3. Apply safe local metadata migrations if needed

If upgrade status shows stale local metadata, preview and then apply the safe migration before continuing.

iap-agent upgrade migrate --project-local --json
iap-agent upgrade migrate --project-local --apply --json

4. Update the package or local configuration

Common examples are package upgrades, prompt changes, host migrations, or tracked file changes.

python -m pip install -U iap-agent

5. Append the updated local state into AMCS

After the update, append the files that now represent the current state. Then confirm the new memory_root and sequence.

iap-agent amcs append --project-local --amcs-db ./amcs.db --file ./AGENT.md --file ./SOUL.md --json
iap-agent amcs root --project-local --amcs-db ./amcs.db --json

6. Issue a new continuity certificate

Once the updated state is in AMCS, certify it as the next point in the chain.

iap-agent continuity request --registry-base "https://registry.ia-protocol.com" --project-local --amcs-db ./amcs.db --json
iap-agent continuity wait --registry-base "https://registry.ia-protocol.com" --request-id <request_id> --timeout-seconds 600 --poll-seconds 5 --json
iap-agent continuity cert --registry-base "https://registry.ia-protocol.com" --request-id <request_id> --output-file ./continuity_record.json --json

7. Verify the new certificate

iap-agent verify ./continuity_record.json --registry-base "https://registry.ia-protocol.com" --json

When to treat the change as a new identity instead

If the signing key changes, if you are intentionally starting a separate agent, or if the existing continuity chain should not be extended, create a fresh project-local identity instead of forcing continuity onto the old agent_id.

If the update fails

Restore the saved AMCS and certificate artifacts, confirm the old certificate still verifies, then use the troubleshooting guide to isolate the exact failure mode.

Open troubleshooting