KoutenDB: A Database Built in Nim to Reduce Retrieval Work Through Data Locality
Hi everyone,
I’m the author of KoutenDB, an open-source locality-first document database written in Nim, with ring-scoped vector retrieval.
https://github.com/puffball1567/koutendb
KoutenDB is built around a locality-first retrieval model.
Applications and import rules place related data into explicit coordinates called rings. A ring is more than a category or routing label: it defines the initial candidate set and maps to ring-local persistent storage and cluster routing.
For example, data related to one user can be placed around users/123, with nearby subrings for profiles, addresses, orders, and notifications. KoutenDB can retrieve that related group together or narrow the read to selected subrings.
The goal is to avoid starting with a large unrelated dataset and filtering or reranking it afterward. This can be useful for RAG and LLM workloads, where every unnecessary candidate may also consume memory, ranking work, and context tokens.
Vector retrieval is supported, but vectors are not the basis of the data model. They are one possible ranking step after locality has narrowed the candidate set.
Some results from the included reproducible benchmarks:
- Working-set benchmark: scanned records per query decreased from 10,000 to 100.
- Memory-pressure benchmark: estimated candidate memory per query decreased from 93.079 MiB to 0.931 MiB.
- Synthetic RAG benchmark: recall remained 1.000 while scanned records per query decreased from 8,000 to 1,000 and estimated tokens per query decreased from 3,955 to 657.
- Generated AI/RAG JSONL case study: recall remained 1.000 while scanned records per query decreased from 400 to 40 and estimated tokens per query decreased from 615.2 to 231.6.
The benchmark scripts and generated datasets are included in the repository so that the results can be reproduced and examined.
KoutenDB also carries locality into persistent storage. Ring-local segments allow disk-backed reads to open the relevant ring data instead of replaying or scanning the complete database.
In an included 1,050,000-record related-data benchmark, KoutenDB retrieved a multi-subring user bundle in 196.859 microseconds. In the same included comparison, the equivalent logical result measured 515 microseconds using six indexed PostgreSQL queries and 236 microseconds using a PostgreSQL JSON aggregate query.
I have also been testing operational stability. A three-node persistent KoutenDB cluster completed a 72-hour Ubuntu run with 4,022,516 mixed client operations, zero client errors, successful offline verification of every data directory, and no fallback to global retrieval.
The trade-off is that applications or import rules need to choose meaningful rings. If useful locality is not known in advance, retrieval may still require a broad scan.
KoutenDB currently supports embedded and TCP server modes, persistent storage, exact ring-scoped vector retrieval, transactions, locks, backup and restore, corruption detection, cluster routing, and a C ABI. Language bindings and driver foundations are available for Rust, JavaScript/TypeScript, Python, PHP, and C++.
The project is currently at v0.12.0.
I’d especially appreciate technical feedback on the ring-local storage model, retrieval design, physical locality, and the Nim implementation.