The FreshContext
Specification

What this is

The FreshContext Specification defines a standard envelope format for AI-retrieved web data.

It exists to solve one problem: AI models present stale data with the same confidence as fresh data, and users have no way to tell the difference.

Any tool, agent, or system that implements this spec is FreshContext-compatible.

The envelope format

Every FreshContext-compatible response MUST wrap its content in the following text envelope:

[FRESHCONTEXT]
Source: <canonical_url>
Published: <content_date_or_unknown>
Retrieved: <iso8601_datetime>
Confidence: <high|medium|low>
---
<content>
[/FRESHCONTEXT]

Confidence levels

Structured JSON form

Implementations MAY additionally expose freshness metadata as structured JSON. This form can be validated against the JSON Schema.

{
  "freshcontext": {
    "source_url":          "https://github.com/owner/repo",
    "content_date":        "2026-03-05",
    "retrieved_at":        "2026-04-05T09:19:00.000Z",
    "freshness_confidence": "high",
    "freshness_score":     94,
    "adapter":             "github",
    "decay_rate":          1.0
  },
  "content": "..."
}

Validate with: npx freshcontext-validate <json_string>

Freshness score

An optional numeric freshness value 0–100:

freshness_score = max(0, 100 - (days_since_retrieved × decay_rate))

Domain-specific decay rates

Adapter contract

Any data source that feeds into a FreshContext-compatible system is called an adapter.

Adapters MUST:

• Return raw content plus a content_date (or null if unknown)
• Set a freshness_confidence level based on how the date was determined
• Never fabricate or forward-date content timestamps
• Identify the source system via the adapter field

Adapters SHOULD:

• Prefer structured API sources over scraped content when both are available
• Surface rate-limit or access-denied errors explicitly rather than returning empty content
• Never silently return cached or stale data on retrieval failure

Composite adapters (v1.1)

A composite adapter combines multiple single-source adapters into one call. Composites MUST:

• Run constituent adapters in parallel (Promise.allSettled or equivalent)
• Handle partial failures gracefully — if one source fails, the others still return
• Label each section with its source adapter name
• Include a Generated: timestamp at the top of combined output
• Support an optional min_freshness_score parameter (0–100) to filter constituent results

When min_freshness_score is set, any constituent result below the threshold is replaced with a staleness warning rather than omitted, preserving output structure.

Compatibility levels

Verify: npx freshcontext-validate <response>

Implementations

Why this matters for AI agents

Large language models have no internal clock. When an agent retrieves web data, it cannot distinguish between something published this morning and something published three years ago — unless that information is explicitly surfaced.

The spec started from a concrete failure: the author asked an AI to help find a job. It returned listings. Three applications later — two roles no longer existed, one had closed two years prior. The AI presented everything with equal confidence.

FreshContext is the fix. Every piece of retrieved data carries its own timestamp. The agent can reason about data age before acting. Users can see exactly how fresh their AI’s information is.

Changelog