Problem

Agent UUIDs can change for various reasons — internal errors, edge cases in the lifecycle management, or other circumstances that are not always obvious to the user. When this happens and the agent is re-spawned under a new UUID, all memories, sessions, and conversation history stored under the old UUID become orphaned: the data still exists in the database but is no longer reachable by the agent or the user.

This is silent data loss. The user has no indication that history was lost — the agent simply "forgets" everything, with no warning or recovery path.

Proposed Solution

Introduce a canonical UUID registry that maps agent_name → uuid, persisted independently of agent lifecycle.

Core behavior

1. On first spawn — register agent_name → canonical_uuid in the registry
2. On respawn — look up registry first; if a canonical UUID exists for this name → restore it instead of generating a new one
3. On explicit delete — show a confirmation prompt before removing the registry entry

Confirmation on delete (CLI / API / Telegram)

⚠️  Deleting agent "nika" will permanently remove its canonical UUID
    and all associated memories and sessions.
    This action cannot be undone.

Confirm? [y/N]

Only on explicit confirmation → purge the entry from the registry.

Optional: migration utility

librefang agent merge-history <name> --from <old-uuid>

Reassigns orphaned sessions/memories from a known old UUID to the current canonical one.

Expected Behavior

Why not just rely on config files?

Config files can be regenerated or overwritten. The registry should be a separate, append-only source of truth — similar to how SSH known_hosts or a CA cert store works. Even if the agent config is reset, the identity mapping survives.

Notes

The implementation could be as simple as a agent_identities.toml (or a dedicated DB table) with entries like:

[agents.nika]
canonical_uuid = "660bef7c-04d5-4480-8af2-0ce029981a14"
created_at = "2026-04-01T10:00:00Z"

This is a low-overhead safety net that prevents what is currently a common and frustrating source of data loss for users running long-lived agents.