How the AxiOwl Registry Keeps Agent Identity Stable

When one AI session sends a message to another, the easy part is the visible name. The hard part is knowing which live provider session that name means, whether the chat title has changed, whether two sessions share the same title, and where a reply should go. AxiOwl solves that with a local registry that treats provider-owned session identity as the stable key and treats display names as useful, changeable labels.

In the current AxiOwl C++ implementation, the registry is not a loose address book. It is a durable routing model used by the CLI, MCP server, discovery code, and send pipeline. On Windows the agent registry lives under %LOCALAPPDATA%\AxiOwl\registry\agents.tsv; on Linux-style environments the same path logic falls back to $XDG_STATE_HOME/axiowl/registry/agents.tsv or ~/.axiowl/registry/agents.tsv.

Sources read

Source repo: C:\Users\kjhgf\OneDrive\Documents\postfourth\axiowl-cplus

• README.md
• docs/reference/architecture-overview.md
• docs/reference/provider-support-matrix.md
• docs/security/trust-boundaries.md
• docs/providers/codex-agents.md
• docs/providers/vscode-native.md
• docs/providers/remote.md
• apps/windows-desktop/src/app_paths.cpp
• apps/windows-desktop/src/models.hpp
• apps/windows-desktop/src/registry.hpp
• apps/windows-desktop/src/registry.cpp
• apps/windows-desktop/src/discovery.hpp
• apps/windows-desktop/src/discovery.cpp
• apps/windows-desktop/src/discovery_codex.cpp
• apps/windows-desktop/src/discovery_codex_policy.cpp
• apps/windows-desktop/src/discovery_vscode_native.cpp
• apps/windows-desktop/src/message_pipeline.cpp
• apps/windows-desktop/src/mcp_server.cpp
• apps/windows-desktop/src/cli.cpp
• apps/windows-desktop/tests/core_tests.cpp

What A Registry Row Means

An AxiOwl AgentRecord stores the parts needed to route and verify a session:

• display_name, the human-readable chat or agent name.
• aliases, extra names and sender addresses that can resolve to the same row.
• provider, such as codex, codex_cli, vscode_native, vscode_copilot_backed, cursor, or another provider edge.
• provider_session_id, the provider-owned session or thread identifier.
• node_id, normally local, so the same provider session string on another node cannot collide.
• enabled and sendable, which separate known rows from rows AxiOwl is willing to route to.
• source, timestamps, and last_error, which explain where the row came from and whether the latest discovery still trusts it.

The stable identity is the provider, node, and provider session. Discovery builds an internal stable agent id from those pieces: provider plus node id plus provider session id. Merge logic also matches existing discovered rows by the same three fields. That is the important design choice: the label can change, but the session key stays attached to the same provider-owned address.

Names Can Change Without Breaking Identity

Provider sessions often get better names after they are created. A chat might begin as "New Chat", then later become a title derived from the first prompt, a custom title, or a provider-side session file. AxiOwl's merge code is built for that.

When discovery finds the same provider, node, and session again, it updates the existing row instead of creating a duplicate. If the new discovered display name is usable, AxiOwl can promote it to the row's current display_name. The previous name is preserved as an alias, along with a normalized "agent" alias and provider session aliases where applicable.

The tests cover this directly. test_discovery_merge_repairs_existing_session_without_duplicate starts with a row named Old Name, discovers the same session as New Name, and expects one row, the new display name, and the old name preserved as an alias. That is registry stability in practice: the address stays the same while the visible name improves.

Duplicate Names Are Not Treated As One Agent

A second common failure mode is duplicate titles. Two sessions can both be named Same Name. The registry code does not assume that equal names mean equal agents when discovery has a different provider session id.

The registry lookup rules are explicit:

• Exact session matches are preferred over name matches.
• Sendable rows are preferred over enabled-only rows.
• For duplicate names, AxiOwl chooses the newest row using last_seen_at, then last_verified_at, then first_seen_at, with agent_id as a tie-breaker.

The core tests verify both sides. test_registry_find_prefers_newest_duplicate_name_and_exact_session expects a name lookup to choose the newer duplicate, but an exact old session id to still return the old session. test_discovery_merge_duplicate_name_enrolls_new_session expects a new session with the same display name to enroll as a separate row.

That means operators can use readable names most of the time, while session ids still remain available as precise addresses when names collide.

Discovery Repairs The Registry, But Only With Enough Proof

AxiOwl discovery does not blindly turn every hint into a sendable target. A discovered row has its own model: display_name, provider, provider_session_id, node_id, status, sendable, has_enrollment_proof, source, evidence strings, last_seen_at, and last_error.

The merge code skips rows that are missing required identity fields. It also refuses to enroll rows that do not prove sendability. This matters most for local Codex discovery, where the code distinguishes stronger sources from weak evidence:

• codex_desktop_thread_state and targeted desktop IPC owner evidence can enroll a sendable Codex row.
• codex_active_workspace_vscode_thread and SQLite-only evidence can be counted as evidence-only instead of becoming a sendable target.
• A targeted Codex row can become sendable when exact target evidence is combined with live Desktop IPC owner proof.

The tests reflect that policy. An evidence-only Codex row is counted and skipped, while a targeted IPC-owner row enrolls and becomes sendable. Manual rows are also protected: discovery can enrich them with aliases and timestamps, but it should not overwrite the manual display name or downgrade the row.

This is one of the practical reasons AxiOwl identity stays stable. Discovery can repair stale state, but it has to show why a route is safe to use.

Sender Identity Uses The Same Registry Discipline

For replies to work, AxiOwl has to know who sent the message. The sender path uses the registry too.

sender_from_registry_or_explicit receives a sender name or session key plus a node id. It first tries to resolve that value through the registry, scoped to the node. If the value matches a provider session id or a session alias, AxiOwl returns the registered display name for that sender. If the request is a session-looking value and no registry row matches, the sender remains unresolved instead of being treated as a real display name. If the value is plain text and not session-like, it can be used as an explicit sender name.

There are careful fallbacks. If a provider session is known but the display name itself is just the session id, AxiOwl can still resolve it as a registry_session_id_display_fallback. If the display name is a real prompt-like title, such as a Codex title derived from a user request, the code preserves it as the sender name instead of throwing it away as suspicious.

The message pipeline enforces this before delivery. A normal send resolves sender identity first. If a session-like sender is unresolved, the pipeline runs one targeted sender discovery pass and tries again. If the sender is still unresolved, the send is rejected loudly. A final-visible relay body is even stricter: it must carry a resolved sender identity, or AxiOwl rejects it.

MCP Makes Session Identity Provider-Owned

The MCP server is where this becomes especially important. The axiowl_send_message tool description says the host MCP session ID is the stable sender identity key. The server's initialize instructions tell hosts to use typed AxiOwl tools, not raw argv, and not to invent --from manually.

In mcp_server.cpp, AxiOwl resolves identity from provider metadata:

• Antigravity metadata becomes antigravity:cascade:<id> or antigravity_cli:conversation:<id>.
• Cursor metadata becomes cursor:composer:<id> or cursor_cli:session:<id>.
• VS Code native metadata becomes vscode_native:session:<id>.
• Codex metadata can resolve through Codex thread state or an existing Codex CLI registry row.
• Copilot CLI, Claude Code CLI, and OpenCode CLI each have provider-specific session normalization paths.

When the MCP sender has a real display name and session id, AxiOwl registers it through registry add-agent with source=mcp_sender_identity. If the provider gives a separate sender address, that address is added as an alias. If required provider metadata is missing, AxiOwl refuses the send instead of guessing.

That is the core identity rule from the docs and implementation: provider-owned session metadata is the stable sender key. Display names make the route readable, but they are not allowed to replace the provider session identity when reply routing depends on it.

What Happens During A Send

The send flow in MessagePipeline shows how the registry is used at runtime:

1. The request enters AxiOwl and gets a message id and run id.
2. Sender identity is resolved through the registry or final-visible relay metadata.
3. If a session-like sender is missing, AxiOwl runs one targeted sender discovery repair and tries again.
4. The target is resolved from the registry by exact session, display name, or alias.
5. If the target is missing or needs repair, AxiOwl runs one targeted target discovery pass across local providers.
6. If the target is still missing, evidence-only, or not sendable, the send is rejected with a detailed discovery summary.
7. Only after target resolution does AxiOwl return an accepted_by_axiowl receipt and hand the provider request to the delivery worker.

That receipt boundary is intentional. The architecture docs and tests both distinguish AxiOwl accepting a request from the provider accepting, acting on, or replying to it. A stable registry identity gets the message to the right provider route; response-backed proof is still the stronger end-to-end signal.

Why This Helps Operators And Developers

Stable identity removes several day-to-day failure cases:

• A renamed chat does not lose its address.
• An older title can still work as an alias.
• Two chats with the same visible title can still be separated by session id and recency.
• Weak discovery evidence does not silently become a sendable route.
• MCP replies carry provider/session metadata instead of relying on a model to remember its own session id.
• Logs and receipts can say whether AxiOwl accepted the request, whether provider delivery was reported, and which registry row was selected.

The result is a registry that behaves more like a routing table than a contact list. AxiOwl can use friendly names at the edge, but underneath it keeps provider, node, and session identity attached to every route it trusts.

Closing

The AxiOwl registry keeps agent identity stable by separating what humans see from what providers own. Display names, aliases, and discovery evidence can change as sessions move through real tools. The durable route is the provider session on a node, backed by source, sendability, timestamps, and proof-aware discovery. That is what lets AxiOwl send and receive across provider sessions without treating a mutable chat title as the identity itself.

Image prompt:

Create a polished graphic image related to: stable agent registry identity in AxiOwl.

Subject: a precise technical registry cabinet made of brushed metal index cards, each card connected to a central routing hub by thin glowing data lines, with one highlighted locked session-key card and several faded alias cards behind it.
Style: halfway between a clean symbolic icon and a realistic product/technical illustration; professional SaaS/technical marketing style; crisp edges; high detail; no text; no logos.
Background: solid #00ff00 chroma key green screen background covering the full canvas edge to edge.
Restrictions: no owl, no axolotl, no birds, no animals, no mascot, no text, no watermark.