Collection endpoints

Lifecycle and introspection of collections. A collection is one Adaptive Elastic Associative Memory inside a database; it inherits the database's dimension.

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")). See Overview.

POST /db/{db}/collections

Create a collection. Idempotent. Legacy: POST /collections.

curl -u admin:pw -X POST http://localhost:6380/db/movies/collections \
  -H 'Content-Type: application/json' -d '{"name":"taste"}'

{ "name": "taste", "created": true }

created is false when the collection already existed.

GET /db/{db}/collections

List collection names. Legacy: GET /collections.

Request body: no body.

curl -u admin:pw http://localhost:6380/db/movies/collections

{ "collections": ["taste", "history"] }

DELETE /db/{db}/collections/{name}

Drop a collection and everything in it. Legacy: DELETE /collections/{name}.

Request body: no body.

curl -u admin:pw -X DELETE \
  http://localhost:6380/db/movies/collections/taste

{ "dropped": true }

{"dropped": false} when there was no such collection — dropping is idempotent, not a 404.

GET /db/{db}/collections/{name}/stats

Counters for the memory. Legacy: GET /collections/{name}/stats.

Request body: no body.

curl -u admin:pw \
  http://localhost:6380/db/movies/collections/taste/stats

{ "num_locations": 812, "total_writes": 10450.0, "current_eta": 0.0031,
  "avg_write_count": 12.87, "max_write_count": 96.0 }

num_locations is a diagnostic of data complexity, not a tunable. current_eta is the decayed learning rate.

GET /db/{db}/collections/{name}/config

The effective EAMConfig for this collection. Legacy: GET /collections/{name}/config. See Configuration for every field.

Request body: no body.

curl -u admin:pw \
  http://localhost:6380/db/movies/collections/taste/config

{ "config": { "d": 128, "l_0": 0, "k": 20, "eta_0": 0.01, "lambda": 0.9999,
  "eta_min": 0.001, "tau_split": 0.3, "tau_merge": 0.95, "gamma": 1.0,
  "tau_damp": 10.0, "tau_overload": 8.0, "beta": 5.0, "t_max": 10,
  "epsilon": 1e-6, "neighbor_cap": 32, "num_landmarks": 32,
  "mdl_gate": false, "competitive": true } }

GET /db/{db}/collections/{name}/locations

The hard locations themselves. Legacy: GET /collections/{name}/locations.

Summary form (full=false):

curl -u admin:pw \
  http://localhost:6380/db/movies/collections/taste/locations

{ "locations": [ { "id": 0, "write_count": 12.0,
                   "avg_counter_magnitude": 0.041 } ] }

Full form (full=true) replaces avg_counter_magnitude with the raw vectors — L × 2D floats, so it is large:

{ "locations": [ { "id": 0, "write_count": 12.0,
                   "address": [ … ], "counter": [ … ] } ] }

POST /db/{db}/collections/{name}/compress

Merge locations while it lowers the collection's description length, stopping at the MDL minimum. Legacy: POST /collections/{name}/compress. Both fields optional; an empty body {} is valid.

curl -u admin:pw -X POST \
  http://localhost:6380/db/movies/collections/taste/compress \
  -H 'Content-Type: application/json' -d '{"kappa":128.0,"lambda":1.0}'

{ "locations_before": 812, "locations_after": 640,
  "description_length_before": 91234.5,
  "description_length_after": 88012.1, "merges": 172 }

GET /db/{db}/collections/{name}/fingerprint

The collection's emergent self-summary: the write-count-weighted centroid of every hard location's normalised pattern, refined by an iterative Hopfield read so it lands on a real attractor rather than a bare average. Legacy: GET /collections/{name}/fingerprint.

Request body: no body.

curl -u admin:pw \
  http://localhost:6380/db/movies/collections/taste/fingerprint

{ "fingerprint": [0.13, -0.07, 0.26] }

{"fingerprint": null} when nothing has been written.