Why KoutenDB Exists: You Know the Center, Not the Boundary

Most database queries begin by describing the answer.

You provide a primary key, write a SQL predicate, select a collection, enter
search terms, or send an embedding to a vector database. The database then
finds the records that match.

That model works extremely well, but it is not the shape of every application
request.

Sometimes the application knows where the answer should begin, while the
complete boundary of useful information is still unclear.

For example:

• a support request starts with a customer, but may need their profile, recent orders, the product involved, previous tickets, and a refund policy.
• an incident investigation starts with a service and a point in time, but may need a nearby deployment, error logs, metrics, and related service events.
• a RAG request starts with a project or topic, but the useful context may span documents, summaries, source metadata, and attached knowledge.
• a game request starts with a player or place, but may need nearby entities, inventory, quests, and regional state.

In each case, the center is known. The exact context boundary is not.

That is the problem KoutenDB was created to explore.

Exact lookup is not the same as context retrieval

Suppose an API receives an order ID.

Finding the order itself is easy. Almost any database can do that efficiently.
The harder question is what else should travel with it.

Should the response include the customer? The shop? Recent payment events? The specific product documentation? An unresolved support ticket? The answer may depend on the request, product, current state, and amount of context the caller can afford to process.

A conventional application can assemble that context with:

• SQL joins;
• several document lookups;
• application-maintained ID lists;
• a graph traversal;
• metadata filters;
• full-text or vector search;
• a cache built for one response shape.

These are all valid solutions. But they usually require the application to reconstruct the neighborhood every time it reads.

KoutenDB asks a different question:

What if the database preserved useful locality when the data was written, so
a later read could begin from that locality directly?

A ring is a coordinate, not just a container

KoutenDB stores a record with a coordinate-like ring.

users/123
users/123/orders
users/123/support
shops/1123
orders/A-001
products/sku-9/docs

The names are readable, but readability is not their main purpose. A ring is part of data placement and part of the read path.

If the application starts from users/123, KoutenDB can inspect that local hierarchy without beginning with an unrelated global collection. If it starts from orders/A-001, it can use an order-centered view instead.

This turns locality known by the application into retrieval information the database can retain.

The same data can be visible from another center

Related context does not always fit one permanent hierarchy. An order belongs to a customer, a shop, and a product at the same time.

KoutenDB therefore has a stellar lens. It can attach existing rings to a useful center without copying their payloads.

kouten put --ring=users/123 \
  --payload='{"kind":"user","name":"Alice"}' --codec=json

kouten put --ring=shops/1123 \
  --payload='{"kind":"shop","name":"Orbit Store"}' --codec=json

kouten put --ring=orders/A-001 \
  --payload='{"kind":"order","orderNo":"A-001","total":42}' --codec=json

kouten stellar attach \
  --stellar=commerce/order/A-001 --ring=users/123

kouten stellar attach \
  --stellar=commerce/order/A-001 --ring=shops/1123

kouten stellar attach \
  --stellar=commerce/order/A-001 --ring=orders/A-001

Now the application can read from the order as the center:

kouten get --stellar=commerce/order/A-001

The original records remain in their original rings. Attaching or detaching a ring changes what the lens can see; it does not duplicate or delete the payload.

This is useful when the same information needs to participate in several context views without turning each view into another copied document.

Example: retrieving useful information around a tourist destination

Travel information makes the center-versus-boundary problem easier to see.

Imagine that a visitor is looking at Kiyomizu-dera in Kyoto. The application knows the starting point, but a useful response probably should not contain only the temple record.

The visitor may also need:

• other nearby landmarks;
• restaurants and cafes;
• museums, galleries, and cultural facilities;
• events taking place that day;
• transit information;
• accessibility or opening-hour information.

There is no single permanent boundary for that context. A family, a solo traveler, and someone planning a rainy afternoon may need different parts of the same surrounding information.

An importer or application can keep each place in a canonical ring:

landmarks/kyoto/kiyomizudera
landmarks/kyoto/yasaka-pagoda
restaurants/kyoto/gion
culture/kyoto/national-museum
events/kyoto/2026-07-22
transit/kyoto/higashiyama

It can then attach the useful coordinates to an area-centered stellar lens:

kouten stellar attach \
  --stellar=travel/kyoto/higashiyama \
  --ring=landmarks/kyoto/kiyomizudera

kouten stellar attach \
  --stellar=travel/kyoto/higashiyama \
  --ring=landmarks/kyoto/yasaka-pagoda

kouten stellar attach \
  --stellar=travel/kyoto/higashiyama \
  --ring=restaurants/kyoto/gion

kouten stellar attach \
  --stellar=travel/kyoto/higashiyama \
  --ring=culture/kyoto/national-museum

kouten stellar attach \
  --stellar=travel/kyoto/higashiyama \
  --ring=events/kyoto/2026-07-22

The application can now begin with the Higashiyama area and retrieve the attached tourism context in one read:

kouten get --stellar=travel/kyoto/higashiyama

Or it can narrow the same view to restaurants or cultural facilities:

kouten get --stellar=travel/kyoto/higashiyama --subring=restaurants
kouten get --stellar=travel/kyoto/higashiyama --subring=culture

The same restaurant can also be attached to a travel/kyoto/rainy-day lens, a station-centered lens, or a day-plan lens without moving or copying its canonical payload.

KoutenDB does not automatically infer geographic relevance from these names.
The application, importer, or curation process still decides which coordinates belong in the neighborhood. The database's role is to preserve that decision and make it directly readable later.

This is the intended meaning of surrounding information: the caller starts from a useful place, receives several categories of nearby context together, and can narrow the field of view without having to list every individual place in the request.

Is this just a path?

A ring such as landmarks/kyoto/kiyomizudera certainly looks like an ordinary path. KoutenDB deliberately uses readable hierarchical names because paths are a useful way to express parent and child locality.

But a path by itself provides only hierarchy.

If all tourism data lived under one tree, an application could read a prefix
such as travel/kyoto/higashiyama/*. That works when every useful relationship fits the same permanent hierarchy and the caller already knows which branches to request.

The difficulty is that real data belongs to several contexts at once:

• a restaurant belongs to its canonical restaurant catalog;
• geographically, it belongs to an area;
• operationally, it may belong to a currently open list;
• editorially, it may belong to a rainy-day guide;
• personally, it may belong to one visitor's itinerary.

Duplicating the same record under every path creates synchronization and consistency work. Moving it into one path makes the other views harder to express. Storing only path strings leaves the application responsible for maintaining and joining all of those relationships.

KoutenDB adds two things beyond the path syntax:

1. the ring hierarchy is understood by the retrieval engine and can be traversed with explicit depth, branch, filter, limit, sort, and projection controls.
2. stellar metadata can connect rings from different hierarchies into another coordinate-centered view without changing their canonical paths or copying their payloads.

The stellar lens is therefore not another directory. It is a stored visibility relationship across existing coordinates.

The same ring coordinate can also act as a boundary for authorization, dump/import, placement, and synchronization. A plain path string has none of those database semantics unless the application builds them separately.

So the path is the readable address. The KoutenDB-specific part is how that address participates in placement, neighborhood retrieval, and reusable views across otherwise separate branches.

Not knowing the boundary does not mean an unbounded query

"The caller does not know the exact boundary" should not mean "read
everything."

The caller still controls the field of view. KoutenDB can narrow a read with:

• a subring;
• hierarchy depth;
• branch budget;
• per-ring limits and sorting;
• filters;
• field selection;
• an overall result limit.

For example, the same order-centered view can request only shop data or only a small projection:

kouten get --stellar=commerce/order/A-001 --subring=shops

kouten get --stellar=commerce/order/A-001 \
  --selection='{ kind name orderNo total }'

The distinction is important:

The application supplies a meaningful center and a cost boundary. It does
not have to enumerate every record relationship that may form the answer.

This is why KoutenDB is intended for surrounding information rather than only exactly bounded queries.

Why not use a collection or partition key?

Collections, namespaces, partitions, and shards can already reduce the amount of data a database examines.

The difference is what they represent.

A partition key commonly answers questions such as:

• Where is this record stored?
• Which node owns it?
• Which partition can be pruned?

KoutenDB also wants locality to answer:

• What information is likely to be useful around this record?
• Which nearby rings should enter the current field of view?
• Can the same existing ring become visible from another useful center?

That makes placement an application-visible retrieval concept, not only an internal scaling decision.

Why not begin with vector search?

Vector search answers a valuable question:

Which items are semantically similar to this query?

But similarity is not the same as operational relevance.

A customer's latest order, a permission record, and the applicable refund policy may be necessary context even when their embeddings are not the closest matches in a global corpus. Systems often compensate by adding namespaces and metadata filters before vector ranking.

KoutenDB makes that first narrowing step the main data model:

1. begin from a known user, order, tenant, topic, place, or time coordinate;
2. open the useful local neighborhood;
3. apply filters, vector ranking, reranking, or an LLM only to that smaller working set when needed.

Vectors remain useful. They are optional rather than the only way to discover related context.

For local AI and RAG systems, that distinction can matter. The expensive work is not limited to the final LLM call. Loading candidates, comparing vectors, reranking chunks, transferring payloads, and filling a context window all have a cost. A smaller first-stage working set can reduce work throughout the pipeline.

Why not keep this entirely in application code?

An application can maintain arrays of related IDs, write join tables, perform fan-out reads, and build cached response documents. Many applications already do.

The tradeoff is that locality becomes scattered across code and supporting infrastructure. One rule determines reads, another determines authorization, another controls exports, and another decides how data should be copied or synchronized.

KoutenDB's larger design goal is to let the same coordinate participate in:

• retrieval scope;
• authorization scope;
• dump and import boundaries;
• placement and compaction;
• delayed synchronization between topologies.

The value is not just fewer lines in one query. It is keeping the application's concept of locality visible across the data lifecycle.

The database cost should follow the working set

Let the complete corpus contain N records, while the useful neighborhood for one request contains k records.

Many systems eventually introduce a first-stage index or filter so later work does not operate over all N. KoutenDB's central bet is that meaningful placement can provide part of that first stage directly.

The goal is to make more of the request cost follow k, the useful local working set, instead of repeatedly rediscovering locality from the full corpus.

This is not an automatic performance guarantee. It depends on whether the application can express useful locality. If all queries are arbitrary and global, there may be no meaningful center to exploit.

But many applications already begin with one:

• an authenticated user;
• a tenant;
• an order;
• a product;
• a project;
• a document group;
• a region;
• a service and time window;
• an entity in a simulation.

KoutenDB makes that starting knowledge part of the database query model.

When this model is useful

KoutenDB is worth examining when all three of these statements are true:

1. requests naturally begin from a known coordinate;
2. the application frequently needs surrounding context, not only one exact record;
3. the useful context can be placed or attached meaningfully before it is requested.

It is less relevant when the main workload is arbitrary full-corpus analytics, global full-text search, independent lookup on every field, or strict relational constraints. Those problems already have databases built around them.

The reason for another database is not that existing databases forgot how to look up records.

It is that a growing class of application and AI requests does not begin with a complete description of the answer. It begins with a center.

KoutenDB exists to make that center useful.

The implementation, data-model demo, and reproducible benchmarks are available in the KoutenDB repository.