Embeddings & Vector Search, plus the Semantic KV Store

Embeddings

The engine converts text, images, and audio / speech into dense vector representations that capture semantic meaning. Similar concepts produce similar vectors regardless of the input modality. "A guard patrols the market" and "a soldier watches the bazaar" land close in embedding space even though they share no words; a screenshot of a stone keep and a textual description of a stone keep land close in shared image-text embedding space; two spoken lines with the same intent land close in audio embedding space.

Embeddings run on-device alongside inference. No external API calls, no latency penalty.

Vector Search

Find the most relevant content by semantic similarity. Given a query, the engine searches a built-in vector database and returns the closest matches ranked by cosine similarity.

Use cases:

• Find the right dialogue line for a player's question
• Retrieve relevant lore entries for an NPC's context
• Match player descriptions to authored content
• Surface related items, quests, or locations

Semantic KV Store with Facet Filtering

The KV store combines vector search with metadata filtering. Author content entries with key text, an answer, and structured facets, then query by semantic similarity and filter by metadata simultaneously. Three patterns from real game demos:

Example: Ambient NPC Barks

NPCs react contextually to the player's presence based on occupation, reputation, weather, and time of day. Author hundreds of lines, the engine surfaces the right one at runtime.

{
  "key_text": "guard patrols the market square on a calm day",
  "answer": "Move along, citizen. Market's open, but I've got my eye on you.",
  "facets": {
    "npc_occupation": "guard",
    "player_reputation": "neutral",
    "weather": "clear",
    "time_of_day": "day"
  }
}

Example: Bard Narration

A narrator provides contextual commentary on the player's actions, adapting to location, class, event type, and time of day. Your writers' prose, matched to the moment.

{
  "key_text": "warrior enters a tavern during the day",
  "answer": "The tavern doors swing wide and in strides our warrior, armor catching the afternoon sun! The patrons look up from their midday ales, sizing up the newcomer.",
  "facets": {
    "location": "tavern",
    "player_class": "warrior",
    "event_type": "arrival",
    "time_of_day": "day"
  }
}

Example: Murder Mystery Interrogation

Characters progress through emotional states as the player interrogates them. Gate dialogue behind emotions: calm, nervous, defensive, cornered. Triggers advance the story.

{
  "character_id": "victor_crane",
  "emotion": "nervous",
  "key_text": "pressing about provenance of specific paintings",
  "answer": "Look, I don't appreciate the interrogation. My records are impeccable.",
  "triggers": [
    { "set_emotion": "defensive" }
  ]
}

Other applications

The same pattern (embed an authored corpus once, query it at runtime with a text prompt plus a few facet filters) underpins a long list of in-game systems. Examples we've seen teams build with it: codex / lorebook lookup (player types a question, the right entry surfaces), quest hint and journal recall keyed off the current objective, tutorial and FAQ search over the manual or design docs, shopkeeper haggling and barter lines filtered by item rarity and player reputation, radio / public-address chatter scoped to faction and world state, vendor and trainer banter, memory and gossip systems where NPCs recall prior interactions, party-member commentary reacting to location and recent events, random-encounter and event picking matched to biome and difficulty, procedural quest stitching by selecting authored beats that fit the current state, flavour text for crafting, cooking, and item-use, support-ticket and live-ops macros for chat moderators, accessibility paraphrasing that swaps in simpler authored variants, and retrieval-augmented LLM responses where the model is constrained to ground its replies in your writers' material rather than inventing new lore.

Querying at Runtime

At runtime, query with both a text prompt and facet filters. The engine finds the semantically closest authored content that matches the current game state.

// Search for the right NPC bark
var results = await Atelico.EmbeddingsSearch(
    "asking about the market",
    new Facets()
        .Filter("npc_occupation", "guard")
        .Filter("weather", "clear"),
    5  // top-k results
);

// Use the best match
string dialogue = results[0].Answer;

This surfaces your writers' authored lines at the right moment: not generative slop, but the exact content you crafted, matched to the current game state.

Guardrails Integration

The embeddings system powers the EmbeddingSimilarity checker in the Guardrails Cascade. Content is compared against known-bad examples via vector similarity, catching semantically similar violations that keyword matching would miss, in roughly 2ms.