HeatherDB.
Benchmarked.
HeatherDB is read-optimized. Writes organize and persist the memory so reads can stay fast. These CPU benchmarks show the cost of each, measured on an Apple M4. The source revision, settings and raw samples accompany each measurement.
The machine. The method.
- Processor / memory
- Apple M4 / 16 GiB
- Operating system
- macOS 26.5.1 · arm64
- Engine revision
- 0e08be78b716 · unmodified engine source
- Build
- rustc 1.97.1 (8bab26f4f 2026-07-14) · optimized bench profile
- Sampling
- Criterion 0.8.2 · 20 samples · 1 s warm-up · 2 s target measurement per case
- Memory configuration
- Engine defaults: data-seeded locations (l₀ = 0), k = 20, β = 5, up to 10 read iterations
Tests ran sequentially on a developer machine using temporary LMDB storage. Input vectors were generated from an unseeded normal distribution and normalized. The figures are Criterion sample means; intervals describe uncertainty in that mean, not p95 request latency.
Read latency, across dimensions.
Iterative reads against a collection pre-filled with 200 random vectors. The test cycles through 100 random queries; it measures execution time, not whether a query recalls the right memory.
| Workload | Mean time | 95% confidence interval | Samples |
|---|---|---|---|
| 64 dimensions | 17.47 µs | 15.17 µs – 20.45 µs | 20 |
| 128 dimensions | 32.39 µs | 32.28 µs – 32.49 µs | 20 |
| 384 dimensions | 120.07 µs | 119.66 µs – 120.53 µs | 20 |
The cost of a write.
HeatherDB prioritizes read performance over write throughput. A write updates the learned memory and persists the change, doing more work than a read. This test measures one vector per call, cycling through 1,000 generated vectors in a collection that continues adapting during warm-up and measurement.
| Workload | Mean time | 95% confidence interval | Samples |
|---|---|---|---|
| 64 dimensions | 5.09 ms | 4.94 ms – 5.24 ms | 20 |
| 128 dimensions | 5.23 ms | 5.05 ms – 5.44 ms | 20 |
| 384 dimensions | 5.27 ms | 5.03 ms – 5.52 ms | 20 |
Write together.
Amortise the transaction.
The same 100-vector workload at 128 dimensions, using individual calls or one batch call. Each iteration starts from a new collection pre-filled with 200 vectors. Setup is excluded; the timed closure includes writes and scope teardown.
| Workload | Mean time | 95% confidence interval | Samples |
|---|---|---|---|
| 100 individual writes | 526.41 ms | 510.39 ms – 541.27 ms | 20 |
| 100 vectors · one batch | 12.46 ms | 11.45 ms – 13.38 ms | 20 |
One batch took 12.46 ms, compared with 526.41 ms for individual writes: approximately 42.3× faster in this test. This is the vector-only write path; metadata-bearing document writes are not covered.
Learning on. Learning off.
The same write workload in both modes, measured on released HeatherDB 1.0.0. Competitive writes select and adapt memory locations. Plain writes append separate locations. Both persist changes with synchronous durability.
| Workload | Competitive · learning on | Plain · learning off | Competitive / plain |
|---|---|---|---|
| One vector · one call | 4.72 ms | 4.39 ms | 1.08×95% CI 0.98 – 1.17× |
| 100 vectors · individual calls | 460.64 ms | 368.01 ms | 1.25×95% CI 1.23 – 1.27× |
| 100 vectors · one batch | 9.92 ms | 4.19 ms | 2.37×95% CI 2.15 – 2.65× |
Each pair uses identical seeded random unit vectors and fresh temporary databases. Mode order alternates; two warm-up pairs per workload are excluded. Prefill, input generation and teardown are outside timing. The 100-vector rows are totals, not per-vector latency. These samples cover small collections of mostly distinct patterns, not sustained ingestion or repeated-example learning.
Plain mode is faster in the 100-vector workloads here. The single-write ratio interval includes 1×, so that case does not establish a clear speed difference. Intervals use 10,000 paired bootstrap resamples; they describe uncertainty in the ratio of means, not request p95.
Disk commits remain part of both paths. Plain mode adds a location for every observation, trading adaptation for a growing representation. Competitive mode may consolidate observations, so equal input counts do not imply equal location counts; those counts are recorded in the raw samples. This is a separate matched experiment from the Criterion results above.
Reproduce the comparison
Check out source 67adcda76e04. Save the benchmark source as heather_db/examples/write_modes.rs, then run:
cargo run --release --locked -p heather_db --example write_modes > write-modes.jsonlThe JSON report includes the source hash, hardware, raw timings, location counts and paired bootstrap confidence intervals. Native calls exclude HTTP, authentication, embeddings and document metadata.
Through authenticated HTTP.
Sequential loopback requests to a 64-dimensional plain memory with 32 vectors. Each request opens a new connection and includes client JSON work, transport, authentication and the read.
| Authentication | Mean round trip | Observed request p95 |
|---|---|---|
| Basic | 11.095 ms | 12.368 ms |
| Bearer | 0.249 ms | 0.275 ms |
Basic was measured before Bearer on a shared developer machine. These are observed request percentiles, not Criterion confidence intervals or a production latency guarantee. No concurrent-load throughput is inferred.
Download measurement evidenceLearning, measured separately.
Competitive mode supports associative recall and shared-pattern learning. Plain mode keeps each vector as a separate location. Reconstruction and held-out learning are measured separately.
| Method | Mean cosine |
|---|---|
| Noisy input | 0.8009 |
| Competitive default | 0.9941 |
| Plain: all observations | 0.9689 |
| Reservoir: same location count | 0.9581 |
| Online k-means: same location count | 0.9968 |
Eight latent patterns, 128 dimensions, 1,024 noisy training observations and independent held-out examples; common attention scale 50. Latent prototypes were never written. Default held-out cosine is 0.9547 at 64 observations and 0.9941 at 1,024. Clustering remains a strong baseline.
When patterns rotate by 45°, fidelity to the new patterns moves from 0.6939 to 0.9920, while fidelity to the old patterns moves from 0.9799 to 0.7109. These checkpoints measure adaptation and retention; they do not define a guaranteed forgetting schedule or secure deletion.
Associative recall.
32 seeded random unit patterns, 64 dimensions and every fourth coordinate erased from each cue. Both modes reconstruct patterns; read settings and the write representation affect the result.
| Write mode and readout | Mean cosine | Fraction at cosine ≥ 0.9 |
|---|---|---|
| Competitive · default β=5 · iterative | 0.8844 | 59.375% |
| Competitive · explicit β=50 · iterative | 0.8977 | 65.625% |
| Plain · attention scale=50 | 1.0000 | 100.000% |
Competitive mode allocates novel patterns independently and updates shared structure for joining observations. Plain mode preserves separate vector locations. These scores do not guarantee exact recall on other data, and a reconstructed vector does not provide document identity.
These results establish neither semantic reasoning nor new scientific discovery. Discovery candidates need independent validation; native memory does not automatically reject unknown queries.
Run it on your hardware.
Check out the measured revision of the engine, then run these commands. They use the existing benchmark suite without changing engine code.
git clone https://github.com/aphorion/heatherdb
cd heatherdb
git checkout 0e08be78b7164b3733f7d60654b73f6a1862ec08cargo bench --locked -p heather_db --bench read_latency -- read/dimension --sample-size 20 --warm-up-time 1 --measurement-time 2cargo bench --locked -p heather_db --bench write_throughput -- write/single --sample-size 20 --warm-up-time 1 --measurement-time 2cargo bench --locked -p heather_db --bench write_throughput -- 'write/batch/(individual|batch)/100$' --sample-size 20 --warm-up-time 1 --measurement-time 2Criterion writes estimates and samples under target/criterion/. Each case has 20 samples; slow operations can extend the target measurement time. Random inputs, thermal conditions, storage and other processes can change your results.
What these results establish.
Engine execution time
Native timings are local Rust calls, excluding HTTP, authentication, network, JSON parsing and embeddings. The separate HTTP table includes client and transport overhead. There is no concurrent HTTP load test here, and no sustained-throughput claim derived from latency.
A specific workload
This run covers small, synthetic collections on one machine. Performance timings do not establish recall quality. The separate synthetic learning and recall tests have their own stated conditions; neither establishes large-scale behaviour, general reasoning or universal superiority.
Your next measurement
Evaluate partial-cue recall, interference and unknown queries on your data. Then measure your end-to-end API latency, concurrency and storage requirements.
Memory boundaries