About NimbusKV
The design philosophy, architectural evolution, maintainer attribution, and engineering goals behind NimbusKV.
What NimbusKV is
NimbusKV is a reactive, TTL-aware, concurrent in-memory key-value store for Python. It provides lock-free reads always, deterministic write mutex concurrency, event-driven reactive subscriptions, and pluggable write-through persistence backends (SQLite and Redis).
It is designed to run cleanly on standard GIL Python (3.9 through 3.13) while adapting automatically to free-threaded Python (3.13t and 3.14t), where concurrent read operations execute with true multi-core CPU parallelism.
Why v3 exists: Architecture Rewrite
Version 2 of the library was structured as a conventional dictionary with TTL checks, callbacks, and a timeout wrapper labeled as a "sandbox". It recombined features that established libraries like cachetools already solved.
NimbusKV v3 was engineered from the ground up as a completely different architecture:
State is stored inside an immutable persistent map (HAMT). Readers inspect the current snapshot with zero locking, regardless of concurrent write traffic.
Starting in v3.1.0, each write acquires a brief lock to build and publish the new snapshot. This replaced the CAS retry loop from v3.0.1, eliminating retry storms under hot keys.
One unified codebase that detects the GIL state at import time. On free-threaded runtimes (3.13t/3.14t), concurrent threads read state simultaneously across cores.
Replaced manual locking with atomic read-modify-write mutations, guaranteeing mutations execute exactly once under the write mutex.
Core Technical Pillars
- Real Async: For in-memory operations,
aget()andaset()are truly non-blocking. They never spawn executor threads for work that is not I/O. Only real I/O (SQLite/Redis writes) is delegated to an executor. - Reactive Subscriptions:
subscribe()notifies callbacks for set, delete, and expire events.wait_for()suspends threads until a condition evaluates to true without polling loops. - Write-Through Persistence: Memory is always the live source of truth. SQLite or Redis backends mirror data write-through for durability and rehydration on startup.
What is explicitly not in v3
- Sandboxed callback execution: Version 2 featured a callback wrapper marketed as a "sandbox". In practice, it was merely a timeout mechanism rather than true process isolation. Calling it a sandbox was misleading. It was removed rather than kept under a false name.
- Manual locking (`lock()` and `unlock()`): Manual locks invited deadlocks and races under concurrency. They were eliminated in favor of deterministic
atomic()andmutate()primitives.
Project History & Renaming
NimbusKV was originally created and published under the name LiveDict. As the scope grew from a reactive dictionary into a high-concurrency infrastructure library with pluggable persistence, HAMT snapshots, and free-threaded runtime support, the project was renamed to NimbusKV.
With release v3.1.0, the licensing model transitioned from GPL-3.0 to the permissive Apache License 2.0, allowing broader adoption across commercial and open-source applications. Prior versions (3.0.1 and 3.0.0) remain under GPL-3.0.
Maintainer & Legal Attribution
Copyright: Copyright 2026 Hemanshu Vaidya.
Author & Maintainer: Hemanshu Vaidya (github.com/NimbusKV/NimbusKV).
Trademark Notice: "NimbusKV" is a trademark of Hemanshu Vaidya.
Third-Party Dependencies: MagicStack immutables (Apache 2.0) and optional redis-py (MIT).