kvendra
·MENU

·SECTION 03 — PLATFORM · THE CORE

Platform.

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.

git clone https://github.com/KvendraAI/kvendra-platform.git

cd kvendra-platform && docker compose up -d

VIEW ON GITHUB
§ 01 — WHY THE PLATFORM ·STRUCTURE, NOT MEMORY

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:

  1. 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.
  2. 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.
  3. 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.
§ 02 — INSTALL ·DOCKER · EMBEDDINGS ROUTES · MCP WIRING

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.

·REQUIRES docker · install Docker →
·01 Pick 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.

  1. ·01 Create a free Kvendra account (200k tokens / month, no card required). SIGN UP
  2. ·02 Generate an embeddings API key from the dashboard.
  3. ·03 Pull the image and run the container with the key injected.
export KVENDRA_EMBEDDINGS_API_KEY=sk_kv_…

docker pull kvendra/kvendra-platform:latest

docker run -d -p 7777:7777 --name kvendra \
  -e EMBEDDINGS_PROVIDER=kvendra \
  -e KVENDRA_EMBEDDINGS_API_KEY \
  -v $(pwd)/data:/data \
  kvendra/kvendra-platform

Run a local embedding model with Ollama. Heavier on local hardware — everything stays on your machine, no signup, no API key.

ollama pull nomic-embed-text

docker pull kvendra/kvendra-platform:latest

docker run -d -p 7777:7777 --name kvendra \
  -e EMBEDDINGS_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -e OLLAMA_MODEL=nomic-embed-text \
  -v $(pwd)/data:/data \
  kvendra/kvendra-platform

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.

docker pull kvendra/kvendra-platform:latest

docker run -d -p 7777:7777 --name kvendra \
  -e EMBEDDINGS_PROVIDER=mock \
  -v $(pwd)/data:/data \
  kvendra/kvendra-platform

·02 Verify & 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

·03 Wire 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.

{
  "mcpServers": {
    "kvendra": {
      "type": "http",
      "url": "http://localhost:7777/mcp",
      "headers": { "Authorization": "Bearer <token-from-step-02>" }
    }
  }
}
·04 Optional · 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.

git clone https://github.com/KvendraAI/kvendra-platform.git

cd kvendra-platform && cp .env.example .env

docker compose up -d --build

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.

·entity_query

entity_query

Typed-filter query — entity type, status, owner, tag, related-to, time window. Boolean composition. Returns ranked entities.

·entity_search

entity_search

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.

·config_get

config_get

Read non-secret platform configuration — embedding provider in use, schema version, feature flags.

·help

help

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.