The FreshContext
Specification

What this is

The FreshContext Specification defines a standard envelope format for AI-retrieved web data and a temporal correction layer that scores it.

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. MCP is one interface over the methodology; the envelope and structured metadata are the compatibility contract.

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. The canonical FreshContext model is exponential Decay-Adjusted Relevancy:

R_t = R_0 · e^(-λt)

For envelope-level freshness, R_0 may be normalised to 100. For ranked intelligence feeds, R_0 may be semantic or profile relevance. λ is the source-specific decay constant and t is signal age.

Context-conditioned utility: FreshContext can rank the same signal differently depending on the requesting user, query, agent, or workflow. That context shapes R_0; DAR then applies source-specific temporal decay through R_t = R_0 · e^(-λt). Core utility primitives may model this as U(q, s, t) = R(q, s) · e^(-λt) · C_date · C_status.

If no reliable timestamp exists, implementations SHOULD set freshness_score to null and confidence to low. Missing, invalid, or future timestamps beyond clock-skew tolerance MUST NOT be treated as fresh.

Reference decay classes

These are reference/default classes. Implementations may tune them by source, profile, or deployment while preserving the exponential DAR model.

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
• Surface retrieval failures explicitly

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

Failure honesty

Adapters MUST NOT wrap failed, empty, blocked, timeout, rate-limited, access-denied, or malformed output as high-confidence fresh context.

If adapter output looks like an error, implementations SHOULD downgrade confidence to low, set freshness_score to null, preserve enough error context for diagnosis, and avoid presenting the result as successful current context.

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

MCP is one interface, not the whole FreshContext model. FreshContext-compatible systems may be MCP servers, APIs, CLIs, npm packages, dashboards, agents, or internal services.

Verify: npx freshcontext-validate <response>

Core-backed implementation status

FreshContext Core now owns freshness scoring, envelope generation, confidence metadata, failure guards, shared types, and rank/explain primitives in the reference implementation.

The live MCP Worker uses Core-backed envelope generation while Cloudflare-specific runtime behavior, MCP transport, cache policy, rate limits, and deployment concerns remain outside Core.

Claude Desktop is a supported MCP client, but FreshContext Core is not Claude-dependent. MCP is one interface over the methodology.

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 addresses this. Retrieved data can carry timestamp, confidence, provenance, and freshness metadata. The agent can reason about data age before acting, and users can inspect how fresh the provided context appears to be.

Changelog