7.8k stars · MIT · v0.17.4 (2025-12-03) · Track this in Scout
The standard way to turn a long thread into named subtopics with a parent/child hierarchy and a timeline view.
▶Repo detailsthe review · specs · pros & cons · install
What it is
A topic-modelling library that embeds documents, clusters them, and labels each cluster with the words that distinguish it. It supports hierarchical topics, topics over time, and swapping in your own embedding model.
What it is good for. This is the economic counterweight to GraphRAG from Edition 1. GraphRAG produces a beautiful nested hierarchy and charges thousands of LLM calls per document to do it — fine as a premium tier and ruinous as the default path for a free trial. BERTopic reaches a comparable structure by clustering embeddings, so the marginal cost of mapping a conversation is CPU time rather than API spend. Its hierarchical mode gives you the parent/child structure a drill-in UI needs, and its topics-over-time view is close to a feature in itself. Pair it with model2vec (Edition 1) as the embedding backend and the whole thing fits comfortably on a small VPS.
- MIT, mature, and by far the best-documented library in this space
- Hierarchical topics map directly onto a drill-in interaction
- Pluggable embeddings, so model2vec keeps it inside your RAM budget
- Default settings are memory-hungry — the UMAP and HDBSCAN steps will bite on a small VPS
- Clustering is non-deterministic, so the same chat can produce a slightly different map twice. Users notice
- The outlier bucket (topic
-1) can swallow a lot of text; you must handle it in the UI
pip install bertopic
