v1.0.0

HeatherDB 1.0.0

HeatherDB is a read-optimized, single-node associative-memory database. It runs
on CPUs, exposes an authenticated HTTP API and can be embedded as a Rust library.
Competitive writes learn an adaptive representation; plain writes retain each
vector as a separate location. Both support associative recall.

Memory and records

• Associative pattern completion through iterative, fast and explicit-scale
  attention reads.
• Competitive learning from repeated observations. Novel patterns receive their
  own locations; joining observations update shared counters and addresses.
• Plain vector locations for workloads that require a non-adaptive representation.
• Metadata-bearing documents, exact ID/metadata lookup and similarity-ranked
  document queries, available with either write mode.
• Per-database dimensions, learning configuration and f64/f32 storage precision.
  Dimension, write mode and precision are selected at database creation.

Reconstruction returns a vector, not document identity. It can express an
individual pattern or shared structure. Evaluate recall, learning and retention
on the data, cue damage and read settings your application needs.

Storage and operation

• Persistent LMDB storage with synchronous commits by default.
• Transactional batch writes. A failed storage transaction leaves the committed
  records and learned state unchanged; failed recovery closes access to that
  collection rather than serving inconsistent state.
• Authentication enabled by default, database-scoped users and immediate bearer
  revocation after user deletion, password rotation or scope changes.
• Live per-database snapshots, cold full backups, restore and offline integrity
  verification. Full backups include users; restored data is verified independently.
• Exclusive ownership of each data directory, health/readiness probes,
  collection statistics and audit records.
• Versioned, checksummed vector records and refusal of unsupported formats.

Run one engine process per data directory on local block storage with a
persistent volume. Terminate exposed HTTP through a TLS proxy. Replication,
automatic failover and multi-node transactions are outside this release.

Measurements

On the recorded Apple M4 workload, the 128-dimensional native iterative-read
mean is 32.39 µs and the single-write mean is 5.23 ms. A 100-vector batch takes
12.46 ms, compared with 526.41 ms through individual calls. These are small,
vector-only workloads with synchronous durability, not throughput guarantees.
Native timings exclude HTTP and authentication.

The 32-pattern, 64-dimensional partial-cue fixture reports mean cosine 0.8844
for default competitive iterative reads and 1.0000 for plain attention at scale
50. A separate five-seed shared-pattern task reaches held-out cosine 0.9941;
a same-count online k-means baseline scores 0.9968. These are distinct synthetic
evaluations, not semantic-reasoning or universal capacity claims.

Benchmark methodology and evidence
and learning protocol and results
record the measured revisions, configurations, raw samples and limitations.

Compatibility and installation

1.0.0 establishes a fresh compatibility baseline. Documented stable APIs and
stored formats enter the 1.x compatibility policy. A breaking API or storage
change requires a major release and an explicit transition procedure.

No automatic migration from 0.x is supplied. Use a new data directory and replay
source observations when moving a pre-1.0 deployment. Preserve its data and backups;
starting with 1.0 does not require deleting an existing directory.

Use a versioned binary or container tag in deployments. Archives cover Linux
x86_64/arm64 (GNU and static musl), macOS Apple Silicon/Intel and Windows x86_64.
Debian packages provide a systemd unit and a dedicated service account. GNU
Linux builds are tested on Ubuntu 24.04; use static musl builds on older Linux
systems. macOS binaries are unsigned and not notarized.

Check archive hashes against SHA256SUMS.txt. Package smoke checks cover binary
version, startup, authenticated writes/reads and persistence across restart.

Experimental features and limits

Vector algebra, automatic attention calibration and dreaming remain experimental.
Their response semantics are outside the stable 1.x API commitment. Opt in
explicitly and validate their effects on your workload.

• Associative reads can blend patterns and do not automatically reject unknown
  queries. Calibrate application-level validation independently.
• Document deletion removes lookup and attribution; it does not subtract prior
  influence from learned counters. Adaptation is not secure unlearning or a TTL.
• Relaxed durability is explicit and can lose data or corrupt storage after a
  system crash. Synchronous durability is the default.
• SIGKILL recovery and map-exhaustion tests are not power-loss or media-failure
  certification. The bounded concurrency check is not a production soak test.
• bincode 1.3.3 carries an informational unmaintained notice. Its serialization
  contracts remain maintained by this project; the recorded advisory review has
  no reported vulnerability entries.

Release contract
provides the supported surface and compatibility commitments.

Downloads

Platform	Asset
linux-aarch64-gnu	heather-v1.0.0-linux-aarch64-gnu.tar.gz
linux-aarch64-musl	heather-v1.0.0-linux-aarch64-musl.tar.gz
linux-x86_64-gnu	heather-v1.0.0-linux-x86_64-gnu.tar.gz
linux-x86_64-musl	heather-v1.0.0-linux-x86_64-musl.tar.gz
macos-aarch64	heather-v1.0.0-macos-aarch64.tar.gz
macos-x86_64	heather-v1.0.0-macos-x86_64.tar.gz
windows-x86_64	heather-v1.0.0-windows-x86_64.zip
ubuntu/debian (amd64, .deb)	heatherdb_1.0.0_amd64.deb
ubuntu/debian (arm64, .deb)	heatherdb_1.0.0_arm64.deb

Install the .deb on Ubuntu/Debian:

curl -fsSLO https://github.com/aphorion/heatherdb/releases/download/v1.0.0/heatherdb_1.0.0_amd64.deb
sudo apt install ./heatherdb_1.0.0_amd64.deb

This installs a heatherdb systemd service, a dedicated heatherdb user, and
generates admin credentials in /etc/heatherdb/env — read that file, then
sudo systemctl start heatherdb.

The macOS binaries are unsigned — clear the download quarantine before
the first run:

xattr -d com.apple.quarantine ./heather

Verify with the bundled SHA256SUMS.txt:

curl -fsSLO https://github.com/aphorion/heatherdb/releases/download/v1.0.0/SHA256SUMS.txt
sha256sum --check SHA256SUMS.txt --ignore-missing