energy-system

energy-system is the foundation of the Kumbatio ecosystem. It's a framework-agnostic TypeScript library for building energy-aware applications - and it's live, open source, and installable today.

pnpm add @kumbatio/energy-system

What it does

Instead of adapting software to clock time, energy-system adapts behavior to current cognitive capacity. It models energy as explicit, self-reported application state - the five-level scale (100 | 75 | 50 | 25 | 0) described in the thesis - and resolves behavior strategies from that state.

An application built with it can adjust complexity, notification load, and interaction patterns based on what a person can realistically handle right now.

What ships in the box

• A framework-agnostic core engine with a rich, immutable state object
• A strategy system mapping energy level to behavior config - UI visibility, notification filtering, task complexity guidance, interaction forgiveness, deferral ordering, agent autonomy, and inbound-demand admission
• Presence annotation: declare which energy levels a component or view belongs to
• Focus sessions: time-boxed suppression windows with auto-expiry and break nudges
• A notification gate that enforces threshold, batching, and defer-not-drop at runtime
• A DOM adapter, React provider and hooks, persistence adapters, and deterministic clocks for testing

Why infrastructure first

Kumbatio's thesis is that energy-awareness shouldn't be a feature of one app - it should be a capability any software can have. Shipping the model as an open-source SDK means:

• The apps share one model. Anasa and Nami run on the same engine, so an energy level means the same thing in both. MPath's own model predates the SDK and is planned to bridge to it; the point of publishing the model as a package - and as a spec with conformance vectors - is that bridging is a defined job rather than a guess.
• Anyone can build with it. Developers outside Kumbatio can make their own products energy-aware without adopting anything else from the ecosystem. The first proof: Meltemi, an email client from entro314 labs (the studio behind Kumbatio) built outside the Kumbatio product line, runs its notification deferral, focus sessions, and inbox scoping on this SDK - and nothing else from the ecosystem.
• The model is inspectable. The claims Kumbatio makes about adaptation aren't marketing - they're readable code.

In production

The SDK isn't just installable - it's shipped:

• Anasa - Kumbatio's writing workspace, in public alpha, runs its entire adaptive shell on the engine: custom persistence, energy-gated AI surfaces, notification filtering, and task-complexity guidance.
• Meltemi - an email client in private beta from entro314 labs, built outside the Kumbatio product line. Energy level drives inbox scope, undo-send windows, UI density, and a defer-not-drop notification gate. The widest use of the API surface anywhere: presence gating, deferral presets, autonomy limits, and inbound demand admission.
• Nami - Kumbatio's AI cognitive-support copilot, in development. Built on the React entry point: a provider at the root, with the level driving assistant copy, planning output, and how much the assistant may do unattended.
• kumbat.io - the marketing site itself adapts to the energy level you set on it.

Two more entro314 labs applications are integrated and still pre-release:

• Entromail - a webmail platform. The dashboard consumes the engine wholesale: level-derived thread density, snooze ordering, hint copy from describeEnergy, and interaction forgiveness across the reading surfaces.
• Equidock - a desktop canvas app. Uses the engine and a custom SQLite persistence adapter for the dial itself; the strategy tables are not wired up yet.

The patterns these integrations proved out are written up in the production patterns guide.

Where to go next