The single-tenant KB engine at the centre of
Kvendra. Twenty typed entity types, a
transactional changelog, fourteen
MCP tools over Streamable HTTP. Built in
TypeScript, persisted on Postgres + pgvector, AGPL-3.0, docker
self-hosted.
The Platform is what makes Kvendra a system instead
of a copilot. Three things it gives you that a vector store, a
prompt cache, or a chat history cannot:
Typed entities, not blobs. Twenty schema'd entity types — components, contracts, requirements, releases, ADRs, runbooks, incidents — with relations and versioned changelog. Your AI reads structure, not paragraphs.
Transactional pipeline. Every mutation lands inside a transaction (begin · stage · commit / cancel). Skills group their work, the KB stays coherent, and rollback is a built-in primitive — not an after-the-fact migration.
Hybrid search. Semantic (pgvector) plus typed filter — "every component that depends on auth-service" is one query, not a prompt engineering exercise.
·STATUS
v0.1.0-alpha.0 — M1 skeleton in progress. AGPL-3.0. The
GitHub repo
is the source of truth for what's wired today.
The recommended path is Docker — the image
ships with the TS service, runs the migrations on first boot,
and writes the bearer token to a mounted volume so it
survives restarts. Three embedding routes (Kvendra Cloud /
Ollama / mock); the Claude Code wiring is identical on all
three.
·01Pick an embeddings route·CHOOSE ONE · ENV-VAR-SWITCHABLE
EMBEDDINGS_PROVIDER selects the vectoriser the
KB uses. Same schema, same MCP surface — only ranking
quality of entity_search differs. The
-v $(pwd)/data:/data mount is what makes your
KB and the auth token persist across
restarts.
·01Create a free Kvendra account (200k tokens / month, no card required).SIGN UP →
·02Generate an embeddings API key from the dashboard.
·03Pull the image and run the container with the key injected.
Deterministic mock embedder — zero
network, zero signup, useless for real semantic ranking.
The right pick for CI pipelines, demos, smoke tests and
any structural work where ranking quality doesn't
matter.
·02Verify & grab the auth token·COMMON · ANY ROUTE
healthz confirms the migrations ran and the
MCP endpoint is listening. The bearer token lands on the
host at ./data/auth.token (file mode
0600) thanks to the volume mount — without
that mount, the token regenerates on every restart and
your Claude Code config breaks.
curl http://localhost:7777/healthz
cat ./data/auth.token
·03Wire it into Claude Code·COMMON · MCP OVER HTTP
The MCP transport is Streamable HTTP at
http://localhost:7777/mcp. Paste the token
from the previous step into your Claude Code config; the
same block works for Cursor and any MCP-aware client.
Switch embedding routes by editing the
-e EMBEDDINGS_PROVIDER=… env var — you don't
need to touch the client config.
·04Optional · build from source·AUDIT-FRIENDLY · BRING-YOUR-OWN-IMAGE
Prefer to clone the repo and build the image yourself — for
regulated environments, locked-down corporate networks, or
when you want to read the source before running it.
docker compose up -d in the repo brings
everything up (Postgres + pgvector + service) using the
embedding route you set in .env.
Pin to a release tag for reproducible builds —
git checkout v0.1.0-alpha.0 before
docker compose up. Edit
EMBEDDINGS_PROVIDER in .env to
switch routes without rebuilding the image.
·NOTE
Switching embedding routes after the KB has data
does not re-embed existing rows. For a
clean comparison, start a fresh volume
(rm -rf ./data && mkdir data) or
accept that older rows will still rank by the old
provider.
§ 03 — MCP TOOLS·14 TOOLS · 4 GROUPS
·CRUD
·entity_get
entity_get
Fetch a single entity by id. Returns the typed entity with its current revision and relations.
·entity_create
entity_create
Create a new entity inside an active transaction. Validates the payload against the entity schema before staging.
·entity_update
entity_update
Update an existing entity. The previous revision is preserved in the changelog — supersession is explicit, never silent.
·entity_archive
entity_archive
Archive an entity (soft delete). The row stays in the graph with status archived so historical relations resolve.
·entity_related
entity_related
List all entities related to a given one, with relation type and direction. The fastest way to traverse the typed graph.
Hybrid semantic + typed search: pgvector for similarity, the filter clause for precision. Same call surface, two ranking signals.
·TRANSACTION
·txn_create
txn_create
Open a new transaction. Every subsequent mutation (entity_create / entity_update / entity_archive) stages inside this transaction until commit or cancel.
·txn_activate
txn_activate
Commit a staged transaction — all changes become visible atomically, the changelog gets a single coherent revision.
·txn_cancel
txn_cancel
Discard a staged transaction. Nothing leaks into the active graph — the KB stays clean even when a skill aborts mid-pipeline.
·txn_check_interrupted
txn_check_interrupted
Detect transactions interrupted by a process crash or network drop. Lets skills resume cleanly without ghost data.
·UTILITIES
·whoami
whoami
Returns the authenticated identity, capability set and active workspace. The first call any well-behaved client makes.
In-protocol discovery: the canonical list of tool names, their JSON schemas and a short description per tool.
§ 04 — ENTITY TYPES·20 TYPES
Twenty typed entity kinds. Each has its own schema, its own
validation rules, its own relation set. The full catalogue:
PRJproject / workspace root
CMPcomponent / service
IFinterface / contract
REQrequirement
TESTtest definition
REGregression run
ISSUEincident / bug
RELrelease
SLAservice-level objective
ROADroadmap item
GLOglossary term
STDcoding standard
PATpattern / threat model
ADRarchitectural decision record
RUNrunbook
UXUX spec / journey
DOCmanual / doc entry
ENVenvironment / deployment target
COSTcost envelope
CFGconfiguration / feature flag
·NOTE
Each entity has a stable id and a versioned changelog.
Mutations land inside transactions, so every change is
grouped, traceable, and reversible. The skills surface
(/skills) is what wires Claude Code
to these types via /slash commands.
§ 05 — LICENSE & SCOPE·AGPL-3.0
The Platform is AGPL-3.0. You can run it
free forever, fork it, modify it. There's one clause you
should read before going to production:
·§13
If you offer a modified version of the
Platform as a network service to third parties,
AGPL-3.0 § 13 requires you to publish your modifications
under the same licence. Running an unmodified Platform
internally, or self-hosting for your own team, has no such
obligation. Read
LICENSE
if in doubt.
What this engine is — and isn't
The Platform is the
single-tenant KB engine. It runs your KB,
your workspace, your typed graph. It is not multi-tenant. It
is not the hosted Cloud product (that's the
Enterprise tier with shared
workspaces, SSO and managed infrastructure).
For most engineers, the right path is:
self-host the Platform for free, install
the CLI vault for secrets, install the
Skills plugin in Claude Code. The
whole stack works offline, costs nothing, ships under open
licences.
We use analytics cookies (Google Analytics, Google Ads) to measure
site usage and campaign conversions. They are loaded only after you
opt in.
Learn more.