> ## 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. # Response Headers > The canonical Mnemom-namespaced response header set, presence conditions, and parser snippets for X-Mnemom-Verdict. ## The canonical set Every Mnemom response carries a tightly-scoped header surface. The Mnemom-namespaced set is **six headers**, plus an optional API-version header and an AAP allow-list pair. Anything else under `X-Mnemom-*` or `X-AIP-*` was retired clean-break on 2026-05-08 — see [What was retired](#what-was-retired) below. **Migrating from legacy headers?** Deprecated headers (`X-Safe-House-*`, most `X-AIP-*`, `X-Mnemom-Autonomy-Verdict`) were retired clean-break on 2026-05-08. See [What was retired](#what-was-retired) below for the legacy → canonical mapping. There is **no dual-emit window** and **no `Sunset` header** on the legacy names — they stopped emitting on the 2026-05-08 ship. | Header | Always emitted? | Emitted by | Purpose | | --------------------- | ------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-Mnemom-Request-Id` | Always | Gateway | UUIDv4 per request — paste into a support ticket and we can pull every log line for that request. Stable across the whole pipeline. | | `X-Mnemom-Verdict` | Always (gateway) | Gateway | Structured per-checkpoint verdict: `front=…; autonomy=…; integrity=…; back=…`, each in `{pass \| observed \| nudged \| enforced \| unverified}`. Parse once; grep four checkpoints. | | `X-Mnemom-Advisory` | When non-empty | Gateway | Compact JSON array of advisory entries `[{source, text, severity?, id?}, …]`. Capped at 5 entries. Omitted entirely when no advisories fired. | | `X-Mnemom-Schema` | On API responses with versioned shapes | mnemom-api | Response-shape identifier (e.g. `alignment_card/v1`, `safe-house-harness-state/v1`). Mirrors the shape your client should validate against. | | `X-Mnemom-Version` | Always (mnemom-api) | mnemom-api | Echoes the date-based API version the response was rendered against (`YYYY-MM-DD`). Stripe-Version analog. | | `X-Mnemom-Agent` | When the request is bound to a named agent | Gateway | The agent identifier the gateway resolved your request to. | | `X-Mnemom-Session` | When the request is part of a multi-turn session | Gateway | Stable session correlation token across a multi-turn conversation. | **AAP allow-list (two headers):** | Header | Always emitted? | Purpose | | --------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-AIP-Verdict` | When AIP analysis ran | Raw AAP verdict for SDK clients (`pass \| boundary_violation \| ambiguous \| clear \| skipped \| pending \| disabled \| error`). The structured `X-Mnemom-Verdict.integrity` is the canonical rollup; `X-AIP-Verdict` is the raw value SDK clients use to fetch the full attestation via `Checkpoint-Id`. | | `X-AIP-Checkpoint-Id` | When AIP analysis stored a checkpoint | Pointer to the integrity checkpoint row. Use this to fetch the full attestation chain via the [integrity checkpoints REST surface](/api-reference/endpoint/get-agents-agent-id-checkpoints-checkpoint-id). | **Unclaimed agents: verdict headers are fail-open, not analytical.** Gateway-auto-provisioned agents that have not been claimed have no canonical alignment card. `X-Mnemom-Verdict` and `X-AIP-Verdict` are still emitted on every request, but their values (`pass`/`clear`) come from the gateway's fail-open path — AIP analysis did not run. `X-AIP-Checkpoint-Id` will not be present. This is expected behavior; it is not the `unverified` state described above — `unverified` means analysis was attempted (a canonical card exists) and failed, whereas an unclaimed agent has no analysis to attempt in the first place. The full integrity pipeline starts after claim. See [integrity during the unclaimed phase](/guides/agent-claim-flow#between-steps-integrity-during-the-unclaimed-phase). Plus standards: `Content-Type`, `Cache-Control`, CORS headers, and `Idempotent-Replay: true` on cached idempotency replays. ## `X-Mnemom-Verdict` — structured per-checkpoint state **Format.** Single-line, semicolon-separated `key=value` pairs. Familiar HTTP convention (Cookie, Cache-Control, Server-Timing). Always exactly four checkpoints, always in canonical order: ``` X-Mnemom-Verdict: front=pass; autonomy=pass; integrity=pass; back=pass ``` Each value is one of `pass | observed | nudged | enforced | unverified`. The semantics of each verdict per checkpoint: | Checkpoint | `pass` | `observed` | `nudged` | `enforced` | `unverified` | | ----------------------------------- | -------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **`front`** (Protection inbound) | No threat detected. | Threat observed but not acted on (`mode=observe`). | Inbound content carried a guidance nudge (`mode=nudge`). | Inbound content was replaced or quarantined same-turn (`mode=enforce`). | Not produced by this checkpoint — Safe House evaluation fails closed internally rather than surfacing an unverified state. | | **`autonomy`** (CLPI on tool calls) | Tool call within bounds. | Out-of-bounds tool call observed but allowed. | Tool call surfaced a warning. | Tool call replaced with a synthetic error response. | Not produced by this checkpoint. | | **`integrity`** (AIP on reasoning) | Reasoning within boundary. | Boundary violation observed but no replacement. | Verdict recorded post-hoc and carried into the agent's next turn (`mode=nudge`); this response is not gated. | Response was replaced same-turn with a same-voice intervention. | The integrity checkpoint produced no trustworthy verdict — the analysis LLM timed out or errored. In `enforce` the response is **withheld** (fail-closed, still returned as a 2xx intervention); in `observe`/`nudge` the response is forwarded and the unverified state is recorded. Never reported as `pass`. | | **`back`** (Protection outbound) | Output clean. | Output flagged but unchanged. | Output flagged; recorded post-hoc (`mode=nudge`) and carried into the next turn — this response is not gated. | Output redacted, replaced, or blocked same-turn. | Not produced by this checkpoint. | The four-checkpoint model is documented in the [Safe House concept](/concepts/safe-house). All four checkpoints **always run** on every gateway-routed request — `pass` means the checkpoint ran and the request was clean. Verdict timing is mode-dependent: in `enforce` the `integrity`/`back` verdicts are resolved before the response is returned (streaming adds latency to preserve this); in `observe`/`nudge` analysis is post-hoc, so a backgrounded checkpoint's same-turn header value is provisional. `off` runs no analysis. **`unverified` is integrity-only and fail-closed by design.** It is the sole verdict that can never be silently reported as `pass` — an analyzer failure (timeout, error, or breaker-open) is a *distinct* outcome from a clean analysis, so the header says so explicitly. This is orthogonal to `off`/no-analysis: `off` never runs a checkpoint at all, while `unverified` means analysis was attempted and failed. ### Parser snippets **TypeScript:** ```ts theme={null} type VerdictValue = 'pass' | 'observed' | 'nudged' | 'enforced' | 'unverified'; type CheckpointVerdicts = { front: VerdictValue; autonomy: VerdictValue; integrity: VerdictValue; // the only checkpoint that can report 'unverified' back: VerdictValue; }; function parseMnemomVerdict(headerValue: string): CheckpointVerdicts { return Object.fromEntries( headerValue.split(';').map(s => s.trim().split('=')), ) as CheckpointVerdicts; } const v = parseMnemomVerdict(response.headers.get('X-Mnemom-Verdict')!); if (v.integrity === 'enforced') { // Same-turn AIP replacement happened — surface that in your UI. } ``` **Python:** ```python theme={null} from typing import TypedDict, Literal VerdictValue = Literal['pass', 'observed', 'nudged', 'enforced', 'unverified'] class CheckpointVerdicts(TypedDict): front: VerdictValue autonomy: VerdictValue integrity: VerdictValue back: VerdictValue def parse_mnemom_verdict(header_value: str) -> CheckpointVerdicts: return dict( s.strip().split('=', 1) for s in header_value.split(';') ) # type: ignore[return-value] v = parse_mnemom_verdict(response.headers['X-Mnemom-Verdict']) if v['integrity'] == 'enforced': pass # surface to UI / log / metric ``` **Go:** ```go theme={null} package mnemom import "strings" type CheckpointVerdicts struct { Front string Autonomy string Integrity string Back string } func ParseMnemomVerdict(headerValue string) CheckpointVerdicts { out := CheckpointVerdicts{} for _, pair := range strings.Split(headerValue, ";") { kv := strings.SplitN(strings.TrimSpace(pair), "=", 2) if len(kv) != 2 { continue } switch kv[0] { case "front": out.Front = kv[1] case "autonomy": out.Autonomy = kv[1] case "integrity": out.Integrity = kv[1] case "back": out.Back = kv[1] } } return out } ``` ## `X-Mnemom-Advisory` — operator-actionable advisory entries **Format.** Compact JSON array. Each entry is `{source, text, severity?, id?}`. Capped at 5 entries (HTTP header size safety). Omitted entirely when there are no advisories. ```http theme={null} X-Mnemom-Advisory: [{"source":"safe_house.dlp","text":"DLP-protected content detected in agent output","severity":"warn"}] ``` Field semantics: | Field | Required | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `source` | Yes | Stable provenance string (`safe_house.dlp`, `safe_house.canary`, `safe_house.quarantine`, `sideband.coherence`, etc.). Maps to the producer surface. | | `text` | Yes | Human-readable one-line summary. Surface this in dashboards / alerts. | | `severity` | Optional | `info \| warn \| critical`. Drives color / prominence in operator UIs. | | `id` | Optional | Stable identifier for the underlying advisory row (e.g. quarantine\_id). Lets you fetch full detail via the API. | ### Parsing ```ts theme={null} type MnemomAdvisory = { source: string; text: string; severity?: 'info' | 'warn' | 'critical'; id?: string; }; const advisoryHeader = response.headers.get('X-Mnemom-Advisory'); const advisories: MnemomAdvisory[] = advisoryHeader ? JSON.parse(advisoryHeader) : []; ``` When the receiving application needs more than 5 advisories per request, fetch the full set via the per-agent advisory listing endpoint — the header cap is a transport budget, not a semantic limit. ## `X-Mnemom-Request-Id` — support correlation UUIDv4 per request. Stable across the entire request lifecycle (gateway → mnemom-api → Supabase → response). When you open a support ticket, paste this header value — we can pull every log line, OTel span, and audit row for the request. ```http theme={null} X-Mnemom-Request-Id: 8f446ed6-ca87-4c1d-aa90-e2bc6e9ef580 ``` The header is **always emitted on gateway-routed responses**, including 4xx and 5xx error responses. Even on auth-failure 401s, the `X-Mnemom-Request-Id` is set — paste-into-support works on the failure case too. ## Inbound stripping The gateway strips customer-supplied `X-Mnemom-*` and `X-AIP-*` from inbound requests at the boundary. This closes a header-smuggling attack vector — without the strip, an upstream proxy or compromised middleware could inject `X-Mnemom-Verdict: front=pass; ...` into a request and confuse downstream consumers parsing headers naively. The four customer-meaningful headers that survive the strip: * `X-Mnemom-Api-Key` — programmatic auth. * `X-Mnemom-Version` — date-based API version negotiator. * `X-Mnemom-Agent` — named-agent identifier (lets the gateway route per-agent). * `X-Mnemom-Session` — multi-turn session correlation (typically server-emitted, but customers can pass through to maintain session continuity across a managed proxy). Anything else under `X-Mnemom-*` or `X-AIP-*` on inbound is deleted. If you're testing with `curl` and accidentally include a verdict-shaped header, the response will reflect the gateway's own canonical state — your inbound value never reaches downstream code. ## What was retired 20 deprecated response headers were retired clean-break on 2026-05-08: **Autonomy verdict (1):** * `X-Mnemom-Autonomy-Verdict` → folds into `X-Mnemom-Verdict.autonomy`. **Safe House extras (9):** * `X-Safe-House-Verdict` / `X-Safe-House-Advisory` / `X-Safe-House-Event` → fold into `X-Mnemom-Verdict.front` + `X-Mnemom-Advisory`. * `X-Safe-House-Quarantine-Id` / `X-Safe-House-Canary-Triggered` / `X-Safe-House-DLP` → fold into `X-Mnemom-Advisory` entries. * `X-Safe-House-Session-Risk` / `X-Safe-House-Mode` / `X-Safe-House-Simulated-Verdict` → were operator-dashboard signals only; data lives in `sh_evaluations` / `audit_log`. **AAP extras (10):** * `X-AIP-Action` / `X-AIP-Proceed` / `X-AIP-Synthetic` / `X-AIP-Source` / `X-AIP-Analysis-Scope` / `X-AIP-Reason` / `X-AIP-Nudge-Count` / `X-AIP-Enforcement` → fold into `X-Mnemom-Verdict.integrity`. * `X-AIP-Certificate-Id` / `X-AIP-Chain-Hash` → fetch via the integrity-checkpoints REST surface using `X-AIP-Checkpoint-Id`. ### Common renames at a glance For upgraders, the high-traffic renames customers were most likely to have hard-coded: | Legacy name | Canonical name | Where to find it | | --------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `x-request-id` | `X-Mnemom-Request-Id` | Always-emitted UUIDv4; paste into support tickets | | `Idempotency-Key` (response echo) | `Idempotent-Replay: true` | Returned only when a cached idempotent replay is served | | `X-Safe-House-Verdict` | `X-Mnemom-Verdict.front` (sub-field of the structured verdict) | Parse `X-Mnemom-Verdict` per the [grammar above](#x-mnemom-verdict--structured-per-checkpoint-state) | | `X-Safe-House-Advisory` | `X-Mnemom-Advisory` (canonical name; same JSON shape) | See [`X-Mnemom-Advisory`](#x-mnemom-advisory--operator-actionable-advisory-entries) | | `X-AIP-Verdict` | Retained as the **raw** AAP value; `X-Mnemom-Verdict.integrity` is the canonical rollup | Both are present when AIP runs | There is **no dual-emit window** and **no `Sunset` header** on the legacy names. The retirement is clean-break. ## See also * [Errors](/api-reference/errors) — canonical status-code + error-code contract, including Safe House verdict-to-status mapping and retry semantics. * [Webhook contract](/concepts/webhook-contract) — the seven invariants every webhook event carries.