HeatherDB

Storing is learning. Reading is reasoning.

HeatherDB is a content-addressable associative memory, exposed as an ordinary HTTP database. It has one write primitive and one read primitive — and both do more than their names suggest.

• Write doesn't insert a row. It's an act of online, self-organizing learning: competitive learning grows, splits, and merges a codebook of "hard locations" to accommodate what it's shown. There is no separate training step — the memory is the model, updated in place, on every write.

• Read doesn't fetch a row. It reconstructs a vector as a weighted superposition of everything relevant ever written — via softmax-over-dot-products, the same operation that sits at the centre of three different fields at once:

  As a…	It does this
  Attention head	softmax(β · Q·Kᵢ) — structurally identical to transformer attention
  Hopfield network	The softmax carves basins of attraction, so a noisy or partial query is pulled toward the nearest genuine attractor
  Posterior under a mixture model	Soft-clustering over prototype locations, weighted by the evidence (write_count) each has accumulated

A compositional vector algebra (bind / unbind / permute / bundle) — Vector Symbolic Architecture in the Holographic Reduced Representation tradition — sits on top, so you can bind roles to fillers, superpose multiple bindings, and pull compositional structure back out. That is what makes king − man + woman ≈ queen-style analogical retrieval possible with no neural network in the loop.

None of this requires training data, GPUs, retraining schedules, or model versioning. It requires an HTTP POST.

AGPL-3.0 licensed, and it runs on a laptop. The engine remains open: anyone can run, study, modify, and redistribute it. If you modify the engine and offer it as a network service, the corresponding source must remain available to the users of that service.

Documentation

The full tree is in docs/, and it separates two things deliberately:

Heather — the paradigm. Intelligence as a property of how data is arranged. Storage native intelligence is the argument; what similarity means is the design surface; boundary conditions is where it stops. These stay true of any system built this way.

HeatherDB — this engine. Getting started · deploy · run it in production · HTTP API · configuration · parameters · behaviour and silent failures

Nine tutorials run in order, each turning on one result you produce yourself. Every technical term has a glossary entry, explained once plainly and once precisely.

Quick start

git clone https://github.com/aphorion/heatherdb
cd heatherdb
cargo build --release -p heather_server

HEATHER_DATA_DIR=/tmp/heatherdb \
HEATHER_DIMENSION=8 \
HEATHER_ADMIN_USER=admin \
HEATHER_ADMIN_PASSWORD='quickstart-password' \
  ./target/release/heather

The admin password must be at least 8 characters; a shorter one aborts the boot. Leave it unset in production and the engine generates one, prints it once, and writes it to $HEATHER_DATA_DIR/initial-admin-password.

Write a vector, then read back a corrupted version of it:

curl -s -u admin:quickstart-password -H 'Content-Type: application/json' \
  -d '{"vectors": [[1, 1, 1, 1, 0, 0, 0, 0]]}' \
  http://localhost:6380/collections/quickstart/write

curl -s -u admin:quickstart-password -H 'Content-Type: application/json' \
  -d '{"query": [1, 0, 0, -1, 0, 0, 0, 0]}' \
  http://localhost:6380/collections/quickstart/read

The collection is created by the write; you never declared it. The read returns the pattern the query belongs to rather than the query or a stored row — see Getting started for the rest, including running it embedded as a Rust library instead of as a server.

Performance

Measured on Apple Silicon (M-series). Config: l_0=1000, k=20, neighbor_cap=max((k-1)·⌈ln L⌉, 2k), 32 landmarks. Reproduce with cargo bench -p heather_db.

Operation	d=64	d=128	d=384
Single write	3.3 ms	3.7 ms	4.1 ms
Single read (iterative)	18 µs	43 µs	153 µs
Reads/sec (sustained)	19,418	9,336	3,473

Batch writes amortise lock acquisition and LMDB persistence into one transaction — 100 vectors take 11.6 ms as a batch against 390 ms individually, a 33.7× speedup, rising to 77.6× at 500.

Graph search follows the learned manifold instead of scanning every location, so activation latency is near-constant in collection size: 18 µs at 1,384 locations and 22 µs at 5,097, against 131 µs and 124 µs for brute force.

This is the beginning of the README. Read the rest at the original. Read the full README ↗