Clusters API

Overview

Clusters are flexible groupings for organizing related memories. Unlike spaces which provide access isolation, clusters are labels that memories can belong to. A single memory can belong to multiple clusters.

Create Cluster

POST /clusters

Creates a new cluster for organizing memories. Cluster names must be unique within a space.

Body Parameters

Response (201)

{
  "id": "<uuid>",
  "name": "learning-progress",
  "description": "Track user learning milestones",
  "space_id": "<space-uuid>",
  "color": "#4A90D9",
  "metadata": {
    "category": "education",
    "auto_assign": true
  },
  "memory_count": 0,
  "created_at": "2026-04-10T10:30:00Z"
}

Get Cluster

GET /clusters/:clusterId

Fetches a cluster by its UUID. Returns cluster details including memory count and optionally the memories themselves.

Path Parameters

Query Parameters

Response (200)

{
  "id": "<uuid>",
  "name": "learning-progress",
  "description": "Track user learning milestones",
  "space_id": "<space-uuid>",
  "color": "#4A90D9",
  "cluster_type": "manual",
  "memory_count": 47,
  "silhouette_score": null,
  "dbcv_score": null,
  "cohesion_score": null,
  "centroid_available": false,
  "created_at": "2026-04-10T10:30:00Z",
  "updated_at": "2026-04-12T14:22:00Z",
  "memories": [
    {
      "id": "<uuid>",
      "content": "Completed React tutorial",
      "created_at": "2026-04-12T14:22:00Z"
    }
  ],
  "memories_pagination": {
    "limit": 5,
    "offset": 0,
    "has_more": true
  }
}

List Clusters

GET /clusters

Returns a list of all clusters, optionally filtered by space and scale.

Query Parameters

Response (200)

{
  "data": [
    {
      "id": "<uuid>",
      "name": "learning-progress",
      "description": "Track user learning milestones",
      "cluster_type": "manual",
      "memory_count": 47,
      "created_at": "2026-04-10T10:30:00Z"
    }
  ],
  "has_more": false
}

Update Cluster

PATCH /clusters/:clusterId

Updates an existing cluster. Only the fields you provide will be updated.

Path Parameters

Body Parameters

Response (200)

{
  "id": "<uuid>",
  "name": "learning-progress",
  "description": "Track learning milestones and achievements",
  "color": "#22C55E",
  "memory_count": 47,
  "created_at": "2026-04-10T10:30:00Z",
  "updated_at": "2026-04-14T09:15:00Z"
}

Delete Cluster

DELETE /clusters/:clusterId

Deletes a cluster. Memories previously associated with the cluster are unlinked; the underlying memories are not deleted.

Path Parameters

Response (204)

Returns no content on successful deletion.

Manage Memory-Cluster Associations

Cluster membership is managed from the memory side, via the Memories API. The endpoints below are documented here for discoverability.

Add a memory to one or more clusters

POST /memories/:id/clusters

Associates a memory with the given clusters.

Body Parameters

Remove a memory from a cluster

DELETE /memories/:id/clusters/:clusterId

Dissociates a memory from a single cluster. Returns no content on success.

List a memory's clusters

GET /memories/:id/clusters

Returns all clusters the memory belongs to.

List Cluster Memories

GET /clusters/:clusterId/memories

Returns a paginated list of memories belonging to a cluster.

Path Parameters

Query Parameters

Response (200)

{
  "cluster_id": "<uuid>",
  "cluster_name": "learning-progress",
  "memories": [
    {
      "id": "<uuid>",
      "content": "Completed React tutorial",
      "created_at": "2026-04-12T14:22:00Z"
    }
  ],
  "pagination": {
    "limit": 5,
    "offset": 0,
    "count": 2,
    "has_more": true
  }
}

Account Cluster Statistics

GET /clusters/stats

Returns account-wide cluster statistics.

Query Parameters

Cluster Quality & Topics

Per-cluster quality and topic endpoints:

Get quality metrics for a cluster

GET /clusters/:id/quality

Returns silhouette, DBCV and cohesion scores if available.

Get topic information for a cluster

GET /clusters/:id/topics

Returns topic label, keywords and representation extracted by topic modelling.

Queue a quality metric refresh

POST /clusters/:id/refresh-metrics

Enqueues a background job to recompute quality metrics for the cluster.

Queue a centroid recomputation

POST /clusters/:id/recompute-centroid

Enqueues a background job to recompute the cluster centroid.

Trigger Clustering Jobs

Trigger incremental clustering

POST /clusters/incremental

Queues an incremental clustering job that assigns new or selected memories to existing clusters.

Body Parameters

Response (202)

{
  "status": "queued",
  "job_id": "<job-id>",
  "message": "Incremental clustering job queued",
  "params": { "space_id": "<space-uuid>", "memory_count": "all_new" }
}

Trigger full HDBSCAN clustering

POST /clusters/full

Queues a full HDBSCAN clustering job that creates new clusters from all unclustered memories.

Get clustering run status

GET /clusters/status

Returns the most recent clustering run, plus aggregate counts.

List recent clustering runs

GET /clusters/runs

Returns a list of clustering runs (filterable by status).

Get clustering configuration

GET /clusters/config

Returns the account's clustering configuration (algorithm, min_cluster_size, auto_enabled).

Update clustering configuration

POST /clusters/config

Updates the account's clustering configuration.

Body Parameters

Cluster Object

The cluster object contains the following fields: