docs: fact-check the refreshed documentation against its sources

Numbers, API names, feature defaults and PR references checked against
CONFORMANCE.md, BENCHMARKS.md, CHANGELOG.md, the code and git history.

- int8 index figures (1.74x memory, 1.63x QPS) carry the dates git gives
  them (2026-09-19/20, machine not recorded, not re-run) instead of none;
  the Pi 5 1.18x carries 2026-09-21.
- BENCHMARKS headline: the libhdf5 chunked-write figure is the newest
  measurement (35x, 2026-09-23), not 45.3x (2026-08-03).
- Conformance counts follow the 2026-09-28 run (1 our-error, 2 ref-bug)
  in conformance/README.md, ROADMAP.md and CLAUDE.md, with a pointer to
  the bad_nbit_parms_walk.h5 flip.
- README: LZ4 is opt-in; the browser refuses reference/opaque/bitfield/
  time datasets too; zlib-rs byte-identity scoped to what was measured;
  macOS default links the system libz for inflate.
- Crate READMEs: system-zlib-decompress does something (macOS), SweepDetector
  lives in prefetch, checkpoint after more than 500 WAL entries, NetCDF-4
  unlimited-dimension size warning.
- agent-memory.md: string-dataset compression threshold, agents-md prints
  Markdown, float16 file sizes linked to their study.
- known-issues.md: contiguous selection reads, 1.21x vs h5py threads.
- docs/README.md, USE_CASES.md, ROADMAP.md, CLAUDE.md: range-read
  milestones M0-M5 and PRs #17-#19, missing README rows, CLI keygen/verify,
  dated figures, fast-math is not BLAS.

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
This commit is contained in:
osobh
2026-09-28 11:23:51 -05:00
co-authored by Claude Opus 5.5
parent a48cb9f1a4
commit c27a478e44
14 changed files with 85 additions and 62 deletions
+11 -9
View File
@@ -48,8 +48,10 @@ not the whole download.
error rather than mixed data.
- In the browser, `clawhdf5-wasm`'s `openUrl` does the same from the page's
main thread; the [viewer](../examples/wasm-viewer/README.md) is a working
example. Opening one dataset of a 3000-dataset, 198 MB h5py file took
5 requests and 5.2 MB at 1 MiB blocks (tank, 2026-09-27, CHANGELOG).
example. Opening and reading one dataset of a 3000-dataset, 198 MB h5py
file took 5 requests and 5.2 MB at 1 MiB blocks (h5py's default
`libver="earliest"`; 7 requests and 6.7 MB with `"latest"`) (tank,
2026-09-27, CHANGELOG "Unreleased").
- Design and measured request counts: [design/range-reads.md](design/range-reads.md).
### Files you did not write and do not trust
@@ -95,8 +97,8 @@ An assistant accumulates preferences, decisions and context over months.
- `clawhdf5-agent` keeps records, sessions and a knowledge graph in one
`.h5` file with a write-ahead log: back it up or move it with the agent.
- Hybrid search (HNSW + BM25) reaches 81.4% turn-level Hit@5 on the full
LongMemEval haystack — retrieval recall, not QA accuracy
([BENCHMARKS.md](../BENCHMARKS.md#longmemeval-results)).
LongMemEval haystack with real MiniLM embeddings — retrieval recall, not
QA accuracy (tank, 2026-09-27; [BENCHMARKS.md](../BENCHMARKS.md#longmemeval-results)).
- The consolidation engine (Working → Episodic → Semantic) and the
knowledge graph are library components you drive; see
[agent-memory.md](agent-memory.md#library-components).
@@ -123,8 +125,8 @@ A Raspberry Pi or another ARM board, no server, no network.
- Pure Rust, no database server, one file.
- The int8 index uses NEON `SDOT` on cores with the dot-product extension
(plain NEON elsewhere); on a Raspberry Pi 5 it
was 1.18x the `f32` index's QPS at equal recall
([BENCHMARKS.md](../BENCHMARKS.md#on-arm-raspberry-pi-5-cortex-a76)).
was 1.18x the `f32` index's QPS at equal recall (2026-09-21, `114a2df`,
not re-run since; [BENCHMARKS.md](../BENCHMARKS.md#on-arm-raspberry-pi-5-cortex-a76)).
CI builds and tests the aarch64 code on an ARM runner.
- WAL appends are not fsynced: on power loss, saves since the last
checkpoint can be lost, while checkpoints themselves are made durable as
@@ -175,6 +177,6 @@ the one verified consumer of clawhdf5.
| zlib-ng instead of zlib-rs | `fast-deflate` (needs cmake) |
| Remote files | `clawhdf5-remote` (`http` default; `https`, `s3`, `gcs`, `azure`) |
| Agent memory | `clawhdf5-agent` (defaults: `float16`, `hnsw`, `parallel`) |
| BLAS for the agent's brute-force paths | `fast-math`, `openblas`, or `accelerate` (macOS) |
| GPU distance computation | `gpu` (wgpu) |
| Async wrapper | `async` (Tokio) |
| Faster brute-force paths in the agent | `clawhdf5-agent`'s `fast-math` (matrixmultiply, pure Rust), or BLAS: `openblas`, `accelerate` (macOS) |
| GPU distance computation | `clawhdf5-agent`'s `gpu` (wgpu) |
| Async wrapper | `clawhdf5-agent`'s `async` (Tokio) |