# agent-preview/v1 — Open Specification (Internet-Draft) ```json {"@context":"https://schema.org","@type":"TechArticle","name":"agent-preview/v1 \u2014 Open Specification (Internet-Draft style)","description":"A vendor-neutral schema for one-fetch URL preview manifests, served alongside HTML at `.preview.json` and discoverable via ``.","url":"https://www.mnemom.ai/spec/agent-preview/v1/rfc","inLanguage":"en-US","dateModified":"2026-05-20","publisher":{"@type":"Organization","@id":"https://www.mnemom.ai#organization","name":"Mnemom","url":"https://www.mnemom.ai"}} ``` ```json {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://www.mnemom.ai/"},{"@type":"ListItem","position":2,"name":"For Agents","item":"https://www.mnemom.ai/for-agents"},{"@type":"ListItem","position":3,"name":"agent-preview/v1","item":"https://www.mnemom.ai/spec/agent-preview/v1"},{"@type":"ListItem","position":4,"name":"RFC","item":"https://www.mnemom.ai/spec/agent-preview/v1/rfc"}]} ``` Internet-Draft (informational, hosted) # agent-preview/v1 A vendor-neutral schema for one-fetch URL preview manifests. Spec version 1.0 MIME type application/vnd.agent-preview+json Normative spec [/spec/agent-preview/v1](https://www.mnemom.ai/spec/agent-preview/v1) Status Open invitation — adopt freely, no permission needed Publisher Mnemom (reference implementation) ## Abstract This document specifies **agent-preview/v1**, a JSON shape served as a sibling resource at `.preview.json` alongside every page that would otherwise be a candidate for OpenGraph preview. The manifest gives an agent client a structured, typed summary of a URL — title, summary, canonical, MIME-tagged representations (HTML, markdown mirror, OG image, JSON-LD), and type-specific context — in a single fetch. Discovery is via `` in the source HTML's ``. The intent is the OpenGraph equivalent for agentic clients: one fetch, structured, vendor-neutral. Any site can adopt the shape and publish manifests without Mnemom's permission or dependency. ## Status of this memo This is an informational draft hosted at `https://www.mnemom.ai/spec/agent-preview/v1/rfc`. The normative schema is at [https://www.mnemom.ai/spec/agent-preview/v1](https://www.mnemom.ai/spec/agent-preview/v1). Mnemom hosts the canonical text and reference implementation, and commits to: - Keep the v1 schema additive — new fields are optional; consumers MUST tolerate additional keys and unknown `type` values (treat unknowns as `reference`). - Version through URL paths (`/spec/agent-preview/v1`, `/v2`, …); old URLs stay frozen indefinitely. - Verify our own conformance via the nightly `preview-surface` commitment on [mnemom.ai/for-agents](https://www.mnemom.ai/for-agents). If adoption materializes across multiple independent implementations, the MIME type is candidate for IANA registration in the Standards Tree (dropping the `vnd.` prefix); see _IANA Considerations_. Until then this is a vendor-tree entry per RFC 6838. ## Conventions The key words **MUST**, **SHOULD**, **MAY**, **MUST NOT**, and **SHOULD NOT** in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals. ## Motivation An agentic client fetching a URL faces three choices today: 1. **Fetch + render HTML**: heavy. Most agents don't run a browser; the markdown mirror or OG meta is usually what they actually need. 2. **Fetch the markdown mirror** (`.md`): useful for body content, but doesn't carry the page's structured metadata (type, grade, status, author). 3. **Fetch the OG image**: a 1200×630 PNG. Not machine-readable in the structured sense. None of these is one-shot addressable. `agent-preview/v1` fills the gap: a single JSON fetch returns title, summary, canonical, representations (with discovery URLs for the other three), and type-specific context (e.g. `author / published_at / tags` for blog posts, `grade / score` for reputation profiles). ## Schema (v1) The manifest is a single JSON object. The normative TypeScript interface is in [`client/lib/preview-types.ts`](https://github.com/mnemom/mnemom-website/blob/main/client/lib/preview-types.ts). Required keys: ``` { "spec_version": "1.0", // String. Must equal "1.0" for v1. "spec_url": "...", // URL of this canonical spec. "url": "...", // The URL this preview is about. "canonical_url": "...", // Preferred form for citing. "type": "blog_post", // Type taxonomy; see below. "title": "...", // Short human-readable name. "summary": "...", // ≤ 220 chars recommended. "language": "en-US", // BCP-47 language tag. "representations": { "html": "...", // Required. "markdown": "...", // Optional (markdown mirror URL). "image": "https://www.mnemom.ai/api/og-image?type=blog&eyebrow=DISPATCHES&author=Mnemom+Research", "json_ld": "..." // Optional (JSON-LD source URL). }, "context": { /* type-specific; empty object valid */ }, "last_modified": "2026-05-13T00:00:00Z", "publisher": { "name": "...", "url": "...", "agents_txt": "...", "readiness_manifest": "..." } } ``` **Type taxonomy** (extensible; consumers MUST treat unknowns as `reference`): `home`, `marketing`, `blog_post`, `research_paper`, `case_study`, `agent_profile`, `team_profile`, `methodology`, `explainer`, `policy`, `discovery`, `coherence_report`, `reference`. **Context fields** (all optional, additive): `eyebrow`, `author`, `published_at` (ISO 8601), `reading_time_min`, `tags` (array), `company`, `outcome`, `agent_id`, `team_id`, `grade`, `score` (0–1000), `last_attested_at`, `status`, `primitives` (array). ## Discovery Sites **MUST** advertise availability via a `` element in the source page's ``: ``` ``` Servers **SHOULD** respond to `Accept: application/vnd.agent-preview+json` requests on the source URL with a 303 redirect to the `.preview.json` sibling, but clients **MUST NOT** assume conneg is implemented — the discovery link is the canonical path. Servers **MUST** serve the manifest with `Content-Type: application/vnd.agent-preview+json`. ## Versioning v1 fields are conservative; new fields land additively in minor revisions (1.0 → 1.1 → 1.2). Schema-breaking changes require a new major path (`/spec/agent-preview/v2`). Old major versions stay frozen — adopters can pin `spec_url` and trust that the schema there will never change shape. ## Security considerations The preview JSON is public. Publishers **MUST NOT** include access-controlled data (private cards, claimed-only reports, signed payloads). For URLs that are `noindex` or otherwise gated, publishers either omit the manifest sibling entirely or serve a tombstone variant exposing only the fact of the URL's existence without sensitive context. Mnemom's implementation declines to write manifests for `/r/` (the coherence-report URLs are themselves the access-control mechanism). Caching: the manifest's `last_modified` is the stable source-of-truth timestamp. Clients **SHOULD** revalidate against `If-Modified-Since`. Manifests have no embedded freshness window beyond standard HTTP cache headers. ## IANA considerations The MIME type `application/vnd.agent-preview+json` is currently a vendor-tree entry per RFC 6838 §3.2. If interoperable use across multiple independent implementations is demonstrated, the registrant (Mnemom) will request promotion to the Standards Tree at `application/agent-preview+json`, retaining the same schema and discovery pattern. The version path stays at `/spec/agent-preview/v1` through the rename. Until promotion, the vendor-tree entry is intentional and stable. Adopters can rely on the existing MIME for production use; the schema does not change as a function of registration status. ## Adoption The spec is intentionally vendor-neutral. Any site can adopt the shape, point at this hosted spec, and let its URLs become one-fetch addressable for agents — no Mnemom dependency, no permission needed. The reference implementation is open at [github.com/mnemom/mnemom-website](https://github.com/mnemom/mnemom-website) (see `scripts/build-preview-cards.mjs`). If you've shipped agent-preview manifests on a domain you control, we'd love to add you to the adopters list — open an issue at the repo above. ## References - RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels - RFC 8174 — Ambiguity of Uppercase vs Lowercase in 2119 - RFC 6838 — Media Type Specifications and Registration Procedures - RFC 9110 — HTTP Semantics (content negotiation, conditional requests) - OpenGraph Protocol — [ogp.me](https://ogp.me/) Source: [client/pages/SpecAgentPreviewRFC.tsx](https://github.com/mnemom/mnemom-website/blob/main/client/pages/SpecAgentPreviewRFC.tsx). Normative TypeScript: [client/lib/preview-types.ts](https://github.com/mnemom/mnemom-website/blob/main/client/lib/preview-types.ts). --- _Source: /spec/agent-preview/v1/rfc/index.html · Generated by build-markdown-mirrors.mjs · For agent-readability commitment #4 see https://www.mnemom.ai/for-agents_