> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnemom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Identity

> How agents are identified in Mnemom, the ID formats in use, and what you can rely on.

Every agent registered with Mnemom receives a unique, permanent **agent ID** assigned at the time of first registration. This ID is the cryptographic anchor for the agent's reputation, alignment cards, and proof chain.

## ID format

New agents receive IDs in the `mnm-{uuid_v4}` format:

```
mnm-550e8400-e29b-41d4-a716-446655440000
```

This is a standard UUID v4 with the `mnm-` prefix. The UUID provides 128 bits of entropy — zero practical collision risk even at millions of agents.

### Legacy format

Agents registered before April 2026 use the original `smolt-{8_hex}` format:

```
smolt-a4c12709
```

Both formats are permanently valid and fully supported. Existing agents will never have their IDs changed — these IDs are cryptographically committed to proof chains and on-chain anchors.

## How IDs are assigned

Agent IDs are **server-assigned**, not derived from your API key. When you first use an API key with the Mnemom gateway, the gateway registers a new agent and assigns it a UUID. That UUID is returned in the `x-mnemom-agent` response header and stored in your local CLI config.

This means:

* You cannot predict your agent ID before registration
* If you lose your CLI config, re-authenticating with `mnemom login` (or routing a request through the gateway with the same API key) recovers your existing agent ID from the server — the API key hash uniquely identifies your agent
* Two uses of the same API key always get the same agent, regardless of which machine or session

## Finding your agent ID

```bash theme={null}
mnemom status
# Agent: my-agent
# ID:    mnm-550e8400-e29b-41d4-a716-446655440000
```

Or from any gateway response header:

```
x-mnemom-agent: mnm-550e8400-e29b-41d4-a716-446655440000
```

## Stability guarantee

Agent IDs never change. They are:

* Referenced in every alignment card (`agent_id` field)
* Anchored in on-chain Merkle proofs
* Embedded in ZK-STARK attestations
* Used as the stable foreign key across all integrity records

Do not attempt to update or reassign an agent ID. The ID is the agent.

## Using agent IDs in API calls

All agent-specific API endpoints accept both `mnm-*` and `smolt-*` formats interchangeably. The unified agent card has been split into two — `alignment-card` (autonomy, integrity, conscience) and `protection-card` (front-door inspection) — so use the appropriate path for what you want to read:

```bash theme={null}
# New ID format
curl -H "Authorization: Bearer $TOKEN" \
  https://api.mnemom.ai/v1/alignment/agent/mnm-550e8400-e29b-41d4-a716-446655440000

# Legacy ID format (still fully supported)
curl -H "Authorization: Bearer $TOKEN" \
  https://api.mnemom.ai/v1/alignment/agent/smolt-a4c12709
```

See [Card Composition](/concepts/card-composition) for the two-card model.

## Registration

There are two paths to register an agent. Both produce a server-assigned `mnm-{uuid}` ID and the same `agent_hash` derived from your provider API key + agent name. They are interoperable — pick whichever fits your deployment.

### `agent_hash` — the canonical identity hash

Every agent is identified by `agent_hash` — the first 16 hex characters of:

```
agent_hash = SHA256(apiKey + '|' + agentName).slice(0, 16)
```

where `apiKey` is your **provider** API key (Anthropic, OpenAI, or Gemini — whichever you use to call the gateway) and `agentName` is the human-readable name you set via `x-mnemom-agent`. This is what the gateway computes on every request to look up the agent. It's also what you submit as `hash_proof` (full 64-char hex; the API truncates) when registering programmatically — proving you own the API key without transmitting it.

For unnamed agents (singleton — one agent per API key, no `x-mnemom-agent` header), the formula drops the name:

```
agent_hash = SHA256(apiKey).slice(0, 16)
```

The same `apiKey` value you use at registration time **must** be the value sent as `x-api-key` (Anthropic), `Authorization: Bearer` (OpenAI), or `x-goog-api-key` (Gemini) on every gateway call against that agent. Any mismatch makes the agent unaddressable from the gateway.

### Path 1: auto-register on first gateway call (recommended)

The simplest path. Make a normal API call through the gateway with the `x-mnemom-agent` header — the gateway hashes your API key, sees no agent exists, and creates one with a server-assigned `mnm-{uuid}`.

```bash theme={null}
curl https://gateway.mnemom.ai/anthropic/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "x-mnemom-agent: my-agent" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 256, "messages": [{"role": "user", "content": "Hello"}]}'
```

The agent's `mnm-*` ID is returned in the `x-mnemom-agent` response header and persisted on the server. Subsequent calls with the same key + name resolve to the same agent.

<Note>
  A gateway-provisioned agent starts **unclaimed**, in a system holding org (the **Mnemom Sandbox**). It works — the gateway routes calls in `observe` mode — but it has no owner and is not in *your* org yet. **No canonical alignment card is composed for unclaimed agents**, which means durable integrity checkpoints do not accumulate, verdict headers (`X-Mnemom-Verdict`, `X-AIP-Verdict`) reflect fail-open defaults rather than real analysis (not the `unverified` verdict — that requires a canonical card and an attempted-but-failed analysis, neither of which applies here), and AP-Traces are best-effort only. The full integrity pipeline — checkpoints, analytical verdicts, guaranteed AP-Traces — begins after claim. To take ownership and place it in your org, **claim** it (prove you hold its key, choose the org). See [Claiming a gateway-provisioned agent](#claiming-a-gateway-provisioned-agent-into-your-org) below, and [integrity during the unclaimed phase](/guides/agent-claim-flow#between-steps-integrity-during-the-unclaimed-phase) for details.
</Note>

### Path 2: programmatic pre-registration via `POST /v1/agents`

When you need to attach an alignment card or policy before the agent's first call — common for fleet provisioning, CI pipelines, or pre-flight role definition — use the CRUD endpoint.

```bash theme={null}
# Compute hash_proof locally (full 64-char hex; API truncates to agent_hash)
HASH_PROOF=$(printf '%s|%s' "$ANTHROPIC_API_KEY" "my-agent" | shasum -a 256 | awk '{print $1}')

curl -X POST https://api.mnemom.ai/v1/agents \
  -H "Authorization: Bearer $MNEMOM_JWT" \
  -H "content-type: application/json" \
  -d "{
    \"name\": \"my-agent\",
    \"hash_proof\": \"$HASH_PROOF\",
    \"card_json\": { ... }
  }"
```

The handler stores `agent_hash = hash_proof.slice(0, 16)`, binds the agent to your authenticated principal, and places it in your org — registration, ownership, and org placement in one authenticated call. No separate claim step is needed on this path, because you authenticated up front.

The first gateway call against the same key + name will then find this row directly (matching `agent_hash`) and use the card you attached.

### Self-register vs. claim: which one do you need?

There is one question that picks the path — and only one:

> **Are you the agent, or are you adopting a pre-existing one?**

* **You are the agent → self-register with [`POST /v1/agents`](/api-reference/endpoint/post-agents)** (Path 2 above). Your provider key *is* the agent's identity. You create an agent you run yourself; it's owned by you and placed in your org in one authenticated call. No holding pen, no separate claim step — you authenticated up front and the identity derives from your key. (Create doesn't adopt: if an agent with that key+name already exists, this returns `409` — adopting an existing agent is what claim, below, is for.)
* **You are adopting a pre-existing agent → claim it with `POST /v1/agents/{id}/claim`.** The agent already exists with an identity that *isn't* derived from your key — typically because gateway first-traffic auto-provisioned it (Path 1) into the **Mnemom Sandbox** holding org before any authenticated owner existed. You prove possession of its key and place it in your org. This is first-class, not legacy.

These are not old-vs-new ways to do the same thing; they answer different questions. The rest of this section covers claim (adoption).

#### Claiming a gateway-provisioned agent into your org

A gateway-provisioned agent sits **unclaimed, in the Mnemom Sandbox holding org** — there is no authenticated owner yet. `POST /v1/agents/{id}/claim` is how that agent gets an owner and a real org. It is the canonical second half of the gateway-first lifecycle:

```
gateway first-traffic  →  Mnemom Sandbox (unclaimed)  →  claim  →  your org
```

Claim is an **authenticated** call — the principal you authenticate as *becomes the agent's owner*. (Unauthenticated → `401`.) You then prove possession of the agent's key (the same `hash_proof` you'd compute for Path 2) and, optionally, name the org to place it in:

* **Choose an org** — pass `org_id` (an `org-…` or `pers-…` id). You must be a member (`owner`, `admin`, or `member`); claiming into an org you don't belong to is rejected with `403 agent_org_not_member`, whose `details` carry `requested_org_id` and `claimable_orgs` — the orgs you *can* claim into, as `{ org_id, name, is_personal }` objects. An unknown `org_id` returns `400`.
* **Omit `org_id`** — the agent lands in your **personal org**. This default is deliberately the smallest-blast-radius choice: a personal org contains only you, so an accidental claim can never over-share the agent to a team. To place the agent in a shared/company org, you must name it explicitly.

The response reports the **resolved** org so you always know where the agent landed:

```
200 { "claimed": true, "agent_id": "mnm-…", "org_id": "<resolved>", "claimed_at": "…" }
```

Claim is **idempotent for the same owner**: re-claiming an agent you already own returns `200` (the original `claimed_at` is preserved; pass a new `org_id` to re-home it). An agent already owned by *someone else* is **not** adoptable — that returns `403` (holding the proof lets you claim an unowned agent, never steal an owned one). There is no `409` on claim.

<Note>
  Don't know your org IDs? List them with `GET /v1/orgs` (or `mnemom org list`). `GET /v1/me/context` returns your active org plus your full membership list. The claimable subset is echoed in `details.claimable_orgs` when you try to claim into an org you're not a member of.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  # Two different keys are involved:
  #   • the AGENT's provider key (Anthropic/OpenAI/Gemini) → derives hash_proof (proves possession)
  #   • YOUR Mnemom api-key → authenticates you as the claimer (you become the owner)
  # hash_proof = SHA256(providerApiKey + '|' + agentName), full 64-char lowercase hex.
  HASH_PROOF=$(printf '%s|%s' "$AGENT_PROVIDER_KEY" "my-agent" | shasum -a 256 | awk '{print $1}')

  # org_id is optional — omit it to land in your personal org.
  curl -X POST https://api.mnemom.ai/v1/agents/$AGENT_ID/claim \
    -H "X-Mnemom-Api-Key: $MNEMOM_API_KEY" \
    -H "content-type: application/json" \
    -d "{ \"hash_proof\": \"$HASH_PROOF\", \"org_id\": \"org-acme\" }"
  # → 200 { "claimed": true, "agent_id": "mnm-…", "org_id": "org-acme", "claimed_at": "…" }
  ```

  ```typescript TypeScript theme={null}
  import { Mnemom } from "@mnemom/sdk";

  const mnemom = new Mnemom({ apiKey: process.env.MNEMOM_API_KEY });

  const result = await mnemom.agents.claim(agentId, {
    hashProof,          // SHA256(providerApiKey + '|' + agentName), 64-char hex
    orgId: "org-acme",  // optional — omit to land in your personal org
  });
  // result: { claimed: true, agentId: "mnm-…", orgId: "org-acme", claimedAt: "…" }
  // Re-home later by re-claiming with a different orgId.
  ```

  ```bash CLI theme={null}
  # Discover the orgs you can claim into:
  mnemom org list

  # Claim a gateway-provisioned agent into an org. Claim by its mnm-id — an
  # unclaimed agent isn't in your fleet yet, so it can't be resolved by name.
  # --org takes a slug or org_id; omit --org to land in your personal org.
  # Pass --name (the x-mnemom-agent name) so the CLI computes the *named* proof
  # SHA256(key|name); drop --name only for an unnamed singleton agent. Or pass a
  # precomputed --hash-proof <64hex> instead of --key/--name.
  mnemom agents claim <mnm-id> --org acme --key "$AGENT_PROVIDER_KEY" --name my-agent
  # ✓ Claimed mnm-…. Landed in: Acme Corp (acme)
  ```
</CodeGroup>

### When the API key rotates

`agent_hash` is keyed by `apiKey`, so rotating the upstream provider key rotates the identity of every agent registered under it. The supported migration path is:

1. Use [`POST /v1/agents/{id}/rekey`](/api-reference/endpoint/post-agents-agent-id-rekey) to update the agent's `agent_hash` to the value derived from the new key, while preserving the agent's `mnm-*` ID + history.
2. Or — for fleets where the old agents are disposable — tombstone them via [`DELETE /v1/agents/{id}`](/api-reference/endpoint/delete-agents-agent-id) and re-register with the new key.

A robust provisioning flow uses the latter pattern: the provision script detects orphans (existing agents whose `agent_hash` doesn't match the canonical formula under the current key) and tombstones them before re-creating.