Behavior discovery API

POST /api/v1/projects/{projectId}/lattice/discover

Cluster the project’s subjects by their feature vectors and return the dense, cohesive clusters as candidate behaviors. See Behavior discovery for the concept.

The same surface is also exposed at POST /api/v1/projects/{projectId}/memory-intelligence/discover — identical request and response.

Request

All fields optional; the engine clamps to safe ranges.

{
  "simThreshold": 0.75,
  "minClusterSize": 3,
  "minStability": 0.6,
  "maxMembers": 50
}

Field	Type	Notes
`simThreshold`	number [0,1]	Min similarity to join a cluster. Default 0.75.
`minClusterSize`	number	Below this a cluster is noise, not a behavior. Default 3.
`minStability`	number [0,1]	Drop clusters below this cohesion. Default 0.6.
`maxMembers`	number	Cap on members returned per behavior. Default 50.

Response

{
  "behaviors": [
    {
      "label": "high-value frequent recurring of tonys-pizza",
      "prevalence": 0.32,
      "stability": 0.88,
      "size": 14,
      "memberSubjects": [ { "kind": "customer", "externalId": "acct-7" } ],
      "exemplarEvidence": ["rfm: rhi fhi mhi", "pattern: recurring_event", "entity: tonys-pizza"]
    }
  ],
  "subjectsAnalyzed": 44,
  "generatedAt": "2026-06-30T00:00:00Z",
  "durationMs": 12
}

Field	Meaning
`label`	Deterministic rule-based description (RFM band + frequency + dominant pattern + top entity).
`prevalence`	Fraction of analyzed subjects in this cluster.
`stability`	Cohesion (mean intra-cluster similarity).
`size`	Total subjects in the cluster (may exceed `memberSubjects` length when capped by `maxMembers`).
`memberSubjects`	Members, medoid first (capped by `maxMembers`).
`exemplarEvidence`	The signals behind the label.

subjectsAnalyzed is the prevalence denominator.

⚠️

An empty behaviors array means the engine abstained — not enough signal to assert a behavior — never “this project has no behaviors”.

Naming discovered behaviors

The label is a deterministic, rule-based description. To upgrade it to a human name, run your own LLM over a discovered cluster and write the name back as metadata — the engine never calls an LLM itself during discovery. See Behaviors for the neuro-symbolic loop.

Example

curl https://app.memmesh.ai/api/v1/projects/$PID/lattice/discover \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{ "minStability": 0.6 }'

Predictions Context & Profiles