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.

Published artifact verification

Package checksums, image digests and verification scope.