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 underX-Mnemom-* or X-AIP-* was retired clean-break on 2026-05-08 — see 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 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}. 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. |
| 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. |
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. The full integrity pipeline starts after claim. See integrity during the unclaimed phase.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:
pass | observed | nudged | enforced. The semantics of each verdict per checkpoint:
| Checkpoint | pass | observed | nudged | enforced |
|---|---|---|---|---|
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). |
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. |
integrity (AIP on reasoning) | Reasoning within boundary. | Boundary violation observed but no replacement. | Reasoning surfaced a nudge into the response. | Response was replaced same-turn with a same-voice intervention. |
back (Protection outbound) | Output clean. | Output flagged but unchanged. | Output flagged with a warning suffix. | Output redacted, replaced, or blocked same-turn. |
pass means the checkpoint ran and the request was clean.
Parser snippets
TypeScript: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.
| 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
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.
X-Mnemom-Request-Id is set — paste-into-support works on the failure case too.
Inbound stripping
The gateway strips customer-suppliedX-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).
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 intoX-Mnemom-Verdict.autonomy.
X-Safe-House-Verdict/X-Safe-House-Advisory/X-Safe-House-Event→ fold intoX-Mnemom-Verdict.front+X-Mnemom-Advisory.X-Safe-House-Quarantine-Id/X-Safe-House-Canary-Triggered/X-Safe-House-DLP→ fold intoX-Mnemom-Advisoryentries.X-Safe-House-Session-Risk/X-Safe-House-Mode/X-Safe-House-Simulated-Verdict→ were operator-dashboard signals only; data lives insh_evaluations/audit_log.
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 intoX-Mnemom-Verdict.integrity.X-AIP-Certificate-Id/X-AIP-Chain-Hash→ fetch via the integrity-checkpoints REST surface usingX-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-Safe-House-Advisory | X-Mnemom-Advisory (canonical name; same JSON shape) | See X-Mnemom-Advisory |
X-AIP-Verdict | Retained as the raw AAP value; X-Mnemom-Verdict.integrity is the canonical rollup | Both are present when AIP runs |
Sunset header on the legacy names. The retirement is clean-break.
See also
- Errors — canonical status-code + error-code contract, including Safe House verdict-to-status mapping and retry semantics.
- Webhook contract — the seven invariants every webhook event carries.