FRESH

Know whether an AI agent should REUSE or REFETCH a URL before retrieving it again.

GitHub

Documentation

FRESH

Know whether to fetch again.

FRESH is shared URL freshness intelligence for AI agents. Before re-fetching, re-scraping, re-rendering, or re-embedding a URL, ask whether the previously seen version is probably still fresh enough to reuse.

Production base URL: https://fresh-api-production-c783.up.railway.app

MCP endpoint: https://fresh-api-production-c783.up.railway.app/mcp

FRESH returns one of three decisions:

  • REUSE — cached knowledge is probably still fresh enough
  • REFETCH — the URL is likely stale enough to justify another retrieval
  • UNKNOWN — evidence is insufficient; FRESH prefers uncertainty over false confidence

Why FRESH exists

A local cache knows when you last fetched something. It does not know whether the outside resource changed since then, nor what other callers recently observed. FRESH builds shared, privacy-safe URL change history from timestamps, ETags, Last-Modified values, and content hashes.

REST

POST /v1/check

{"url":"https://example.com/docs/api","lastSeenAt":"2026-08-13T12:00:00Z","toleranceSeconds":3600}

POST /v1/observe

{"url":"https://example.com/docs/api","observedAt":"2026-08-13T13:00:00Z","etag":"abc123","lastModified":"Wed, 13 Aug 2026 12:45:00 GMT","contentHash":"sha256:..."}

Raw page content is not required.

MCP

  • fresh_check — decide whether to retrieve a URL again
  • fresh_observe — report privacy-safe freshness evidence after retrieval

Privacy

FRESH does not need raw page contents, cookies, target-site credentials, or customer payloads. URL keys are stored as one-way hashes with aggregate observation metadata.

Stranger verification

A core-tool invocation is evidence of use, not automatically proof of a genuine stranger. FRESH classifies candidate activity as KNOWN_VALIDATOR, LIKELY_VALIDATOR, CONTROLLED_TEST, UNKNOWN_MACHINE, or CREDIBLE_REAL_USE. Only CREDIBLE_REAL_USE advances stranger milestones.

Our acceptance/smoke traffic uses X-Tollbooth-Internal: 1 or X-Fresh-Internal: 1 so it cannot earn stranger credit.

Production acceptance gate

Every Railway deployment now performs live internal checks against the running service before /health can return 200. The gate exercises REST, UNKNOWN, REUSE, REFETCH, persistent observation reload, MCP initialize, MCP tool discovery, MCP fresh_check, and verifies that the controlled self-test does not increase the verified-stranger count.

Status

v0.1.2 experimental production infrastructure. Priorities: conservative decisions, low latency, sub-penny economics, privacy-safe shared learning, REST + MCP, durable observations, and auditable real-use analytics.