rebrand as multicache

Author: Thomas Stromberg

Makefile

@@ -9,13 +9,13 @@ tag:
 	fi
 	@echo "=== Releasing $(VERSION) ==="
 	@echo ""
-	@echo "Step 1: Update submodule go.mod files to require sfcache $(VERSION)..."
-	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/sfcache v[^ ]*|github.com/codeGROOVE-dev/sfcache $(VERSION)|' {}
+	@echo "Step 1: Update submodule go.mod files to require multicache $(VERSION)..."
+	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/multicache v[^ ]*|github.com/codeGROOVE-dev/multicache $(VERSION)|' {}
 	@# Update store submodule dependencies (compress must be first as others depend on it)
-	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/sfcache/pkg/store/compress v[^ ]*|github.com/codeGROOVE-dev/sfcache/pkg/store/compress $(VERSION)|' {}
-	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/sfcache/pkg/store/localfs v[^ ]*|github.com/codeGROOVE-dev/sfcache/pkg/store/localfs $(VERSION)|' {}
-	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/sfcache/pkg/store/datastore v[^ ]*|github.com/codeGROOVE-dev/sfcache/pkg/store/datastore $(VERSION)|' {}
-	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/sfcache/pkg/store/valkey v[^ ]*|github.com/codeGROOVE-dev/sfcache/pkg/store/valkey $(VERSION)|' {}
+	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/multicache/pkg/store/compress v[^ ]*|github.com/codeGROOVE-dev/multicache/pkg/store/compress $(VERSION)|' {}
+	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/multicache/pkg/store/localfs v[^ ]*|github.com/codeGROOVE-dev/multicache/pkg/store/localfs $(VERSION)|' {}
+	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/multicache/pkg/store/datastore v[^ ]*|github.com/codeGROOVE-dev/multicache/pkg/store/datastore $(VERSION)|' {}
+	@find . -path ./go.mod -prune -o -name go.mod -print | xargs -I{} sed -i '' 's|github.com/codeGROOVE-dev/multicache/pkg/store/valkey v[^ ]*|github.com/codeGROOVE-dev/multicache/pkg/store/valkey $(VERSION)|' {}
 	@echo ""
 	@echo "Step 2: Commit go.mod changes..."
 	@git add -A
@@ -71,7 +71,7 @@ bench:
 # 4. Meta Trace Hit Rate (real-world)
 # 5. Zipf Hit Rate (synthetic)
 benchmark:
-	@echo "=== sfcache Benchmark Suite ==="
+	@echo "=== multicache Benchmark Suite ==="
 	@cd benchmarks && go test -run=TestBenchmarkSuite -v -timeout=300s
 
 clean:

README.md

@@ -1,14 +1,14 @@
-# sfcache - Stupid Fast Cache
+# multicache - Stupid Fast Cache
 
-<img src="media/logo-small.png" alt="sfcache logo" width="256">
+<img src="media/logo-small.png" alt="multicache logo" width="256">
 
-[![Go Reference](https://pkg.go.dev/badge/github.com/codeGROOVE-dev/sfcache.svg)](https://pkg.go.dev/github.com/codeGROOVE-dev/sfcache)
-[![Go Report Card](https://goreportcard.com/badge/github.com/codeGROOVE-dev/sfcache)](https://goreportcard.com/report/github.com/codeGROOVE-dev/sfcache)
+[![Go Reference](https://pkg.go.dev/badge/github.com/codeGROOVE-dev/multicache.svg)](https://pkg.go.dev/github.com/codeGROOVE-dev/multicache)
+[![Go Report Card](https://goreportcard.com/badge/github.com/codeGROOVE-dev/multicache)](https://goreportcard.com/report/github.com/codeGROOVE-dev/multicache)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 <br clear="right">
 
-sfcache is the fastest in-memory cache for Go. Need multi-tier persistence? We have it. Need thundering herd protection? We've got that too.
+multicache is the fastest in-memory cache for Go. Need multi-tier persistence? We have it. Need thundering herd protection? We've got that too.
 
 Designed for persistently caching API requests in an unreliable environment, this cache has an abundance of production-ready features:
 
@@ -33,10 +33,10 @@ Designed for persistently caching API requests in an unreliable environment, thi
 As a stupid-fast in-memory cache:
 
 ```go
-import "github.com/codeGROOVE-dev/sfcache"
+import "github.com/codeGROOVE-dev/multicache"
 
 // strings as keys, ints as values
-cache := sfcache.New[string, int]()
+cache := multicache.New[string, int]()
 cache.Set("answer", 42)
 val, found := cache.Get("answer")
 ```
@@ -45,12 +45,12 @@ Or as a multi-tier cache with local persistence to survive restarts:
 
 ```go
 import (
-  "github.com/codeGROOVE-dev/sfcache"
-  "github.com/codeGROOVE-dev/sfcache/pkg/store/localfs"
+  "github.com/codeGROOVE-dev/multicache"
+  "github.com/codeGROOVE-dev/multicache/pkg/store/localfs"
 )
 
 p, _ := localfs.New[string, User]("myapp", "")
-cache, _ := sfcache.NewTiered(p)
+cache, _ := multicache.NewTiered(p)
 
 cache.SetAsync(ctx, "user:123", user) // Don't wait for the key to persist
 cache.Store.Len(ctx)                  // Access persistence layer directly
@@ -59,29 +59,29 @@ cache.Store.Len(ctx)                  // Access persistence layer directly
 With S2 compression (fast, good ratio):
 
 ```go
-import "github.com/codeGROOVE-dev/sfcache/pkg/store/compress"
+import "github.com/codeGROOVE-dev/multicache/pkg/store/compress"
 
 p, _ := localfs.New[string, User]("myapp", "", compress.S2())
 ```
 
 How about a persistent cache suitable for Cloud Run or local development? This uses Cloud DataStore if available, local files if not:
 
 ```go
-import "github.com/codeGROOVE-dev/sfcache/pkg/store/cloudrun"
+import "github.com/codeGROOVE-dev/multicache/pkg/store/cloudrun"
 
 p, _ := cloudrun.New[string, User](ctx, "myapp")
-cache, _ := sfcache.NewTiered(p)
+cache, _ := multicache.NewTiered(p)
 ```
 
 ## Performance against the Competition
 
-sfcache prioritizes high hit-rates and low read latency. We have our own built in `make bench` that asserts cache dominance:
+multicache prioritizes high hit-rates and low read latency. We have our own built in `make bench` that asserts cache dominance:
 
 ```
 >>> TestLatencyNoEviction: Latency - No Evictions (Set cycles within cache size) (go test -run=TestLatencyNoEviction -v)
 | Cache         | Get ns/op | Get B/op | Get allocs | Set ns/op | Set B/op | Set allocs |
 |---------------|-----------|----------|------------|-----------|----------|------------|
-| sfcache       |       7.0 |        0 |          0 |      23.0 |        0 |          0 |
+| multicache       |       7.0 |        0 |          0 |      23.0 |        0 |          0 |
 | lru           |      23.0 |        0 |          0 |      23.0 |        0 |          0 |
 | ristretto     |      28.0 |       13 |          0 |      77.0 |      118 |          3 |
 | otter         |      34.0 |        0 |          0 |     160.0 |       51 |          1 |
@@ -94,7 +94,7 @@ sfcache prioritizes high hit-rates and low read latency. We have our own built i
 >>> TestLatencyWithEviction: Latency - With Evictions (Set uses 20x unique keys) (go test -run=TestLatencyWithEviction -v)
 | Cache         | Get ns/op | Get B/op | Get allocs | Set ns/op | Set B/op | Set allocs |
 |---------------|-----------|----------|------------|-----------|----------|------------|
-| sfcache       |       7.0 |        0 |          0 |      94.0 |        0 |          0 |
+| multicache       |       7.0 |        0 |          0 |      94.0 |        0 |          0 |
 | lru           |      24.0 |        0 |          0 |      83.0 |       80 |          1 |
 | ristretto     |      31.0 |       14 |          0 |      73.0 |      119 |          3 |
 | otter         |      34.0 |        0 |          0 |     176.0 |       61 |          1 |
@@ -110,7 +110,7 @@ sfcache prioritizes high hit-rates and low read latency. We have our own built i
 
 | Cache         | QPS        |
 |---------------|------------|
-| sfcache       |  100.26M   |
+| multicache       |  100.26M   |
 | lru           |   44.58M   |
 | tinylfu       |   18.42M   |
 | freecache     |   14.07M   |
@@ -125,7 +125,7 @@ sfcache prioritizes high hit-rates and low read latency. We have our own built i
 
 | Cache         | QPS        |
 |---------------|------------|
-| sfcache       |   36.46M   |
+| multicache       |   36.46M   |
 | freecache     |   15.00M   |
 | ristretto     |   13.47M   |
 | otter         |   10.75M   |
@@ -140,7 +140,7 @@ sfcache prioritizes high hit-rates and low read latency. We have our own built i
 
 | Cache         | 50K cache | 100K cache |
 |---------------|-----------|------------|
-| sfcache       |   71.16%  |   78.30%   |
+| multicache       |   71.16%  |   78.30%   |
 | otter         |   41.12%  |   56.34%   |
 | ristretto     |   40.35%  |   48.99%   |
 | tinylfu       |   53.70%  |   54.79%   |
@@ -155,7 +155,7 @@ sfcache prioritizes high hit-rates and low read latency. We have our own built i
 
 | Cache         | Size=1% | Size=2.5% | Size=5% |
 |---------------|---------|-----------|---------|
-| sfcache       |  63.80% |    68.71% |  71.84% |
+| multicache       |  63.80% |    68.71% |  71.84% |
 | otter         |  61.77% |    67.67% |  71.33% |
 | ristretto     |  34.91% |    41.23% |  46.58% |
 | tinylfu       |  63.83% |    68.25% |  71.56% |
@@ -171,22 +171,31 @@ Want even more comprehensive benchmarks? See https://github.com/tstromberg/gocac
 
 ### Differences from the S3-FIFO paper
 
-sfcache implements the core S3-FIFO algorithm (Small/Main/Ghost queues with frequency-based promotion) with these optimizations:
+multicache implements the core S3-FIFO algorithm (Small/Main/Ghost queues with frequency-based promotion) with these optimizations:
 
 1. **Dynamic Sharding** - 1-2048 independent S3-FIFO shards (vs single-threaded) for concurrent workloads
 2. **Bloom Filter Ghosts** - Two rotating Bloom filters track evicted keys (vs storing actual keys), reducing memory 10-100x
 3. **Lazy Ghost Checks** - Only check ghosts when evicting, saving 5-9% latency when cache isn't full
 4. **Intrusive Lists** - Embed pointers in entries (vs separate nodes) for zero-allocation queue ops
 5. **Fast-path Hashing** - Specialized for `int`/`string` keys using wyhash and bit mixing
 
-### Adaptive Enhancements
+### Adaptive Mode Detection
 
-Beyond the core algorithm, sfcache includes optimizations discovered through benchmarking:
+multicache automatically detects workload characteristics and adjusts its eviction strategy using ghost hit rate (how often evicted keys are re-requested):
 
-- **Scan Detection** - If ghost hit rate <5%, switches to pure recency mode (matches Clock on scan-heavy traces)
-- **Adaptive Queue Sizing** - Larger small queue (20%) for small caches, paper's 10% for large
-- **Ghost Boost** - Returning items start with freq=1 instead of 0
-- **Pressure-Aware Promotion** - Lowers threshold when small queue >80% full
+| Mode | Ghost Rate | Strategy | Best For |
+|------|------------|----------|----------|
+| 0 | <1% | Pure recency, skip ghost tracking | Scan-heavy workloads |
+| 1 | 1-6% or 13-22% | Balanced, promote if freq > 0 | Mixed workloads |
+| 2 | 7-12% | Frequency-heavy, promote if freq > 1 | Frequency-skewed workloads |
+| 3 | ≥23% | Clock-like, all items to main with second-chance | High-recency workloads |
+
+Mode 2 uses **hysteresis** to prevent oscillation: entry requires 7-12% ghost rate, but stays active while rate is 5-22%.
+
+### Other Optimizations
+
+- **Adaptive Queue Sizing** - Small queue is 20% for caches ≤32K, 15% for ≤128K, 10% for larger (paper recommends 10%)
+- **Ghost Frequency Boost** - Items returning from ghost start with freq=1 instead of 0
 - **Higher Frequency Cap** - Max freq=7 (vs 3 in paper) for better hot/warm discrimination
 
 ## License

benchmarks/README.md

@@ -1,4 +1,4 @@
-# sfcache Benchmarks
+# multicache Benchmarks
 
 This directory contains comparison benchmarks against popular Go cache libraries.
 
@@ -32,7 +32,7 @@ Your mileage **will** vary based on:
 
 ### The Real Differentiator: Persistence
 
-**sfcache's primary advantage isn't raw speed or hit rates** - it's the automatic per-item persistence designed for unreliable cloud environments:
+**multicache's primary advantage isn't raw speed or hit rates** - it's the automatic per-item persistence designed for unreliable cloud environments:
 
 - **Cloud Run** - Instances shut down unpredictably after idle periods
 - **Kubernetes** - Pods can be evicted, rescheduled, or killed anytime
@@ -87,7 +87,7 @@ go test -bench=BenchmarkSpeed -benchmem
 ```
 
 Compares raw Get operation performance across:
-- sfcache (S3-FIFO)
+- multicache (S3-FIFO)
 - golang-lru (LRU)
 - otter (S3-FIFO with manual persistence)
 - ristretto (TinyLFU)