FreshContext

I asked Claude to help me find a job. It gave me a list of openings. I applied to three of them. Two didn't exist anymore. One had been closed for two years.

Claude had no idea. It presented everything with the same confidence.

That's the problem freshcontext fixes.

This repository is the integrated FreshContext Core/MCP package. FreshContext is the context judgment layer between retrieval and reasoning. Core is the reusable engine that scores, ranks, explains, and turns candidate context into decision-ready context; MCP is the first live host/interface over that engine.

Live demo: freshcontext-mcp.gimmanuel73.workers.dev/demo — same model, same query, two completely different answers. Only the temporal layer changed.

The problem

Large language models retrieve web data semantically. Cosine similarity finds the documents that match a query best — but cosine doesn't know when a document was written.

So a 2022 blog post and a 2026 paper can score nearly identically. The model gets a context window full of stale documents and faithfully summarizes 2022 advice for a 2026 question.

That's not hallucination. That's correct summarization of corrupted retrieval.

Most RAG pipelines rank context correctly semantically but incorrectly temporally.

The layer

FreshContext is context integrity infrastructure for AI agents and retrieval systems. It sits between retrieval and reasoning:

candidate context
  -> FreshContext Core
  -> decision-ready context
  -> model / agent / app

FreshContext evaluates freshness, source profile, confidence, utility, provenance material, and failure honesty before context reaches the LLM. The temporal core uses Decay-Adjusted Relevancy:

R_t = R_0 · e^(−λt)

• R_0 — base semantic relevancy (whatever your retriever already gives you)
• λ — source-specific decay constant (HN ≈14h half-life, blogs ≈29d, academic papers ≈1.6y)
• t — hours elapsed since publication
• R_t — decay-adjusted relevancy at query time

That's the core correction. No model swap. No re-embedding. No re-indexing. The layer drops onto whatever retrieval pipeline you already have.

The layer is the product. The named adapters shipped with this repo demonstrate compatibility across different source classes. The DAR engine, the freshness envelope, Source Profiles, and the FreshContext Specification are the moat.

The standard

Every FreshContext-compatible response wraps content in a structured envelope:

[FRESHCONTEXT]
Source: https://github.com/owner/repo
Published: 2024-11-03
Retrieved: 2026-03-05T09:19:00Z
Confidence: high
---
... content ...
[/FRESHCONTEXT]

When it was retrieved. Where it came from. How confident we are the date is accurate.

The FreshContext Specification v1.2 is published as an open standard under MIT licence. Any tool, agent, or system that wraps retrieved data in this envelope is FreshContext-compatible. → Read the spec · Read the methodology

Architecture boundary

FreshContext Core is the reusable center of the current integrated package. It owns signal normalization, freshness scoring, Source Profiles, decision output, envelope formatting, failure guards, shared types, rank/explain primitives, and the context-conditioned utility primitive.

MCP is the primary reference/interface implementation over Core. Claude Desktop is supported, but not required. The MCP tool surface exposes named reference adapters and a live interface for using the system.

The production Cloudflare Worker now uses Core-backed envelope generation. Worker-specific concerns remain outside Core: MCP transport, runtime guards, KV cache policy, cache metadata injection, JSON parse/replace cache helpers, D1 feeds, cron, rate limiting, and Store/feed scoring/provenance.

See Core / MCP Boundary for the current package boundary and the staged path toward a future standalone Core package.

Core import path

FreshContext Core is also available directly from the current MCP package:

import {
  evaluateSignals,
  interpretEvaluations,
  getSourceProfile,
  normalizeSignal,
  calculateHaPriV2,
} from "freshcontext-mcp/core";

This is a Core subpath export inside freshcontext-mcp, not a standalone freshcontext-core package yet. The root package and freshcontext-mcp binary remain the MCP reference host.

Primary MCP interface

The clearest MCP path is evaluate_context.

It accepts candidate context from any retriever, agent, database, local script, note parser, or adapter output:

{
  "profile": "academic_research",
  "intent": "citation_check",
  "signals": [
    {
      "title": "Example source",
      "content": "Candidate context text...",
      "source": "https://example.com/source",
      "source_type": "arxiv",
      "published_at": "2026-05-24T12:00:00.000Z",
      "retrieved_at": "2026-05-24T13:00:00.000Z",
      "semantic_score": 0.92
    }
  ]
}

FreshContext returns decision-first output:

• Decision
• Meaning
• Action
• Warnings
• Source
• Freshness
• Rank score
• Utility
• Confidence
• Why

Structured results also include a readable object for humans:

{
  "decision": "cite_as_primary",
  "label": "Cite as primary",
  "readable": {
    "label": "Primary source",
    "summary": "This source is strong enough to use as main evidence.",
    "why": [
      "Strong semantic match and current freshness for arxiv.",
      "source profile academic_research uses lenient date policy",
      "intent profile citation_check selected"
    ],
    "action": "Use this as main evidence while preserving citation and provenance.",
    "warnings": [
      "FreshContext judges citation readiness and context usefulness; it does not certify truth."
    ]
  }
}

The readable object translates Core decisions into user-facing language. It does not change ranking, decision labels, utility scoring, or source intake. Utility helps explain usefulness for the current question; it remains explanatory and does not control default decision labels or ranking.

FreshContext does not certify truth. It records why context was used, supported, questioned, refreshed, watched, or excluded before it reaches a model.

evaluate_context does not fetch URLs, crawl, scrape, browse, read folders, or call adapters. It only evaluates candidate context the caller provides.

Current boundary: evaluate_context ships in the npm/local stdio MCP server. The hosted Cloudflare Worker MCP endpoint is a separate deployment surface and is verified independently — check /v1/health for its live version and tool count rather than assuming parity with the package. The Worker remains a separate deployment surface, so future package interfaces should be re-verified remotely before being claimed live.

Network Boundary

FreshContext's primary evaluate_context path does not fetch, crawl, scrape, browse, read folders, or call adapters. The MCP package also includes read-only reference adapters that use network access only when those adapter tools are invoked. Supply-chain scanners may therefore report package network access; that applies to the optional adapter surface, not to caller-provided context evaluation.

Advanced Worker/feed surface

Beyond the per-call Core/MCP paths, the production Worker deployment exposes a continuous, decay-scored, deduplicated feed. This is an advanced deployment surface, not the required way to use FreshContext Core:

GET /v1/intel/feed/:profile_id?limit=20&min_rt=0

Every signal is stamped with base_score, rt_score, entropy_level (low / stable / high), ha_pri_sig (Ha-Pri v1 SHA-256 provenance reference), semantic_fingerprint (cross-adapter dedup), and published_at. Ready for direct LLM or agent consumption — no synthesis required.

Production endpoint: https://freshcontext-mcp.gimmanuel73.workers.dev

Reference adapters

The repo ships named reference adapters that demonstrate how different source classes can become FreshContext-compatible. Each adapter keeps its own name because it represents a source boundary; the adapter count is operational proof, not the product headline.

Intelligence

Competitive research

Market data