> ## 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.
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.
```bash theme={null}
npm install -g @mnemom/mnemom
```
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`.
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.
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/*` |
Most SDKs and frameworks let you override the base URL. Set it to the gateway path for your provider and everything else works unchanged.
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) | 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). `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.** |
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 (when `enforced` becomes a 422 quarantine or 403 block).
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 agents 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 personal org by default; pass `--org ` to claim into a shared org.
* The operation is idempotent — safe to run more than once.
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).
Verify the gateway is reachable and your agent is connected:
```bash theme={null}
mnemom status --agent my-agent
```
```text Output theme={null}
Agent: my-agent (mnm-550e8400-e29b-41d4-a716-446655440000)
Gateway: https://gateway.mnemom.ai (healthy)
Status: Connected
Providers: anthropic, openai
Last seen: just now
```
After making API calls through the gateway, view what was traced:
```bash theme={null}
mnemom logs --agent my-agent
```
```text Output theme={null}
2026-02-17T10:30:00Z tr-abc123 recommend bounded verified 0.82
2026-02-17T10:30:05Z tr-abc124 search bounded verified 0.76
2026-02-17T10:30:12Z tr-abc125 respond bounded verified 0.91
```
Use `mnemom logs --agent my-agent -l 20` to show more entries.
View AIP integrity scores for your agent's recent activity:
```bash theme={null}
mnemom integrity --agent my-agent
```
```text Output theme={null}
Agent: mnm-550e8400-e29b-41d4-a716-446655440000
Checkpoints: 12
Verdicts:
clear: 11
review_needed: 1
boundary_violation: 0
Integrity score: 0.94
Drift: none detected
```
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
```
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)
## 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.
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.
## Supported providers
{/* */}
| Provider | Models | Thinking / AIP Support | Auth Header |
| --------- | --------------------------------------------------------------------- | -------------------------------------------- | ----------------------- |
| Anthropic | 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-5, GPT-5 Codex, o3, o3-mini | Via reasoning summaries (reduced confidence) | `Authorization: Bearer` |
| Gemini | 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) | Full | Thinking blocks analyzed directly |
| OpenAI GPT-5 Thinking series | Partial | Reasoning summaries (reduced confidence) |
| Gemini 2.5/3 with thinking | Full | Thought parts analyzed directly |
| Non-reasoning models | Tracing only | Synthetic clear verdict |
| OpenAI o-series (o3, o3-mini) | Partial | Reasoning summaries only — reduced confidence |
**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.
## 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
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.
## 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 (HTTP 403 for non-streaming); 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