# Motif Clustering

> motif-clustering

- Skill: `lamm-mit/motif-clustering` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add lamm-mit/motif-clustering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lamm-mit/motif-clustering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lamm-mit (https://skillmd.com/u/lamm-mit)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lamm-mit/motif-clustering

---

# motif-clustering

Clusters melodic motifs using scikit-learn (KMeans or hierarchical clustering) with optional UMAP projection. Takes motif JSON (from motif-detection) and groups them by interval similarity.

## Usage

```bash
python3 skills/motif-clustering/scripts/motif_clustering.py --query "bach motifs" --n-clusters 8 --method kmeans
python3 skills/motif-clustering/scripts/motif_clustering.py --query "bach motifs" --method hierarchical
```

## Output

```json
{
  "method": "kmeans",
  "n_clusters": 8,
  "clusters": [
    {
      "cluster_id": 0,
      "n_members": 12,
      "centroid_intervals": [2, -1, 2],
      "genre_distribution": {"baroque": 8, "folk": 4},
      "top_motifs": ["m_0001", "m_0012"]
    }
  ],
  "silhouette_score": 0.47,
  "inertia": 234.5
}
```

## Dependencies

- scikit-learn
- music21