Retentioneering 5.x: DuckDB Eventstreams, anywidget Graphs, and an Analytics MCP Server

The problem Retentioneering targets: one-off scripts that nobody can re-run

Most clickstream questions get answered once and thrown away. An analyst writes a pandas script to build a funnel, a second script to draw a flow diagram, and a third to compare two cohorts, and none of the three share a data model. When someone asks a follow-up question three weeks later, the scripts have drifted from the data and the answer has to be rebuilt. Retentioneering's stated pitch is that analysts and AI agents should instead use tested analytical primitives and reusable workflows, so that a journey analysis is assembled from parts rather than regenerated from scratch. The README frames the benefit in terms of reduced implementation effort, lower agent token usage, and fewer subtle analytical errors. The audience is explicit: data scientists and analysts who are comfortable with what the README calls average Python knowledge, plus LLM agents driven through the bundled MCP server and agent skills. The questions it names are concrete ones. Where do users get stuck. Which journeys lead to conversion or churn. What behavioral segments exist. How do flows differ between cohorts or experiment groups. If your work looks like that, the toolkit is aimed at you. If your work is dashboarding for non-technical stakeholders, it is not.

Eventstream, immutable processors, and the DuckDB rewrite

The central object is Eventstream. You construct it from a DataFrame, and the README says it also accepts CSV, TSV, Parquet, or a custom export from BigQuery, ClickHouse, or another event database. Everything else hangs off that object: graphs, funnels, step matrices, segmentation, experiment comparison. The mechanism that matters for reproducibility is chaining. Data processors return a new Eventstream and, per the README, the original is never modified. A cleaning pipeline is therefore a value, not a sequence of side effects, which is what makes a journey analysis re-runnable against fresh data. The README's example chains filter_events, collapse_events with loops=True, and split_sessions with a 30m timeout, then calls step_matrix with a path_pattern of add_to_cart->.*->purchase. That single expression shows the intended granularity: filter out noise, fold repeated loops into one unit, cut the stream into sessions, then ask which paths between two events actually occur. Version 5.0 is described as a ground-up rewrite. The pandas engine and CDN-loaded widgets of 3.x were replaced with a DuckDB-backed Eventstream and a new generation of anywidget-based widgets. The README does not publish throughput numbers, so the performance claim should be read as an architectural change rather than a measured one. The legacy 3.x engine still exists on a separate branch.

Getting it running: install, schema, and the headless twins

Python 3.10 or newer is required. The install is a single command, pip install retentioneering, and the README notes the same line works with a leading exclamation mark inside Jupyter, Google Colab, or VS Code. Input needs three columns: a path identifier, an event name, and a timestamp. If your columns are named differently, you pass a schema, which the documentation covers under the Eventstream page. The quick start builds the object and renders a graph in two lines: stream = rete.Eventstream(df) followed by stream.transition_graph(). If you have no data, the bundled synthetic e-commerce set loads with rete.datasets.load_ecom(), and the README uses it to show a funnel over catalog, add_to_cart, and purchase, plus a transition_graph with diff set to platform, mobile, desktop for a two-segment comparison. The detail worth noticing is the headless pairing. Every widget has a data twin: transition_graph_data returns a DataFrame and accepts edge_weight such as proba_out, while funnel_data returns a dict. That split is what makes the toolkit usable in a pipeline or a test, not only in a notebook. It also gives you a way to cross-check a rendered graph against raw numbers, which is the auditable-computation claim in practice rather than in marketing copy.

Where Retentioneering 5.x will disappoint you

The rewrite is the limitation. The README states plainly that 5.0 replaced the pandas engine and the CDN-loaded widgets of 3.x, that the full delta is in CHANGELOG.md, and that the legacy engine lives on the 3.x branch. It also asks users to open issues or pull requests to migrate features from 3.x into later 5.x releases. Read that as an admission that the 5.x surface is not yet feature-complete relative to what people were running before. If your production analysis depends on a 3.x capability that has not been ported, upgrading means either staying on the branch or rebuilding that step. There is a second boundary. The toolkit renders interactive widgets in Jupyter, Colab, Cursor, VS Code, Codex, Claude Code, or another Python-compatible environment, and the README positions the absence of a hosted SaaS platform as a feature: analysis runs in your own environment and raw event data never leaves your machine. That is a real constraint as much as a benefit. There is no shared workspace, no scheduling layer, and no server-side dashboard for a colleague who does not open a notebook. Finally, the README notes that anonymous product telemetry may be enabled by default and can be disabled at any time. The README does not name the configuration key that disables it, so check the documentation before you assume an air-gapped install is telemetry-free.

How this differs from Mixpanel, Amplitude, or a hand-rolled pandas script

The obvious comparison is a hosted product analytics platform. The difference is where the computation happens and what you get back. A hosted tool gives you a UI, saved reports, and a shared link, and it requires you to send event data to a third party. Retentioneering gives you Python objects, an interactive widget in your own notebook, and an HTML export, with the README stating that raw and analysed event data never leaves your machine. You trade collaboration surface for data locality and for the ability to script anything the primitives do not cover. The second comparison is a bespoke pandas script, and here the difference is narrower than the README implies. A careful analyst can reproduce most of what the toolkit does. What Retentioneering adds is the immutable processor chain, a consistent Eventstream abstraction across graph, funnel, step-matrix, and segmentation methods, and the widget-versus-DataFrame pairing that lets you verify a picture against numbers. If your analyses are one-off and never revisited, a script is cheaper. If they are revisited quarterly against a moving event log, the chain is the part that pays for itself. The third option is the MCP server and agent skills, which let an LLM agent drive the same primitives instead of writing fresh analysis code. That is a different bet: you are trusting the toolkit's tested components rather than the model's generated pandas.

Maintenance, versioning, and what Apache-2.0 means here

The release cadence visible in the material is roughly monthly: v5.0.1 in mid-July 2026, v5.1.0 in late July, v5.2.0 in mid-August, with the last push to master in early September 2026. The repository is not archived. That cadence, combined with the explicit request for issues and pull requests to port 3.x features forward, tells you the 5.x line is still absorbing migration work rather than sitting still. Budget for that: a minor version bump inside 5.x may add capabilities you were waiting for, and it may also shift widget behaviour, since the README notes that the widget front-end source is now open and collaboration on it is encouraged. Pin your version in requirements and read CHANGELOG.md before bumping. On licensing, the project is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual obligations around preserving notices and stating changes. The README's telemetry note is a separate matter from the licence: Apache-2.0 says nothing about what the package sends at runtime, so treat those as two independent questions. This is not legal advice; check the licence text and your own policy.

What to verify before you commit a team to it

Load one week of your own event log into Eventstream and confirm the three-column schema and your timestamp format survive the trip, including whatever timezone handling your export applies. Then take the analysis you run most often and rebuild it as a processor chain, checking at each step that the returned Eventstream is what you expect rather than a mutated original. Compare the widget output against its data twin, for example transition_graph against transition_graph_data with edge_weight set, and confirm the numbers agree on a slice you can verify by hand. Check the 3.x branch and CHANGELOG.md for any method your current work depends on, and decide now whether you are porting it or waiting. If telemetry matters to your environment, find the documented switch and confirm it before the first run rather than after. Only then decide whether the MCP server and agent skills belong in your workflow, because that decision adds a second dependency on top of the library itself.

Editorial conclusion

Adopt Retentioneering 5.x if your team already writes pandas and wants journey graphs, step matrices, and funnel diffs rendered inside a notebook rather than a hosted product analytics tool, and if you accept that the 3.x pandas engine is now a separate branch. Do not adopt it if you need a stable API surface across the 3.x to 5.x boundary or if you cannot run Python 3.10 or newer. Before committing, verify three things against your own data: that the three-column schema and your timestamp format load cleanly into Eventstream, that the widgets you depend on exist in 5.x rather than only on the 3.x branch, and whether the default anonymous telemetry is acceptable in your environment.

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. retentioneering/retentioneering-tools on GitHub