Module identity 

Non-Human Identity (NHI) resolution for agent_id.

Every stored memory carries metadata.agent_id — a best-effort identifier for the agent (AI, human, or system) that wrote it. This module encapsulates the precedence chain and default-id synthesis for all three entry points (CLI, MCP, HTTP) so that the identity format is uniform.

Precedence (CLI / MCP)

1. Explicit id passed by the caller (--agent-id, MCP tool param)
2. AI_MEMORY_AGENT_ID environment variable
3. (MCP only) initialize.clientInfo.name captured at handshake time → ai:<client>@<hostname>:pid-<pid>
4. host:<hostname>:pid-<pid>-<uuid8> — stable per-process
5. anonymous:pid-<pid>-<uuid8> — fallback if hostname is unavailable

Precedence (HTTP)

HTTP serve is multi-tenant; no process-level default is ever cached.

1. Request body agent_id field
2. X-Agent-Id request header
3. Per-request anonymous:req-<uuid8> (emits a WARN log line)

Trust

agent_id is a claimed identity, not an attested one. Do not use it for security decisions without pairing it with agent registration (Task 1.3) and, eventually, signed attestations.

Modules

attest

Store-path agent attestation glue (#626 Layer-3, Task 1.3 / C4).

keypair

Per-agent Ed25519 keypair lifecycle (Track H, Task H1).

replay

H5 (v0.7.0 round-2) — Ed25519 verify-link replay protection.

sentinels

Reserved caller-identity sentinels — the SSOT for every internal / system principal string the substrate compares against, stamps on rows, or carves out of cross-tenant ownership gates (#1558 identity-sentinel remediation).

sign

Outbound Ed25519 signing for memory_links (Track H, Task H2).

verify

Inbound Ed25519 verification for federated memory_links (Track H, Task H3).

Constants

ENV_ANONYMIZE

Environment variable opt-out for the hostname-revealing default (#198). When truthy (1, true, yes, on), the host:<hostname>:pid-... fallback is skipped and anonymous:pid-... is used instead. pub since #1558 so the daemon bootstrap (which maps the config flag onto this env var) shares the spelling. AppConfig::effective_anonymize_default() mirrors the same semantics from the config file, and CLI startup maps config → this env var so the downstream resolution stays env-only.

Functions

anonymous_request_id

Resolve agent_id for a single HTTP request.

preserve_agent_id

Preserve existing.agent_id through update/dedup.

process_discriminator

Returns a stable-for-this-process discriminator of the form <pid>-<uuid8>. Used to make process-level defaults collision-free when many agents share a host (e.g., 25 MCP clients on one machine).

resolve_agent_id

Resolve agent_id for CLI and MCP paths.

resolve_http_agent_id

resolve_read_visibility_caller

v0.7.0 #1468/#1469 — resolve the visibility caller for MCP read paths (memory_session_start / memory_list / memory_search / memory_recall).