> ## 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.

# Mnemom Gateway Quickstart

> Complete agent governance — verification, integrity analysis, and policy enforcement — in 5 minutes with zero code changes

The Mnemom Gateway is a transparent AI gateway that sits between your application and any LLM provider. It provides the full Mnemom trust stack out of the box:

* Verifiable [AP-Traces](/concepts/ap-traces)
* Per-turn [AIP integrity checks](/concepts/integrity-checkpoints)
* Policy enforcement from the alignment card's `capabilities` and `enforcement` sections
* [Safe House](/concepts/safe-house) protection configured via the [protection card](/concepts/protection-card)
* Verification against the agent's [alignment card](/concepts/agent-cards)

Your prompts and responses pass through unchanged. Your API keys never leave your machine.

<Note>
  These quickstarts are available in [Spanish (Español)](/es/quickstart/overview) and [French (Français)](/fr/quickstart/overview) — six pages per language have been translated.
</Note>

<Tip>
  Looking to launch a **governed coding agent** instead of wiring up your own application's API calls? See [`mnemom agent`](/gateway/agent) — install once, run `mnemom agent`, and it launches Claude Code through the gateway with an agent set up for you. `mnemom agent` is available by invitation only.
</Tip>

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g @mnemom/mnemom
    ```
  </Step>

  <Step title="Authenticate">
    Log in to your Mnemom account:

    ```bash theme={null}
    mnemom login
    ```

    This opens a browser-based login flow and stores your auth token in `~/.mnemom/auth.json`. On a machine with no local browser (SSH, a container), use `mnemom login --no-browser` instead — see [CLI Reference](/gateway/cli#authentication).

    <Note>
      Your provider API keys are **not** sent to Mnemom. Only SHA-256 hashes are used to identify your agent. The hash cannot be reversed to recover your key.
    </Note>
  </Step>

  <Step title="Make an API call">
    Use the gateway URL instead of the provider's direct URL. Include the `x-mnemom-agent` header to name your agent — it will be auto-created on first call in the Mnemom Sandbox with no owner. Before the read commands (`mnemom status`, `logs`, `integrity`, `card show`) can resolve it, you must claim the agent to your account (next step). Use `-i` to print response headers so you can capture the `X-Mnemom-Agent` id you'll need for the claim.

    ```bash theme={null}
    # Instead of https://api.anthropic.com/v1/messages
    curl -i 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": 1024,
        "messages": [{"role": "user", "content": "Hello"}]
      }'
    ```

    The same call against OpenAI uses the `/openai` path and the `Authorization: Bearer` header:

    ```bash theme={null}
    # Instead of https://api.openai.com/v1/chat/completions
    curl -i https://gateway.mnemom.ai/openai/v1/chat/completions \
      -H "Authorization: Bearer $OPENAI_API_KEY" \
      -H "x-mnemom-agent: my-agent" \
      -H "content-type: application/json" \
      -d '{
        "model": "gpt-5",
        "messages": [{"role": "user", "content": "Hello"}]
      }'
    ```

    And against Gemini, the `/gemini` path with the `x-goog-api-key` header:

    ```bash theme={null}
    # Instead of https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent
    curl -i https://gateway.mnemom.ai/gemini/v1beta/models/gemini-2.5-flash:generateContent \
      -H "x-goog-api-key: $GEMINI_API_KEY" \
      -H "x-mnemom-agent: my-agent" \
      -H "content-type: application/json" \
      -d '{
        "contents": [{"parts": [{"text": "Hello"}]}]
      }'
    ```

    The gateway supports all three providers at their standard paths:

    | Provider | Gateway Path | Direct Equivalent |
    | - | - | - |
    | Anthropic | `gateway.mnemom.ai/anthropic/*` | `api.anthropic.com/*` |
    | OpenAI | `gateway.mnemom.ai/openai/*` | `api.openai.com/*` |
    | Gemini | `gateway.mnemom.ai/gemini/*` | `generativelanguage.googleapis.com/*` |

    <Tip>
      Most SDKs and frameworks let you override the base URL. Set it to the gateway path for your provider and everything else works unchanged.
    </Tip>
  </Step>

  <Step title="What you'll want to read on the way back">
    The gateway adds response headers that carry the Safe House verdict, support-correlation metadata, and advisory entries. A compliant integration should parse and observe these — at minimum surface them when something goes wrong.

    | Header | When emitted | What to do with it |
    | - | - | - |
    | `X-Mnemom-Request-Id` | Always | UUIDv4 per request. **Always log this.** Paste into a support ticket and we can pull every log line for the request. |
    | `X-Mnemom-Verdict` | Always (gateway), except on an early-committed long non-streaming response (see the note below) | Structured `front=…; autonomy=…; integrity=…; back=…` with each value in `{pass \| observed \| nudged \| enforced \| unverified}`. Parse it; the four-checkpoint state tells you what Safe House observed (front+back), what CLPI did on tool calls (autonomy), and what AIP did on reasoning (integrity). `front` is a rollup over every inbound surface the request carried — the message *and* each tool result screened inside that same request — so `front=enforced` on a `200` means a tool result was withheld or decorated before the model saw it. See [When the front door runs](/concepts/safe-house#when-the-front-door-runs). `unverified` is integrity-only: the analyzer failed, so no trustworthy verdict exists — `enforce` withholds the response (fail-closed, still 2xx), `observe`/`nudge` forward it and record the unverified state. Never reported as `pass`. |
    | `X-Mnemom-Advisory` | When the gateway has advisories | Compact JSON `[{source, text, severity?, id?}, …]`. Surface entries to your operator UI / logs. Omitted entirely when empty. |
    | `X-Mnemom-Agent` | When the request is bound to a named agent | The agent identifier the gateway resolved your request to (e.g., `mnm-a1b2c3d4…`). Useful for cross-referencing dashboard rows. |
    | `X-Mnemom-Session` | On multi-turn sessions | Stable session correlation token. Echo it back on the next turn to maintain session continuity. |
    | `Retry-After` | On `429` and some `503` | Seconds to wait before retrying. **Honor it.** |
    | `X-Mnemom-Effective-Mode` | Only when a turn ran in a different mode than the one configured | Today one value: `passthrough; reason=balance_depleted; configured=enforce` — an `enforce` agent's µ balance was depleted, so the turn was forwarded without Trust OS checks. The `X-AIP-Verdict: clear` / `integrity=pass` on such a response does **not** mean the turn was checked. Top up to restore enforcement. |
    | `X-Mnemom-Deferred` | On a long non-streaming response the gateway committed early | See the note below. |

    <Note>
      A non-streaming request to `/anthropic/v1/messages`, `/openai/v1/chat/completions` or `/openai/v1/responses` that is still running after about 75 seconds is committed early: the gateway sends a `200` whose body starts with newline keepalive bytes, then the final JSON (leading whitespace is valid JSON, so JSON clients parse it unchanged). On such a response `X-AIP-Verdict` is `pending`, `X-Mnemom-Verdict` and `X-Policy-Verdict` are **absent** (never read their absence as a pass), and `X-Mnemom-Deferred` names what the early headers could not carry. An error after the commit closes the connection mid-body — a transport error your SDK can retry — rather than an error body inside the `200`.
    </Note>

    Quick parse:

    ```typescript theme={null}
    const v = response.headers.get('X-Mnemom-Verdict')!;
    const checkpoints = Object.fromEntries(v.split(';').map(s => s.trim().split('=')));
    // checkpoints.front, checkpoints.autonomy, checkpoints.integrity, checkpoints.back

    if (checkpoints.integrity === 'enforced') {
      // Same-turn AIP replacement happened — surface that in your UI.
    }
    if (checkpoints.integrity === 'unverified') {
      // Analyzer failed — no trustworthy verdict. In enforce this response
      // was already withheld/replaced; in observe/nudge it was forwarded.
    }
    ```

    See the [Headers reference](/api-reference/headers) for the full canonical set + per-language parsers, and the [Errors reference](/api-reference/errors) for the verdict-to-status mapping.
  </Step>

  <Step title="Claim your agent">
    The gateway created your agent in the shared Mnemom Sandbox (no owner). Claiming it proves you hold the provider key and moves it into your account so all read commands can resolve it.

    Copy the `X-Mnemom-Agent` value from the response headers above, then run:

    ```bash theme={null}
    mnemom agent claim mnm-550e8400-e29b-41d4-a716-446655440000 --name my-agent --key $ANTHROPIC_API_KEY
    ```

    Replace `mnm-550e8400-e29b-41d4-a716-446655440000` with the actual id from your `X-Mnemom-Agent` header.

    * Pass `--name` matching the `x-mnemom-agent` value you sent on the gateway call (omit `--name` if you made that call without the header). If the id, `--name`, or `--key` don't resolve to a real agent, the claim returns `404` — re-check the `X-Mnemom-Agent` id and that `--name`/`--key` match the gateway call.
    * The key is hashed locally (SHA-256) and never sent to Mnemom.
    * The agent lands in your active org (set with `mnemom org use <slug>`), or your personal org if you haven't set one; pass `--org <slug>` to claim into a specific shared org instead.
    * The operation is idempotent — safe to run more than once.

    <Note>
      A `503` response means your personal org is still being provisioned. Wait a few seconds and retry. For `403` cross-tenant or not-a-member errors, see the [Agent claim flow guide](/guides/agent-claim-flow).
    </Note>
  </Step>

  <Step title="Check status">
    Verify the gateway is reachable and your agent is connected:

    ```bash theme={null}
    mnemom status --agent my-agent
    ```

    This prints an authentication / gateway / API connectivity checklist, then your agent ID, the gateway URL, and a dashboard link, followed by a trace summary once the agent has traffic.
  </Step>

  <Step title="View traces">
    After making API calls through the gateway, view what was traced:

    ```bash theme={null}
    mnemom logs --agent my-agent
    ```

    Each trace prints as its own block — timestamp, action, type, and (when present) the reasoning excerpt and any policy violations. Use `mnemom logs --agent my-agent --limit 20` to show more entries.
  </Step>

  <Step title="Check activity">
    View your agent's AAP behavioral activity — total traces, how many verified clean, and any violations:

    ```bash theme={null}
    mnemom activity --agent my-agent
    ```

    ```text Output theme={null}
    Agent Activity (AAP)
      Score:      94.0% [█████████░]
      Total:      12 traces
      Verified:   11
      Violations: 1
    ```

    <Note>
      `mnemom integrity` is a deprecated alias for this same command — `mnemom activity` is the current name. Despite the name, this surfaces AAP trace verification, not the AIP per-turn [integrity checkpoints](/concepts/integrity-checkpoints); AIP checkpoint data is not yet exposed through the CLI.
    </Note>
  </Step>

  <Step title="View your alignment card">
    See the alignment card assigned to your agent:

    ```bash theme={null}
    mnemom card show --agent my-agent
    ```

    Customize it by publishing your own card:

    ```bash theme={null}
    mnemom card publish my-card.yaml --agent my-agent
    ```
  </Step>

  <Step title="Explore the dashboard">
    Your agent's data is available at [mnemom.ai/dashboard](https://mnemom.ai/dashboard) once you are logged in. The dashboard shows:

    * **Conscience timeline** -- A chronological view of every trace, integrity checkpoint, and enforcement action
    * **Alignment card** -- Your agent's declared values and boundaries
    * **Integrity scores** -- AIP verdict history and trend analysis
    * **Drift alerts** -- Notifications when behavior diverges from declared alignment
    * **Enforcement log** -- Records of nudges and blocks (if enforcement is enabled)
  </Step>
</Steps>

## Named agents

If you run multiple agents behind the same API key, use the `x-mnemom-agent` header to give each one a distinct identity. The provider path stays unchanged -- the gateway hashes `SHA256(apiKey + '|' + agentName)` to derive a unique agent ID. See [Agent Identity](/concepts/agent-identity) for the full ID derivation, the auto-create vs programmatic registration paths, and how key rotation interacts with agent identity.

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

Each named agent gets its own trace history, integrity scores, and drift detection -- even though they share an API key. Agents are auto-created on first API call; claim once (see the claim step above) to bind the agent to your account.

<Tip>
  You can also create agents programmatically via the [Agent CRUD API](/api-reference/endpoint/post-agents) if you want to pre-create agents with metadata before they make their first request.
</Tip>

## Supported providers

| Provider | Models | Thinking / AIP Support | Auth Header |
| - | - | - | - |
| Anthropic | Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5 | Full (thinking blocks analyzed directly) | `x-api-key` |
| OpenAI | GPT-6.1 Sol, GPT-6 Astra, GPT-6 Sol, GPT-6 Luna, GPT-5.6 Sol, GPT-5.6 Terra, GPT-5.6 Luna, GPT-5.5, GPT-5, GPT-5 Codex, o3, o3-mini | Not available through the gateway today | `Authorization: Bearer` |
| Gemini | Gemini 3.8 Flash, Gemini 3.5 Flash-Lite, Gemini 2.5 Pro, Gemini 2.5 Flash | Full (thought parts analyzed directly) | `x-goog-api-key` |

### AIP compatibility

| Provider / Model | AIP Support | Method |
| - | - | - |
| Anthropic reasoning models (Opus, Sonnet, Fable) | Full | Thinking blocks analyzed directly |
| Gemini 2.5/3 with thinking | Full | Thought parts analyzed directly |
| Non-reasoning models | Tracing only | Synthetic `clear` verdict, no analysis-LLM call |
| OpenAI (all models, including the o-series) | Not available | The gateway's `/openai` door proxies Chat Completions, which never returns reasoning content — see [Provider Support](/concepts/provider-support#2-openai--no-thinking-trace-inspection-through-the-gateway-today) for the full disclosure |

<Note>
  **Thinking elements in proxied responses.** Safe House / AIP enables extended thinking to analyze the agent's reasoning per turn. Proxied responses therefore include a `thinking` content element in the `content` array alongside the standard `text` block. Clients that assume text-only content arrays should be updated to handle or ignore `thinking` blocks. Thinking output tokens are billed as standard output tokens — this behavior is intentional and cannot be disabled.
</Note>

## What gets traced

The Mnemom Gateway builds [AP-Traces](https://github.com/mnemom/aap) that record:

* **Action** -- What the agent did (type, name, category)
* **Decision** -- What alternatives were considered and why one was selected
* **Escalation** -- Whether the agent escalated to a human and why
* **Verification** -- Whether the trace is consistent with the agent's declared Alignment Card
* **Integrity** -- Per-turn AIP analysis of thinking blocks, with verdict (`clear` / `review_needed` / `boundary_violation`)

## What is NOT stored

<Warning>
  Your **prompts**, **responses**, and **API keys** are never stored by Mnemom. The gateway processes requests in memory and forwards them to the provider. Only structured trace metadata (actions, decisions, verdicts) and thinking block analysis results are persisted.
</Warning>

## Enforcement modes

The Mnemom Gateway supports three enforcement modes when an integrity violation is detected:

| Mode | Behavior |
| - | - |
| `observe` | Detect violations, record them, take no action (default) |
| `nudge` | Detect violations, inject feedback into the agent's next request via system prompt. The agent sees it and can self-correct. |
| `enforce` | Gates same-turn on both streaming and non-streaming requests. The request still completes with a `2xx` status — the response body is replaced with an agent-voice intervention message and `X-Mnemom-Verdict` reports `integrity=enforced`. On streaming this adds latency because the response is evaluated before it is delivered. |

Set enforcement mode by updating the agent's alignment card. `integrity_mode` and `autonomy_mode` are top-level fields on the alignment card; the legacy `/v1/agents/{id}/enforcement` endpoint was retired 2026-05-14.

Three paths, pick the one that fits your workflow:

* **Dashboard:** open `https://mnemom.ai/dashboard/agents/{your-agent-id}/card`, toggle `integrity_mode`, save. Easiest path.
* **CLI:** `mnemom card edit` opens the current alignment-card YAML in `$EDITOR`; change `integrity_mode: nudge`, save, the CLI publishes + recomposes.
* **Programmatic:** [`PUT /v1/alignment/agent/{agent_id}`](/api-reference/endpoint/put-agents-agent-id-alignment-card) with the full canonical card. See the [Card Management guide](/guides/card-management) for the read-modify-write flow and the [alignment-card schema](/specifications/alignment-card-schema) for field requirements.

## Next steps

* [View protocol overview](/protocols/overview) to understand how AAP, AIP, and CLPI work together
* [Set up policy enforcement](/guides/policy-management) to define governance rules for your agent's tool usage
* [Explore concepts](/concepts/alignment-cards) to understand Alignment Cards, traces, and integrity
* [CLPI overview](/concepts/clpi) to understand the governance layer (policy enforcement, trust recovery, on-chain anchoring)
* [Read about enforcement](/gateway/enforcement) for detailed enforcement mode documentation
* [Self-host](/quickstart/self-hosted) if you need full data residency control


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.