Quickstart
Run HeatherDB locally, store two patterns and reconstruct one from an incomplete
cue. This example uses eight-dimensional vectors so you can inspect every value.
You need Docker, curl, and an unused local port 6380.
This first example uses plain writes to keep the two observations separate. Competitive learning is the default when you do not specify a mode. After the example, choose a memory mode for your task.
1. Run the engine
docker run -d --name heather-quickstart \
-p 127.0.0.1:6380:6380 \
-v heather_quickstart:/var/lib/heatherdb \
-e HEATHER_ADMIN_USER=admin \
-e HEATHER_ADMIN_PASSWORD='quickstart-password' \
aphorion/heatherdb:1.0.0
The command prints a container ID. The credentials are for this local example. The named volume preserves the engine data when the container stops.
If you prefer a native binary or embedded Rust, use the installation guide. The HTTP commands below work with any local server using these credentials.
curl -fsS http://localhost:6380/health
Expected response:
{ "status": "ok" }
2. Create a plain memory
curl -fsS -u admin:quickstart-password \
-H 'Content-Type: application/json' \
-d '{"name":"quickstart","dimension":8,"eam":{"competitive":false}}' \
http://localhost:6380/db
The response identifies quickstart, with dimension: 8 and
competitive: false. Dimensions and write mode are database settings.
3. Store two patterns
The first pattern has activity in its first four coordinates. The second has activity in its last four coordinates.
curl -fsS -u admin:quickstart-password \
-H 'Content-Type: application/json' \
-d '{"vectors":[[1,1,1,1,0,0,0,0],[0,0,0,0,1,1,1,1]]}' \
http://localhost:6380/db/quickstart/collections/patterns/write
Expected response:
{ "count": 2 }
The write creates the patterns collection. Both observations are now stored.
4. Recall from a partial cue
Send only two active coordinates from the first pattern. Attention scale 50 makes this small example strongly prefer the matching location.
curl -fsS -u admin:quickstart-password \
-H 'Content-Type: application/json' \
-d '{"query":[1,0,1,0,0,0,0,0],"scale":50}' \
http://localhost:6380/db/quickstart/collections/patterns/attention
The response includes:
{
"result": [
1.0, 1.0, 1.0, 1.0, 3.720075976020836e-44, 3.720075976020836e-44,
3.720075976020836e-44, 3.720075976020836e-44
],
"beta": 50.0
}
The first four values reconstruct the original active region. The remaining values are effectively zero. The full response also includes contributor IDs, weights and dot-product similarities; see the read reference.
This is a two-pattern numeric example, not a semantic-reasoning test. The output is a reconstructed vector. Use the document API when you need to look up a document by identity. Larger or overlapping memories need their own recall and read-setting evaluation.
5. Check persistence
docker restart heather-quickstart
Once /health responds, repeat the attention request. The named volume retains
the patterns across the restart. See backup and restore
for a recoverable deployment rather than relying on a single local volume.
Troubleshooting
| What you see | What to check |
|---|---|
| Connection refused | Wait for startup, then inspect docker logs heather-quickstart and check port 6380 |
| Container name is already in use | Inspect the existing example with docker ps -a; reuse it with docker start heather-quickstart |
| Authentication error | Use the credentials that initialized this volume; changing an environment variable does not rotate an existing user's password |
| Database already exists | Skip the create request when reusing this example, or choose a different database name consistently in the commands |
| Dimension mismatch | The database dimension is 8; every vector and cue must contain eight numbers |
To stop and remove only the example container:
docker stop heather-quickstart
docker rm heather-quickstart
The heather_quickstart volume remains. Starting the same command again reuses
its data and credentials.