Grilling: what a Resource cache hit means

[antejavor]

Part of #454

Question

What does a cache hit mean? (a) Recall-side: the agent (via the recall MCP tool or injected context) learns "you already read this, here's the gist and when" and decides itself whether to re-fetch; (b) interception: a PreToolUse hook serves stored content instead of letting the fetch run; or both. For the "go over 500 Memgraph issues again" case: what gets served, how is staleness judged against GitHub freshness signals, and what happens when stored content is too old?

[antejavor]

Input from GitHub identity and freshness research: with no token the harness gets 60 REST calls/h and no GraphQL, and 304s still cost. Decide whether the Resources component ever re-validates freshness itself, or only serves the cache with a staleness mark and leaves re-fetching to the agent. Open: do reactions, label changes and PR review comments bump updated_at like comments do? If not, one timestamp doesn't cover a cached PR thread.

[antejavor]

Input from how GitHub resource reads appear in harness hook payloads: hooks can't swap tool output uniformly across harnesses, and a cached WebFetch answer is specific to the prompt it was asked with — the research argues cache hits must be served via recall rather than interception. Weigh that here.

[antejavor]

Resolution — address-keyed resource tool, non-blocking nudge, facts not verdicts

Built on Resource capture model and Resources component placement and Resource ownership.

1. Mechanism. resources-graph's own address-keyed resource(address) Tool, served by agent-context-graph mcp like recall, with a session_hint ("before fetching GitHub issues/PRs/repos, check resource"). A cache lookup is an exact-identity question, not semantic search; the listing-plus-filters key from the capture model only works address-keyed. recall stays memory — Resources may feed it later via Chunks (fog), but that isn't a cache hit. No tool-output interception (not uniform across harnesses; a cached WebFetch answer is prompt-specific).
2. Nudge, never block. On a fetch-like PreToolUse, extract the Address and do one indexed lookup; on a hit, inject one non-blocking line ("[master < T0499-MG] Add automated build of all Memgraph packages memgraph#123 is in memory, fetched 2h ago, updated_at 3d ago — resource returns it") where the harness can add context without denying. The fetch always runs. Harnesses without that capability get the session hint only. No GitHub call in the hook.
3. Freshness: facts, not verdicts; touch-driven refresh. The resource tool never calls GitHub — it returns content + fetched_at + source updated_at and the model judges staleness for its task. No TTL, no background crawl. Only a real re-fetch (WebFetch / gh / MCP) — the model's judgement that memory was too stale — makes the next Sweep revalidate: conditional request for items, since=<last fetched_at> for listings. Whether reactions/labels/review comments bump updated_at is verified in GitHub Resource graph model; if not, the Sweep checks an extra signal for PRs.
4. Listings return an index: one row per member (number, title, state, labels, updated_at, comment count) + the listing's fetched_at and member count, paged/bounded. Members are read one at a time at full capture depth (body + all comments).
5. Matching. Exact normalised match, plus subsumption for structured filters (state, labels, author, assignee, milestone): a cached superset listing answers by filtering stored members locally, labelled "derived from '' fetched ". Free-text search (q= / --search) is exact-only. Only a fully expanded listing can subsume (a --limit-truncated one never answers a broader request).
6. A cache read is a Touch: provenance FETCHED, marked served from memory, outcome hit / subsumed / miss. It does not trigger refresh. A miss followed by a real fetch is normal first contact.

Follow-up issue: track and analyse memory served to and used by the model, covering both recall and resource.