Skip to main content

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.

This page is Mnemom’s canonical commitment for how the API evolves. It is the contract we expect every customer integration to be able to rely on. For how-to detail, see the API Versioning guide.

​
The two version axes

Mnemom versions the API at two independent levels:
AxisWhere it livesWhen it changesWhat it gates
URL generation/v1/ prefix in every pathOnly for complete API redesigns. Expected cadence: at most once every several years.The shape of the surface — paths, resource hierarchy, top-level abstractions.
Date-pinned behaviorX-Mnemom-Version: YYYY-MM-DD request/response headerEach breaking change inside a /v1/-generationField names, response shapes, default behavior, enum values, validation rules.
Both axes are independent. A new X-Mnemom-Version date never moves the URL; a new URL generation does not invalidate active date-pinned integrations. This dual model mirrors Stripe-Version and GitHub’s X-GitHub-Api-Version. Per the ADR-042 amendment (Q2 ratification 2026-05-08), X-Mnemom-Version is the 7th Mnemom-namespaced header and is permanent contract.

​
How clients pin a version

Production integrations must pin by sending the X-Mnemom-Version header on every request: 
GET /v1/agents/mnm-... HTTP/1.1
Host: api.mnemom.ai
X-Mnemom-Api-Key: ...
X-Mnemom-Version: 2026-04-13
If the header is omitted, the latest stable version is served. This is fine for exploratory calls; it is not safe for production systems — and especially not for AI agents, whose embedded environments rarely self-update in response to version-cutover messages. The response always echoes the version that was applied: 
HTTP/1.1 200 OK
X-Mnemom-Version: 2026-04-13
If you request a version we don’t recognize (typo, future date, retired version), we serve the closest valid predecessor and the response header tells you which one was applied. We never 4xx on an unrecognized version — silent fallback to the predecessor is the supported failure mode.

​
Support window

Change classMinimum support windowNotes
Standard breaking change18 months from the new version’s release dateLonger than most APIs (typical industry standard is 12). The premium reflects Mnemom’s service to the agentic internet: an agent in production may not be able to update on a human cadence.
Security-critical change30 days minimumRare; only when continued support of the old behavior would create a customer-facing security exposure. We notify and assist migration on an accelerated path.
Enterprise / contract termsPer contractSome enterprise contracts negotiate longer windows.
After the window closes, calls to the retired version receive a 410 Gone with a Sunset header and a link to the migration guide. There is no silent re-mapping past retirement — the surface is final.

​
What counts as a breaking change

A change is breaking (requires a new version date) if any of:
  • A response field is removed or renamed.
  • A response field’s type changes.
  • A previously optional request field becomes required.
  • An enum loses a value, or an enum’s set of valid values is constrained.
  • An endpoint is removed.
  • A default behavior changes in a way client code could observe.
A change is non-breaking (no new version date) if any of:
  • A new endpoint is added.
  • A new optional response field is added.
  • A new optional request parameter is added.
  • An enum gains a new value.
  • A new response header is introduced.
For non-breaking changes, clients are expected to follow the Tolerant Reader discipline — ignore unknown fields, treat unknown enum values as the documented fallback (we always document the fallback), and never assume a fixed set of headers. This is the same discipline protobuf / Stripe-Version-style ecosystems require. Tooling that fails closed on additive evolution is brittle.

​
Deprecation signals

When a version is deprecated, calls to that version surface: 
Deprecation: true
Sunset: Mon, 13 Oct 2027 00:00:00 GMT
Link: <https://docs.mnemom.ai/policy/versioning>; rel="deprecation"
X-Mnemom-Deprecation-Note: Version 2026-04-13 deprecated; migrate to 2026-10-01 by Oct 2027
The headers conform to RFC 8594 (Sunset) and draft-ietf-httpapi-deprecation-header (Deprecation). In parallel, we send email notifications to the org owner and to any integration contacts on file at:
  • T+0 — deprecation announcement.
  • T+12 months — half-window mark.
  • T+16 months — 60-day warning.
  • T+17 months — 30-day final warning.

​
What we will not do

  • We will not break date-pinned production behavior within /v1/ without bumping the date.
  • We will not retire a version before the published Sunset date.
  • We will not silently change X-Mnemom-Version resolution behavior. The fallback rule (closest valid predecessor) is part of the contract.
  • We will not introduce a /v2/ URL generation for individual breaking changes. URL increments are reserved for resource-model overhauls.