RocheDB v0.5.0: Data Locality for RAG and LLM Retrieval

KoutenDB v0.5.0 has been released.

Release:
github.com/puffball1567/koutendb/releases/tag/v0.5.0

KoutenDB is an open-source NoSQL document and vector store written in Nim.

The project is built around one idea:

Data locality should be part of the database model, not only an accidental
result of indexes, caches, or application code.

A lot of database performance discussions start with indexes, query syntax, or
caches. Those are important. But layout often decides whether a system is
working with the hardware or asking it to fight back.

KoutenDB v0.5.0 is a step toward making locality explicit at three levels:

• logical placement with rings;
• related-data retrieval with stellar locality;
• physical layout visibility with WAL locality reporting.

Ring locality

KoutenDB uses a ring as a semantic and structural placement unit.

An application, import rule, or operator chooses a ring when writing data:

users/123/profile
users/123/orders
shops/1123/orders
docs/japan/support
tenant/acme/orders/2026

Enter fullscreen mode Exit fullscreen mode

That ring is not only a directory-like label. It is a coordinate in the
retrieval space.

When a request already knows its natural locality, KoutenDB can open that local
region first instead of scanning unrelated records and filtering later.

kouten put --ring=docs/japan --payload='{"title":"Refund guide","status":"draft"}' --codec=json

kouten get --ring=docs/japan --filter='{"status":"draft"}' --selection='{ title }'

Enter fullscreen mode Exit fullscreen mode

The important part is not the string syntax. The important part is that
placement and retrieval scope are connected.

Short version: a ring is both where data is placed and where retrieval can
start.

Not only point reads

Point reads are important, but many real applications need related data.

For example, a user page may need profile data, orders, billing information,
and support metadata. In a relational database, that often becomes joins. In a
document database, it often becomes manual denormalization or multiple
application-side reads.

KoutenDB v0.5.0 adds a locality mechanism for this kind of shape: stellar
locality.

A stellar group is a read lens over nearby rings. It lets related rings be read
together without pretending that all data must live in one document.

kouten stellar attach --stellar=user-123 --ring=users/123/profile
kouten stellar attach --stellar=user-123 --ring=users/123/orders
kouten stellar attach --stellar=user-123 --ring=shops/1123/orders

kouten get --stellar=user-123

Enter fullscreen mode Exit fullscreen mode

The same stellar view can be narrowed:

kouten get --stellar=user-123 --subring=orders --limit=20

Enter fullscreen mode Exit fullscreen mode

This is not meant to replace every join. It is meant to cover a different
pattern:

When the application already knows that several rings are useful neighbors,
make that locality available to the database.

Why this is different from a secondary index

A secondary index usually gives another path to find rows by a key.

That is useful, but it can also fight the primary layout. The index finds the
matching keys, then the database may still need to jump around to fetch the
records themselves.

KoutenDB’s current approach is more conservative. Secondary access should guide
the query back toward ring-local reads where possible.

In v0.5.0, stellar locality is not a global secondary index. It is a locality
lens over rings that are already meaningful to the application.

That keeps the model simple:

• rings define local placement;
• stellar groups define related local regions;
• filters and projections narrow the result after the local scope is chosen.

kouten get --stellar=user-123 --filter='{"status":"paid"}' --selection='{ title status }'

Enter fullscreen mode Exit fullscreen mode

This is why KoutenDB is not just “routing by path.” The ring path is part of the
query plan, and stellar locality lets related ring coordinates become a
retrieval unit.

Physical locality

Logical locality is not enough by itself.

If the storage layer gradually becomes fragmented, the first clean benchmark
does not mean much. Real workloads mutate, delete, backfill, and query from odd
angles.

KoutenDB v0.5.0 adds early physical locality visibility through WAL locality
reporting:

kouten locality

Enter fullscreen mode Exit fullscreen mode

The goal is to make locality observable before building heavier compaction and
layout optimization features.

This is still early, but the direction is clear:

• show how records are grouped physically;
• make locality drift visible;
• provide a base for future compaction;
• avoid hiding layout problems until performance has already degraded.

There is also a locality layout demo:

examples/locality_layout_demo.sh

Enter fullscreen mode Exit fullscreen mode

And a stellar data model demo:

examples/stellar_data_model_demo.sh

Enter fullscreen mode Exit fullscreen mode

Write patterns and mutation

KoutenDB should not assume that writes are always clean.

Applications backfill data. Imports arrive in imperfect order. Some records are
attached to related data later. Some records are detached later.

v0.5.0 adds attach/detach workflows for stellar locality:

kouten stellar attach --stellar=user-123 --ring=users/123/orders
kouten stellar detach --stellar=user-123 --ring=users/123/orders
kouten stellar list --stellar=user-123

Enter fullscreen mode Exit fullscreen mode

This makes the locality model adjustable without rewriting the whole dataset.

The current implementation is intentionally modest. It focuses on making
relationships explicit and testable first. Heavier compaction and automatic
relocation are better handled after the behavior is observable.

Atomic workflows

KoutenDB v0.5.0 also adds embedded atomic batch helpers:

• atomic batch put;
• atomic batch update;
• atomic batch delete.

These are designed for application workflows where a group of related changes
should either commit together or not commit at all.

There are also cooperative coordinate locks:

• ring locks;
• stellar locks;
• TTL-based lock expiry;
• release-on-exception helpers.

These locks are opt-in. Normal lightweight NoSQL reads and writes do not pay
for them unless the application chooses to use them.

The goal is not to turn KoutenDB into a financial ledger. The goal is to support
higher-integrity application workflows without losing the ring-first retrieval
model.

What the benchmarks are testing

The main KoutenDB benchmark claim is not “always faster than every database.”

The narrower claim is:

If locality is meaningful, KoutenDB can reduce how much unrelated data must be
read, held, ranked, transferred, or passed downstream.

The current benchmark documents include working-set, memory-pressure,
RAG-oriented, PostgreSQL, and Redis comparison helpers.

Some examples from the repository:

Working-set benchmark

With 100 rings and 10,000 documents, scanned records per query dropped from
10,000 to 100.

Memory-pressure benchmark

With 100 rings, 100,000 documents, and 512-byte payloads, estimated candidate
memory per query dropped from 93.079 MiB to 0.931 MiB.

Synthetic RAG benchmark

Recall stayed at 1.000 while scanned records per query dropped from
8,000 to 1,000, and estimated tokens per query dropped from 3960 to
657.8.

These are local synthetic and generated benchmarks, not universal performance
claims. The scripts are in the repository so the numbers can be reproduced,
challenged, and improved.

What is still open

There are still important layout questions to solve.

The biggest ones are:

• preserving physical locality as data mutates;
• compaction behavior over time;
• backfill-heavy workloads;
• secondary access paths that do not fight the primary ring layout;
• dynamic cluster membership without unnecessary remapping;
• deeper real-world benchmarks.

The current v0.5.0 work does not pretend those are solved forever. It gives
KoutenDB clearer mechanisms for observing and testing them.

Why I think this direction matters

Many systems already know their useful locality:

• tenant;
• user;
• region;
• product area;
• document topic;
• time window;
• prompt or context domain;
• game world entity;
• application workflow.

Often that information is known by the application but not directly usable by
the database as a retrieval primitive.

KoutenDB tries to close that gap.

It does not ask every workload to become a KoutenDB workload. It is most
interesting when the application can place data in meaningful local regions and
then benefit from reading those regions directly.

That is the direction of v0.5.0: make locality explicit, observable, and useful
enough that it can become part of the database design itself.

Repository:
github.com/puffball1567/koutendb

Release:
github.com/puffball1567/koutendb/releases/tag/v0.5.0