Caching
Cache repeated context, not user reality
Caching should reduce repetition without freezing the user model for too long. The safest starting point is conditional context reads with explicit cache-shape tracking.
Use caching to reduce repetition, not hide important changes
Good caching preserves freshness for eventful flows and efficiency for repeated reads.
Caching Layers
Think in terms of shape, freshness, and invalidation evidence.
Conditional Reads
ETag-based revalidation is the safest first optimization.
- Store ETag together with view and expand parameters.
- Replay it with `If-None-Match` on identical reads.
- Treat `304` as a healthy optimization path.
Shape Awareness
Know exactly which response shape you cached.
- Record whether the payload was compact, full, or expanded.
- Include shaping params in the cache key.
- Prefer compact reads as the default cacheable surface.
Invalidation
Drop or revalidate the cache when workflow evidence says the user model changed.
- Resume uploads and assessment completion are natural invalidation triggers.
- Webhook events can wake up revalidation.
- Do not reuse cached payloads across unrelated workflows.
Start with ETag before inventing custom cache logic
`/api/v1/context` already supports conditional requests on cache-friendly shapes, which makes native revalidation the cleanest first move.
- Persist the last ETag beside the cached payload.
- Send it only for the exact same request shape.
- Treat cache misses and cache revalidation as normal runtime behavior.
Keep caching decisions tied to workflow evidence
The runtime should invalidate cached context when it observes product events that could change reasoning quality.
- Use shorter freshness windows for dynamic or volatile reads.
- Use re-fetch after profile edits, resume parsing, or new assessments.
- Avoid long-lived caches that the runtime cannot explain later.
Caching Comparison
Not every response shape deserves the same caching posture.
| Shape | Default posture | Why |
|---|---|---|
| Compact context | Best default for conditional caching. | It is high-signal and comparatively stable. |
| Expanded dynamic context | Use short windows or bypass longer caches. | Recent events and relevance can change quickly. |
| Health / alert-heavy reads | Revalidate aggressively or fetch fresh. | Operational signals can become stale fast. |
Decision Matrix
Use this to choose a caching move based on workflow shape.
Situation
The same compact read happens repeatedly
Action
Store the ETag and revalidate conditionally.
Why
It cuts repeated payload transfer without inventing a custom policy first.
Situation
The task depends on recent events
Action
Use shorter cache windows or fetch fresh state.
Why
Dynamic context can drift quickly.
Situation
A webhook or product event changes the user model
Action
Invalidate the cached entry and pull a fresh read.
Why
Downstream reasoning should not rely on stale identity signals.
Conditional request examples
ETag-based reads are the safest first optimization for repeated context access.
curl "https://api.profileclaw.com/api/v1/context" -H "Authorization: Bearer $PROFILECLAW_API_KEY"curl "https://api.profileclaw.com/api/v1/context" -H "Authorization: Bearer $PROFILECLAW_API_KEY" -H 'If-None-Match: "<etag-from-previous-response>"'Next surfaces
After caching is stable, tighten retries and continuation behavior too.