Mnemosyne — A Caching Library in Python, Go & Rust

A small, focused caching library implementing common caching strategies (starting with LRU, expanding from there) in Python, Go, and Rust — built as a hands-on way to go deep on caching concepts and produce something reusable across future projects in any of the three languages. Part of the mnemosyne-cache organization; this repo is the Python implementation.

Caching strategies (LRU, LFU, write-through, cache-aside, etc.) come up constantly in backend and systems design work, but "I've read about it" and "I've implemented it correctly, twice, in two different languages" are very different levels of understanding. This project exists to close that gap directly, not just talk about it.

• Python implementation — mnemosyne/, with lru/ (LRU cache), ttl/ (TTL / expiring cache), and data_structures/ (shared, cache-agnostic building blocks — currently a hand-built doubly linked list, used by lru/ for eviction ordering; lives outside lru/ since it has no inherent connection to caching). MVP complete — both cache types are functionally done.
• Go implementation — post-MVP, not started, lives in its own mnemosyne-go repo. Once it begins it'll mirror the same shape as the Python side (lru/, ttl/, data_structures/).
• Rust implementation — post-MVP, sequenced after Go, will live in its own mnemosyne-rust repo, mirroring the same shape.
• Each implementation is self-contained, idiomatic to its language, and tested independently. The goal isn't a 1:1 port line-by-line — it's correctly implementing the same concepts in each language's natural style.

• LRU cache (Python) — done, MVP
• TTL / expiring cache (Python) — done, MVP
• Go implementation (LRU + TTL) — planned, post-MVP
• Rust implementation (LRU + TTL) — planned, post-MVP
• LRU + TTL combined — planned, post-MVP
• LFU (Least Frequently Used) — planned, post-MVP
• Write-through vs. cache-aside patterns — planned, post-MVP
• Distributed caching (Redis-backed) — planned, post-MVP

MVP complete. Both cache types are built for real (not a throwaway translation) directly in Python (full detail in DESIGN.md's Roadmap) — Go and Rust are out of MVP scope, moved to post-MVP (Go first, then Rust) so the Python side shipped complete before a second language starts (see DESIGN.md's Decided, 2026-07-27 and 2026-08-22) — loosely inspired by MosheWorld/CacheStrategies's two actual implementations:

• LRU cache — manual hash map + doubly linked list, capacity-based eviction only, no shortcuts (OrderedDict / container/list). Python implementation (mnemosyne/lru/) is functionally complete — get/put/has/delete/clear/keys/size, with eviction and recency tracked entirely by the doubly linked list rather than borrowed from dict ordering — and has its own unit test suite covering happy paths and failure modes (invalid capacity, eviction under full load, refresh-on-access, updating an existing key, empty-cache edge cases, deleting a missing key). The doubly linked list it's built on (mnemosyne/data_structures/) also has full unit test coverage and a locked-down mutation surface (read-only first_node/last_node/key, structural changes only via its own methods).
• TTL / expiring cache — hash map with time-based expiration as the primary mechanism, plus capacity-based eviction as a backstop against unbounded growth (see DESIGN.md's Decided, 2026-08-24). Python implementation (mnemosyne/ttl/) is functionally complete — get/put/has/delete/clear/keys/size, with put()/get()/has() all refreshing an entry's expiration on access (sliding TTL) — and has its own unit test suite covering happy paths and failure modes (invalid capacity and invalid TTL, eviction under full load, updating an existing key, expired-key access, empty-cache edge cases). (The reference repo calls its version of this "client-side caching," but that's a browser-storage concept that doesn't apply here — what's reusable is the TTL logic.)

Packaging and CI are in place for the Python side: pip-installable via pyproject.toml, tests run through pytest with coverage reporting, and GitHub Actions runs the suite on every push/PR to main.

Post-MVP: the Go and Rust implementations (both cache types each, Go first), combining LRU + TTL into one cache, LFU, write-through vs. cache-aside, and Redis-backed distributed caching (not hand-rolled).

(To be filled in once the first implementation has a stable API.)

MIT