Choosing a cache eviction policy is a decision most projects make once, from intuition, and never revisit. The trouble is that the right answer depends on traffic you have not seen yet, and it is not stable: replayed against six published production traces, four different policies win, and the strongest general-purpose baseline of them all comes near the bottom on one. Guessing wrong is not a rounding error either — on one of those traces seven of the nine policies here serve 0.0% while one serves 45%.
as-cache makes the choice at runtime instead. One policy is active and serves every request. The others run as shadows: they see each key but never its value, and answer "would I have had this?" Once per epoch every arm reports its hit rate, a multi-armed bandit names the winner, and the cache switches if the win is worth the migration. There is also an observe-only mode where nothing ever switches and the library simply tells you which policy your traffic wants — often the more useful half of it.
It is pre-1.0, the API may still change, and nothing here has run in production that I know of. What it does have is measurement: every claim in these documents comes from a reproducible run against published traces, and the concurrency has been exercised under the race detector and adversarially reviewed. The numbers are all in the evidence, so you do not have to take "experimental" or "production-ready" on trust.
| Document | Contents |
|---|---|
| Getting started | Install, a working example, and the AdaptiveCache API |
| Design | How it works per request and per epoch, when it fits, the Bandit interface, what is not done |
| Configuration | Every Settings field, migration strategies, sampling, stability gates, tuning |
| Policies | The nine ready-made arms, their caveats, adapting your own cache |
| Advisor mode | ObserveOnly, Advice(), and the metrics module |
| Evidence | Every measured claim: policy tables, competing libraries, real traces, sampling fidelity, fleets |
| Benchmarking | Reproducible replays, benchclient, make evidence |
| Running a fleet | Pooling evidence across replicas through Valkey or Redis |
| Project site | Landing page, plus an interactive explorer of the bandit's decisions on a phase-shift run |
Past releases are recorded in the changelog and in docs/release-notes-*.md, which are kept as published rather than updated.
Mozilla Public License 2.0 — file-level copyleft. You may use this library in a closed-source application without opening your own code; if you modify one of these files and distribute the result, that file's source must be made available under the same licence. Each publishable module carries its own copy, because a Go module zip contains only its own directory.