Documentation menu
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.

Search ranks entities by semantic similarity, so a query finds the right thing by meaning rather than by exact keyword match.

Semantic search over your content via pgvector; the embeddings provider is configurable, so the same data and search behave consistently whichever provider you pick.

What Platform is for

Platform keeps the structured knowledge of your project — its components, requirements, decisions, issues, tests, releases — in one place your agent can read and write. Crucially, it lets you find the right thing by describing it, not by knowing its exact id or the exact words used when it was written. Ask "how do we avoid leaking tokens" and it surfaces the broker and the allowlist even if those words never appear verbatim.

That is the whole promise: a project memory that stays organised as it grows, and that answers questions by meaning rather than by literal keyword match.

How it finds things by meaning

Under the hood the engine uses embeddings for semantic retrieval: text is turned into vectors so that things which mean similar things end up close together, and a query finds the nearest matches. You do not need to think about any of this to use Platform — it is an internal detail of how search ranks results. Kvendra stores both the entity data and these vectors in the same PostgreSQL database (via the pgvector extension), so there is no separate search service to keep in sync.

It is Postgres all the way down — your data, in your database, with a clean export. There is no proprietary store to escape from.

Learn more about vector search: pgvector, the open-source extension Kvendra builds on.

Where embeddings come from

Something has to turn text into those vectors, and that is the one knob you may care about when installing — a single setting, EMBEDDINGS_PROVIDER, picks where it happens. There are three modes:

  • Ollama (recommended) — vectors are computed by a model you run yourself, so nothing about your text leaves your infrastructure.
  • Kvendra Cloud free-tier — a hosted endpoint computes them for you. Zero setup, when you would rather not run a model locally.
  • Mock — deterministic stub vectors, for CI and tests where you want reproducible builds and no model dependency.

The vector shape is wire-stable under a fixed alias, so the provider is an operational choice, not a lock-in: stored data and semantic search behave the same whichever mode you pick.