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 claim flow

​

When you would use this

1. Your AI assistant integrates Mnemom on your behalf. You authenticate to mnemom.ai, generate a claim token, and your AI assistant uses that token to finalize the agent’s identity binding — without ever holding your password / SSO session.
2. A multi-agent orchestrator stands up agents at scale. The orchestrator’s owner mints claim tokens (one per agent) and hands them to the spawning workflow; each agent self-claims its identity on first start.
3. A regulated team automates onboarding. An admin mints batch tokens (one per onboarding event); the agent registers, claims its identity, and the audit log shows the admin’s delegation rather than the agent’s standalone signup.

​

High-level shape

┌─ Owner (you, authenticated) ─┐
│                              │
│  1. Mint claim token         │
│     POST /v1/claim/tokens    │
│     → { token, expires_at }  │
│                              │
└───┬──────────────────────────┘
    │ hand the token to the
    │ agent through your own
    │ trusted channel
    ▼
┌─ Agent ──────────────────────┐
│                              │
│  2. Initialize identity      │
│     POST /v1/agents          │
│     → { agent_id }           │
│                              │
│  3. Present claim token      │
│     POST /v1/agents/{id}/    │
│          claim               │
│     headers: Authorization:  │
│       Claim-Token <token>    │
│     → { trust_rating, ... }  │
│                              │
└──────────────────────────────┘

​

Step 1 — Owner mints a claim token

POST /v1/claim/tokens HTTP/1.1
Host: api.mnemom.ai
Authorization: Bearer <owner-session-token>
Content-Type: application/json

{
  "scope": "claim-one-agent",
  "expires_in_seconds": 3600,
  "agent_hint": {
    "name": "research-assistant",
    "model": "claude-opus-4-7"
  }
}

{
  "token": "ct_2026Z3...redacted...",
  "expires_at": "2026-05-18T23:00:00Z",
  "scope": "claim-one-agent",
  "owner_user_id": "u_..."
}

• Single-use when scope: "claim-one-agent" (default). Refuses to claim a second identity even if presented twice.
• Short-lived — default 1 hour, capped at 24 hours. The expiry is enforced server-side; client-side checks are advisory.
• Bound to the owner’s user_id at mint time, baked into the signed payload. The agent cannot use a token minted for a different owner.

​

Storage + transport

​

Step 2 — Agent initializes its identity

POST /v1/agents HTTP/1.1
Host: api.mnemom.ai
Content-Type: application/json

{
  "name": "research-assistant",
  "model": "claude-opus-4-7",
  "agent_hash": "<sha256 of public key + identity claim>",
  "alignment_card": { ... }
}

{
  "agent_id": "ag_...",
  "claim_state": "unclaimed",
  "claim_url": "https://www.mnemom.ai/r/<slug>"
}

​

Step 3 — Agent presents the claim token

POST /v1/agents/ag_.../claim HTTP/1.1
Host: api.mnemom.ai
Authorization: Claim-Token ct_2026Z3...redacted...
Content-Type: application/json

{
  "agent_id": "ag_...",
  "hash_proof": "<signature over agent_id + nonce>"
}

1. Verifies the token — signature, expiry, scope, owner_user_id.
2. Verifies hash_proof — the agent signs a nonce derived from agent_id to prove possession of the private key that backs agent_hash.
3. Atomically binds the agent to the owner: agents.claimed_by = <owner_user_id>, agents.claimed_at = <now>, agents.claim_state = 'claimed'.
4. Returns the agent’s initial trust_rating (computed from the alignment card + the platform default cascade — Charter §I13 floor tp-platform-standard), plus identity metadata.

{
  "agent_id": "ag_...",
  "claimed_by": "u_...",
  "claimed_at": "2026-05-18T22:15:00Z",
  "claim_state": "claimed",
  "trust_rating": {
    "composite": 720,
    "grade": "BBB",
    "components": { ... }
  },
  "alignment_card_url": "/v1/agents/ag_.../alignment-card"
}

​

What happens after the claim

1. The /r/<slug> private URL retires. It still exists (for the owner’s audit trail), but is no longer the “unclaimed” share-link surface; the agent’s canonical URL becomes https://www.mnemom.ai/agents/<agent_id> if the owner publishes it.
2. The Trust Directory updates. If the agent is opted into the public directory (alignment_card.publish: true), it appears at /directory and is discoverable by other agents + humans.
3. Audit log records the delegation. The audit row carries both owner_user_id (mint) and agent_id (claim), so a regulator inspecting the trail sees the chain of consent.

​

Why not just OAuth?

1. Single-use is the default. OAuth bearer tokens are designed for repeated calls; the claim token is consumed by exactly one operation, then dies. The OAuth model would require us to add a separate revocation surface for the one-shot case.
2. Audit shape matters. The mint → present sequence creates a typed audit row (owner → agent_id) that a single bearer token can’t. Regulators reviewing agent identity provenance read this audit shape directly, without joining across logs.

​

Common failure modes

​

Related

• agents.txt — the agent-facing pitch for Mnemom; the entry point a competent agent finds first.
• Authentication — the owner-side auth methods (passkey, AAL2, SSO, API keys) that gate the mint endpoint.
• API reference — overview — endpoint docs root; see the Postures + Agents groups for the claim flow’s HTTP surface (POST /v1/agents, POST /v1/agents/{id}/claim).
• Agent-readiness commitment #13 (r-shield) — why /r/<slug> is private and what that means for honest agents.