FRESH

Saiba se um agente de IA deve REUTILIZAR ou BUSCAR NOVAMENTE uma URL antes de recuperá-la.

GitHubExperimente este MCPPatrocinado

Documentação

FRESH

Saiba se deve buscar novamente.

FRESH é inteligência compartilhada de atualização de URLs para agentes de IA. Antes de buscar novamente, raspar de novo, renderizar de novo ou reincorporar uma URL, pergunte se a versão vista anteriormente provavelmente ainda está atualizada o suficiente para ser reutilizada.

URL base de produção: https://fresh-api-production-c783.up.railway.app

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

FRESH retorna uma de três decisões:

  • REUSE — o conhecimento em cache provavelmente ainda está atualizado o suficiente
  • REFETCH — a URL provavelmente está desatualizada o suficiente para justificar outra recuperação
  • UNKNOWN — as evidências são insuficientes; FRESH prefere incerteza a falsa confiança

Por que o FRESH existe

Um cache local sabe quando você buscou algo pela última vez. Ele não sabe se o recurso externo mudou desde então, nem o que outros chamadores observaram recentemente. FRESH constrói um histórico compartilhado e seguro de mudanças de URLs a partir de timestamps, ETags, valores Last-Modified e hashes de conteúdo.

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:..."}

O conteúdo bruto da página não é necessário.

MCP

  • fresh_check — decide se deve recuperar uma URL novamente
  • fresh_observe — reporta evidências de atualização seguras para privacidade após a recuperação

Privacidade

FRESH não precisa do conteúdo bruto das páginas, cookies, credenciais do site de destino ou payloads do cliente. Chaves de URL são armazenadas como hashes unidirecionais com metadados agregados de observação.

Verificação de estranhos

Uma invocação de ferramenta principal é evidência de uso, não prova automática de um estranho genuíno. FRESH classifica a atividade candidata como KNOWN_VALIDATOR, LIKELY_VALIDATOR, CONTROLLED_TEST, UNKNOWN_MACHINE ou CREDIBLE_REAL_USE. Apenas CREDIBLE_REAL_USE avança os marcos de estranhos.

Nosso tráfego de aceitação/smoke usa X-Tollbooth-Internal: 1 ou X-Fresh-Internal: 1 para não poder ganhar crédito de estranho.

Portão de aceitação de produção

Cada deploy no Railway agora realiza verificações internas ao vivo contra o serviço em execução antes que /health possa retornar 200. O portão exercita REST, UNKNOWN, REUSE, REFETCH, recarga persistente de observações, initialize do MCP, descoberta de ferramentas MCP, fresh_check do MCP, e verifica que o autoteste controlado não aumenta a contagem de estranhos verificados.

Status

v0.1.2 infraestrutura de produção experimental. Prioridades: decisões conservadoras, baixa latência, economia de sub-centavo, aprendizado compartilhado seguro para privacidade, REST + MCP, observações duráveis e análises auditáveis de uso real.