Concepts

The Platform engine

Platform is the open knowledge-base engine. It is the piece a developer can run entirely on their own machine to get a complete, single-tenant KB: a database, the engine, and the runtime, brought up together.

Kvendra Platform (AGPL-3.0) is written in TypeScript (Node 20.x) on a stack of Fastify HTTP server + PostgreSQL 16 + pgvector.

The open knowledge-base engine: a single-tenant KB you self-host. A developer brings it up with docker-compose to get their own complete local KB — Postgres + pgvector + engine + skills runtime.

What the engine gives you

  • The KB engine: 20 entity types, the entity + transaction + typed server-side changelog model, relations, history, transactions.
  • Pluggable embeddings (bring-your-own provider).
  • Basic auth: static HTTP token / API key.
  • Self-host stack: docker-compose + multi-stage Dockerfile.
  • Public engine API: an MCP server over JSON-RPC (Fastify), moving to a streaming HTTP transport.

Embeddings are pluggable; the wire alias kvendra-embedding-v1 is stable across providers (1024-dimension, L2-normalized). A deterministic mock provider is used in staging; a hosted Titan-class provider is the production target.

Semantic search ranks entities by cosine similarity over the embedding vectors.

Why a vector database

A knowledge base is only useful if you can find the right entity when you describe it in your own words rather than by its exact id. Keyword search misses that: "how do I avoid leaking tokens" should surface the broker and the allowlist even though those words may not appear verbatim. That is a similarity problem, and similarity is best expressed as distance between vectors — hence a vector database.

Kvendra uses PostgreSQL with the pgvector extension, so the same database holds both the relational entity data and the vector index. One store, one transaction boundary, no separate search service to keep in sync.

What an embedding is

An embedding is a fixed-length list of numbers — a vector — that captures the meaning of a piece of text. Texts that mean similar things map to vectors that point in similar directions. Kvendra's embeddings are 1024 numbers long and are L2-normalized, meaning every vector is scaled to unit length so that only its direction carries meaning.

The vector shape is wire-stable under a fixed alias, so the engine can swap the underlying model without breaking stored vectors or downstream consumers.

Search by cosine similarity

To find the entities most relevant to a query, the engine embeds the query into the same 1024-dimension space and ranks stored entities by the cosine of the angle between their vector and the query's. Because the vectors are unit-length, cosine similarity reduces to a dot product: fast, and directly supported by the vector index. 

-- Conceptually: rank entities by closeness to a query embedding.
-- (<=> is pgvector's cosine-distance operator; smaller = closer.)
SELECT entity_id, title
FROM entity
ORDER BY embedding <=> :query_embedding
LIMIT 10;