Skip to content
EN FR

Embedding Registry

Documentation status: architecture — see Maturity and evidence.

The embedding registry is the bridge between conceptual identity and vector identity.

Why a registry exists

A vector index knows how to compare vectors, but it does not inherently know which concept a vector represents. The registry makes this relation explicit and reversible.

Customer#42 <-> [0.12, -0.44, ...]
Document#7 <-> [0.81,  0.03, ...]

The conceptual value remains the semantic object. The vector remains a numerical representation.

Current invariants

Within one named registry, the current engine enforces these invariants:

  1. one registered conceptual value resolves to one registered embedding vector;
  2. one registered embedding vector resolves back to one conceptual value;
  3. registering the same pair again is idempotent;
  4. trying to remap either side to a conflicting partner is rejected;
  5. registry names define isolated embedding spaces.

These invariants are important for explainability: a nearest-neighbor result can be traced back to the exact conceptual value that owns the vector.

Named spaces

Use separate registry names when embeddings have different semantics, for example:

product-description-v3
support-ticket-v2
concept-structural-embedding

A registry name should identify an embedding space, not merely a deployment machine. Two registries may contain embeddings for the same concepts if they represent different models or projection policies.

Search bridge

The basic conceptual search flow is:

query vector
 -> HNSW scored neighbors
 -> registry vector-to-value resolution
 -> conceptual candidates

Vectors present in the HNSW index but absent from the registry do not become symbolic candidates. The current engine skips them.

When the caller expects a conceptual kind, the engine can combine numerical retrieval with symbolic instance checking:

retrieve candidate vectors
 -> resolve symbolic values
 -> IsInstanceOf(expected kind)
 -> retain compatible values

This is a hard filter, not a soft embedding hint. A numerically closer value can therefore be rejected in favor of a farther value whose symbolic kind is compatible.

A strictness option controls the instance-compatibility test. Treat that option as part of the semantic query definition, not as a performance tuning flag.

Updating embeddings

Because conflicting remapping is rejected, changing a vector should be handled as an explicit update/rebuild operation for the embedding space. A robust update flow is:

new model/version
 -> create or migrate registry/index
 -> generate vectors
 -> register identities
 -> build/search-test index
 -> switch consumers
 -> retire old space

This avoids making an index temporarily inconsistent with its conceptual mapping.