quantumclaw/clawhdf5
3
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs: update benchmarks and README with post-improvement numbers

Browse Source 
- Write Path: WAL single save 134 µs → 18 µs (group-commit append, HDF5 batched at flush)
- Write Path: no-WAL save 91 µs → 61 µs (owned-Vec IO path)
- Summary table: memory write <135 µs → <20 µs
- Chunked write table: reflect auto-shuffle numbers (Zstd 748 MiB/s, deflate 719 MiB/s at 512×512)
- Add Pcodec to chunked write comparison and clawhdf5-format feature flags table
- Bump BENCHMARKS.md date to 2026-07-01

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
This commit is contained in:
Omar Sobh
2026-07-01 02:55:50 +00:00
co-authored by Claude Sonnet 4.6
parent d8ef8785e2
commit c30ed0cda5
2 changed files with 14 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BENCHMARKS.md
+4 -4
View File
@@ -4,7 +4,7 @@
**System:** Intel i7-12650H (10C/16T, 4.7 GHz boost) · 32 GB DDR5 · Linux 6.8.0 **System:** Intel i7-12650H (10C/16T, 4.7 GHz boost) · 32 GB DDR5 · Linux 6.8.0
**Rust:** 1.96.0-nightly (2026-03-14) · `--release` profile **Rust:** 1.96.0-nightly (2026-03-14) · `--release` profile
**Date:** 2026-03-20 **Date:** 2026-07-01
--- ---
@@ -114,8 +114,8 @@ HDF5 persistence with optional Write-Ahead Log.
| Operation | Latency | Notes | | Operation | Latency | Notes |
|-----------|---------|-------| |-----------|---------|-------|
| Single save (no WAL) | 91 µs | Direct HDF5 write | | Single save (no WAL) | 61 µs | Direct HDF5 write (owned-Vec IO path) |
| Single save (with WAL) | 134 µs | +47% for crash safety | | Single save (with WAL) | 18 µs | WAL group-commit append; HDF5 write batched at flush |
| Batch 100 | 723 µs | 7.2 µs per record | | Batch 100 | 723 µs | 7.2 µs per record |
| Batch 1,000 | 6.17 ms | 6.2 µs per record | | Batch 1,000 | 6.17 ms | 6.2 µs per record |
| WAL save (1K existing) | 539 µs | Incremental append | | WAL save (1K existing) | 539 µs | Incremental append |
@@ -160,7 +160,7 @@ End-to-end strategy evaluation including embedding operations.
| **Hybrid vector+keyword** | <200 µs | 1K records | | **Hybrid vector+keyword** | <200 µs | 1K records |
| **Knowledge graph query** | <25 µs | 1K entities | | **Knowledge graph query** | <25 µs | 1K entities |
| **Temporal range query** | <1 µs | 10K timestamps | | **Temporal range query** | <1 µs | 10K timestamps |
| **Memory write** | <135 µs | Per record | | **Memory write** | <20 µs | Per record (WAL group-commit append) |
| **Consolidation cycle** | <165 µs | 1K records | | **Consolidation cycle** | <165 µs | 1K records |
| **Importance gate** | <1 µs | Per record | | **Importance gate** | <1 µs | Per record |
README.md
+10 -7
View File
@@ -57,7 +57,7 @@ Benchmarked on Intel i7-12650H (10C/16T), 384-dim embeddings, Criterion.rs.
| Spreading activation | **17 µs** | 100 entities | | Spreading activation | **17 µs** | 100 entities |
| Temporal range query | **716 ns** | 10K timestamps | | Temporal range query | **716 ns** | 10K timestamps |
| Consolidation cycle | **164 µs** | 1K records | | Consolidation cycle | **164 µs** | 1K records |
| Memory write (WAL) | **134 µs** | per record | | Memory write (WAL) | **18 µs** | per record (group-commit append; HDF5 batched at flush) |
| Importance gate | **61 ns** | per record | | Importance gate | **61 ns** | per record |
### HDF5 Core I/O (vs h5py/C HDF5) ### HDF5 Core I/O (vs h5py/C HDF5)
@@ -71,14 +71,16 @@ Benchmarked on Intel i7-12650H (10C/16T), 384-dim embeddings, Criterion.rs.
### Chunked Write Throughput (codec comparison) ### Chunked Write Throughput (codec comparison)
Measured with Criterion on 512×512 f32 matrices (h5bench-equivalent workload): Measured with Criterion on f32 matrices. Auto-shuffle is applied before all compression codecs
by default (AoS→SoA byte transpose, +157–204% throughput for float data):
| Codec | 128×128 f32 | 512×512 f32 | vs Deflate | | Codec | 128×128 f32 | 512×512 f32 | Notes |
|-------|-------------|-------------|------------| |-------|-------------|-------------|-------|
| Zstd level 3 | **189 µs / 330 MiB/s** | **1.69 ms / 593 MiB/s** | **2.1–2.5×** | | Zstd level 3 | **148 µs / 422 MiB/s** | **1.34 ms / 748 MiB/s** | With auto-shuffle |
| Deflate level 6 | 475 µs / 132 MiB/s | 3.57 ms / 280 MiB/s | baseline | | Deflate level 6 | 153 µs / 407 MiB/s | 1.39 ms / 719 MiB/s | With auto-shuffle |
| Pcodec | 528 µs / 118 MiB/s | 1.69 ms / 591 MiB/s | Best compression ratio |
Use `.with_zstd(3)` for write-heavy workloads. Same or better compression ratio at 2× the speed. Use `.with_zstd(3)` or `.with_deflate(6)` for write-heavy workloads — both now perform at ~720–750 MiB/s on large matrices. Use `.with_pcodec()` for write-once/read-many workloads where compression ratio matters more than encode speed. Disable auto-shuffle with `.without_shuffle()` for byte arrays that don't benefit from AoS→SoA transposition.
> ¹ MemX ([arxiv:2603.16171](https://arxiv.org/abs/2603.16171), March 2026): Rust + libSQL, claims <90ms at 100K records. > ¹ MemX ([arxiv:2603.16171](https://arxiv.org/abs/2603.16171), March 2026): Rust + libSQL, claims <90ms at 100K records.
@@ -404,6 +406,7 @@ ClawhDF5's agent memory design draws from 15+ recent papers:
| `fast-checksum` | no | crc32fast-accelerated checksums | | `fast-checksum` | no | crc32fast-accelerated checksums |
| `lz4` | no | LZ4 block compression filter (id 32004) | | `lz4` | no | LZ4 block compression filter (id 32004) |
| `zstd` | no | Zstandard compression filter (id 32015) | | `zstd` | no | Zstandard compression filter (id 32015) |
| `pcodec` | no | Pcodec lossless numerical codec (id 32023, via `pco` crate) |
| `system-zlib` / `zlib-rs` | no | Alternative zlib backends for deflate | | `system-zlib` / `zlib-rs` | no | Alternative zlib backends for deflate |
| `blake3_hash` | no | BLAKE3 content hashing for provenance | | `blake3_hash` | no | BLAKE3 content hashing for provenance |