Read endpoints

Recall from a collection. Six routes: the plain Hopfield read, three attention variants, analyze (a read with its activation trace), and batch_analyze.

Every route here has a legacy form without the /db/{db} prefix that targets the default database. Auth for all of them: Basic or Bearer, root or Database(db) (legacy form: root or Database("default")). All create the collection if it does not exist — a read against an unknown name returns an empty result, not a 404. See Overview.

read, attention and analyze record an audit entry when logging is enabled for the database (as does documents/query). attention/mdl, attention/calibrate and batch_analyze do not.

POST /db/{db}/collections/{name}/read

Reconstruct a pattern associated with the query. Legacy: POST /collections/{name}/read.

iterative runs the Hopfield loop to convergence (up to t_max); fast is a single step.

The result is a reconstructed vector. In competitive mode it can complete an individual pattern or express shared structure learned from related writes. Novel writes receive separate locations; joining writes can combine observations. Plain mode keeps each vector as a separate location, but attention can still blend them. Read strategy, temperature and data overlap affect reconstruction.

For document identity, use metadata-bearing writes and the document API. documents/{id} returns the ID and metadata; documents/query returns similarity-ranked document results. Neither requires a different write mode. See Choose a memory mode.

curl -u admin:pw -X POST \
  http://localhost:6380/db/movies/collections/taste/read \
  -H 'Content-Type: application/json' \
  -d '{"query":[0.1,0.2,0.3],"strategy":"iterative"}'

{ "result": [0.1, 0.3, 0.5, 0.2] }

POST /db/{db}/collections/{name}/attention

Raw dot-product attention at a temperature you supply. Legacy: POST /collections/{name}/attention.

curl -u admin:pw -X POST \
  http://localhost:6380/db/movies/collections/taste/attention \
  -H 'Content-Type: application/json' \
  -d '{"query":[0.1,0.2,0.3],"scale":12.5}'

{ "result": [ … ], "beta": 12.5,
  "contributors": [ { "id": 7, "similarity": 0.91, "weight": 0.63 } ] }

contributors is ordered by descending weight. similarity here is the raw dot product Q·Kᵢ, not a cosine — unlike the identically-named field in analyze.

POST /db/{db}/collections/{name}/attention/mdl

The same read, except β is not supplied: the engine picks it per query by minimising the description length of the activated key set (leave-one-out KDE bandwidth selection over a log grid in [0.1, 500]). Legacy: POST /collections/{name}/attention/mdl.

curl -u admin:pw -X POST \
  http://localhost:6380/db/movies/collections/taste/attention/mdl \
  -H 'Content-Type: application/json' -d '{"query":[0.1,0.2,0.3]}'

{ "result": [ … ], "beta": 37.2, "entropy": 0.41,
  "contributors": [ { "id": 7, "similarity": 0.91, "weight": 0.63 } ] }

entropy is the normalised Shannon entropy of the weights, -Σ w·ln w / ln n, in 0..1 — 0 for fewer than two contributors. It is reported, never acted on: attention entropy is a weak abstention signal on its own (measured AUC 0.61–0.76, against 0.997 for the top-1 match margin), so the threshold, if any, is the caller's.

POST /db/{db}/collections/{name}/attention/calibrate

Pick an attention temperature for the whole collection by leave-one-out value-reconstruction description length. Legacy: POST /collections/{name}/attention/calibrate.

curl -u admin:pw -X POST \
  http://localhost:6380/db/movies/collections/taste/attention/calibrate \
  -H 'Content-Type: application/json' -d '{"betas":[1.0,10.0,100.0]}'

{ "beta": 42.6, "dl": 1183.4 }

Feed the result back as scale on attention.

POST /db/{db}/collections/{name}/analyze

A read with the full activation trace attached — the "why this?" endpoint. Legacy: POST /collections/{name}/analyze.

curl -u admin:pw -X POST \
  http://localhost:6380/db/movies/collections/taste/analyze \
  -H 'Content-Type: application/json' \
  -d '{"query":[0.1,0.2,0.3],"strategy":"iterative"}'

{ "iterations": 4, "converged": true,
  "activated_locations": [ { "id": 7, "similarity": 0.91, "weight": 0.63 } ],
  "result": [ … ] }

Here similarity is a cosine.

POST /db/{db}/collections/{name}/batch_analyze

Many analyze calls in one request, run in parallel. Legacy: POST /collections/{name}/batch_analyze.

curl -u admin:pw -X POST \
  http://localhost:6380/db/movies/collections/taste/batch_analyze \
  -H 'Content-Type: application/json' \
  -d '{"queries":[[0.1,0.2,0.3],[0.9,0.0,0.1]],"strategy":"fast"}'

{ "results": [ { "iterations": 4, "converged": true,
                 "activated_locations": [ … ], "result": [ … ] } ] }

Results are in request order. Not audited — use analyze when you need the log.