How Freshness Validator works
The service monitors the sources you register, then scores the context your agents send against what it last saw.
1. Register sources
Agents or operators register the public URLs that feed agent context. Each source gets a check schedule of 1h, 6h, 24h, 7d, or 30d. Registration costs 2 validation calls.
POST /api/v1/source/register
{
"source_url": "https://example.com/compliance-policy",
"check_frequency": "24h"
}2. Monitoring
A scheduled job runs every 15 minutes and fetches the registered sources that are due for a check. It strips scripts, styles, and markup, reduces the page to lowercase words, and hashes that text with SHA-256. If the hash differs from the last check, the source is flagged as changed. Restyling a page does not trigger a flag, but any edit to its text does.
When a source changes, it is flagged with a last_changed timestamp. Any context validated before that time may be stale.
3. Validation
When an agent sends context, the score combines three signals:
| Signal | Weight | What it measures |
|---|---|---|
| Time decay | 30% | Starts at 100 and falls to 75 across the agent's freshness policy window. After that, it drops 50 points for each additional window. Skipped (scores 100) if you do not send last_validated. |
| Source authority | 30% | 20 if the monitored source changed after last_validated, 60 if its recent checks failed, 85 if it is monitored but there is no last_validated to compare, 100 if monitored and unchanged. Unmonitored sources get a neutral 75. |
| Content match | 40% | The share of your context's 5-word shingles found in the source's stored text, or 100 for an exact match. Paraphrased summaries (content_type paraphrase) are scored on the share of their keywords found in the source. Without a monitored source this signal is a neutral 75. |
4. Response
The response includes a score from 0 to 100, a stale flag, a confidence value, flagged issues, and suggestions. If the agent has insufficient credits, the result is still returned with HTTP status 402.
{
"freshness_score": 68,
"is_stale": true,
"confidence": 0.85,
"flagged_issues": ["Source content changed after this context was last validated"],
"suggestions": ["Re-fetch the content from its source and validate again"],
"source_match": { "method": "overlap", "overlap": 0.95 },
"source_status": "monitored",
"credits_deducted": 0.03,
"remaining_balance": 4.97
}Score thresholds
| Score | State | Suggested action |
|---|---|---|
| 80 and above | Fresh | Context is current and reliable. |
| 70 to 79 | Warning | Context is approaching stale. Consider refreshing it. |
| Below 70 | Stale | The agent should re-fetch from the source. |
The is_stale flag is true when the score is below 70.