Caching and freshness

Pipeworx caches tool results at the gateway with per-tool TTLs. Agents see the cache state in _meta.cache on every response, and can decide whether to trust prior data or re-call.

What every response tells you

{
  "result": {
    "content": [...],
    "_meta": {
      "cache": {
        "hit": false,
        "ttl_seconds": 300,
        "fresh_until": "2026-05-09T16:42:18Z"
      },
      "tier": "anonymous",
      "cost": { "total": 1, "components": [...] }
    }
  }
}

• hit — was this served from cache?
• ttl_seconds — how long this response remains in cache
• fresh_until — exact wall-clock time the cache entry expires

Why this matters for agents

Most agent failures fall into one of two cache-related buckets:

1. Re-using stale memory as fact. The agent called fred_get_series an hour ago, now is asked again, and just trusts its conversation history. If the data has updated, the agent’s “current value” is wrong.
2. Hammering the gateway. The agent re-calls every turn even when the data hasn’t moved.

Reading fresh_until resolves both. The agent should:

if (now < remembered_fresh_until) {
  // safe to reuse the prior response
} else {
  // re-call; the data may have changed
}

TTL by data class

The gateway sets TTL based on how often the underlying source actually changes. Rough buckets:

Look at ttl_seconds per call — it’s the authoritative number.

Writing cache-aware agents

In your agent’s loop:

1. Store fresh_until alongside results in your scratchpad/memory. When the agent later cites a number, check whether the source is still fresh.
2. Use remember for cross-session memory:

   remember({ key: "aapl_revenue_fy23", value: { value: 383300000000, fresh_until: "2026-05-09T..." } })

   Then recall and check the timestamp before reusing.
3. For long-lived sessions, refresh data when the agent’s task spans multiple fresh_until boundaries.

Cache misses and _meta.cost

A cache hit costs less than a miss in real terms (no upstream call), but the _meta.cost at gateway level is the same — Pipeworx charges per tool invocation, not per upstream call. The cost transparency exists so agents can budget; freshness is the orthogonal concern.

Forced refresh

If you must bypass cache (rare), append ?nocache=1 to the gateway URL:

https://gateway.pipeworx.io/mcp?nocache=1

Cache is then disabled for the connection. Counts every call against your daily quota with no caching benefit. Use sparingly.