Skip to main content

​
Agent identity

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

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: 
# New ID format
curl https://api.mnemom.ai/v1/alignment/agent/mnm-550e8400-e29b-41d4-a716-446655440000

# Legacy ID format (still fully supported)
curl https://api.mnemom.ai/v1/alignment/agent/smolt-a4c12709
See 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. 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}. 
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.
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, 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 below, and integrity during the unclaimed phase for details.

​
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. 
# 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 (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.
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.
# 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": "…" }

​
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 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} 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.