Architecture
How entity storage, the index, and the embedder divide responsibilities and process data.
Three layers
Omnio combines three components with different responsibilities.
| Layer | Interface | Responsibility |
|---|---|---|
| Entity | IOmnioEntity |
Stores bytes under an entityId. |
| Index | IObjectIndex |
Stores keys, metadata, tags, embeddings, and purge reservations. |
| Embedding | IEmbedder |
Converts text or images into Float32Array values. |
This separation lets you choose byte storage and metadata search independently. For example, bytes can live on a local file system while the index lives in PostgreSQL.
Write path
putObject processes a write in this order.
- Validate the input and convert the key to an
OmnioKey. - Convert the data to bytes.
- Generate an embedding when a description exists and embedding is enabled.
- Read the existing record for the same key from the index.
- Create a new
entityIdand record a purge reservation in the index. - Write the bytes to entity storage and compute SHA-256.
- Store metadata and the hash in the index.
- Remove the purge reservation that is no longer needed.
The reservation in step 5 is written first so that an unreferenced entity can be reclaimed if the process crashes between steps 6 and 7.
Read path
headObject and listObjects read only the index. They do not touch entity storage.
getObject and streamObject first read the entityId and hash from the index, then read bytes from entity storage. If a record exists but its bytes do not, Omnio throws EntityMissingError.
Search path
searchObjects processes a query in this order.
- Embed the query. Text and image queries use
IEmbedder. - Call
searchon the index. - The index applies
filterand excludes dirty and deleted rows. - It computes similarity and returns results in descending score order.
- With
includeEmbedding: false, it removes embeddings from the results.
Text and image queries consider only rows whose model name matches the current embedder. This prevents vectors from different models from being mixed.
Background work
open() starts background work.
- Deletion reclamation: physically deletes entities whose grace period has passed.
- Reservation draining: processes purge reservations left by a crash or an interrupted operation.
- Reindexing: rebuilds embeddings for objects whose model or dimensions changed.
Background work never blocks reads. Searches consider only rows that are complete at that moment.
Locks
Omnio uses asyncmux to coordinate lifecycle changes and operations.
openandclosetake an exclusive lock.- Normal operations take a shared lock and can run concurrently.
- Writes to the same key are serialized with a per-key exclusive lock.
- Operations that touch several keys acquire them in sorted order to avoid deadlocks.
SQL indexes also use shared locks for reads and exclusive locks for writes.
Why separate the layers
- Byte storage can use a file system, OPFS, or cloud storage depending on the deployment.
- Metadata search can use SQL filtering and transactions.
- Embedding models can be swapped for accuracy, speed, or modality support.
Clear responsibilities let the same API cover an in-memory test setup and a production PostgreSQL setup.