Documentation menu
Getting Started

Quickstart

One path, in order, that ends in a first win: your agent planning real work in your project and later recalling the decision by meaning. We use the reference stack — the ready-made, everything-wired-together bundle — with local embeddings, so you get going with no signup and nothing leaving your machine. Everything below is copy-paste: one clone, two plugin commands, and a wizard that does the rest.

The recommended host is Claude Code, but anything that speaks the Model Context Protocol can drive Kvendra. Prefer to build it yourself, step by step — from source, or against your own Postgres? See Advanced install.

Prerequisites

You need Docker (Docker Desktop, or Colima on macOS; engine ≥ 20.10), Docker Compose v2, and git. Check them in one go: 

docker --version          # Docker version 20.10+ (Desktop or Colima)
docker compose version    # Docker Compose version v2.x  (note: "compose", not "docker-compose")
git --version
  • Docker runs the engine and its database in isolated containers, so you do not install Postgres or Node on your host — docker.com/get-started.
  • Ollama runs an embedding model locally so nothing leaves your machine — ollama.com. The reference stack runs it for you as a container, so there is nothing to install separately.

What you're spinning up

A quick look from above. The reference stack brings up these containers, wired together on an internal network:

  • PostgreSQL 16 + pgvector — your knowledge base. Entities and their embedding vectors live in the same database.
  • The Kvendra Platform engine — the MCP server your agent talks to, on :7777.
  • A backup sidecar — a tiny container that takes scheduled database dumps.
  • Ollama — the local embeddings runtime, started only when you pass --with-ollama.

Want the details of what's in the stack? see it on GitHub.

1. Get the stack

Clone the reference stack. That is the only thing the wizard cannot do for you — everything else (first boot, configuration, wiring) is automated in step 3: 

git clone https://github.com/KvendraAI/kvendra-reference-stack
cd kvendra-reference-stack

No config to edit: the first run creates .env from the example on its own, and local embeddings are wired automatically.

2. Install the Skills

Skills turn pipelines into one-command workflows. They install as a Claude Code plugin — and the plugin ships the /setup onboarding wizard that does the entire wiring in the next step: 

/plugin marketplace add KvendraAI/kvendra-skills
/plugin install kvendra-skills@kvendra-marketplace

3. Run /setup — the wizard does the rest

From the reference-stack directory, run the /setup skill and pick self-hosted: 

/setup self-hosted

The wizard takes it from here: it brings the stack up with local embeddings (Ollama running mxbai-embed-large — nothing leaves your machine), waits for the engine to report healthy, reads the bearer token out of the container, and registers the Platform as a distinct MCP server named kvendra-platform. The bundled cloud server is left untouched, and re-running /setup never duplicates a server — it detects what is already registered and offers to re-verify instead.

One step stays yours: activating a newly added MCP server needs a Claude Code restart (or /mcp reconnect kvendra-platform). The wizard tells you when — and after the restart it verifies the connection with a real read against your knowledge base, which hands your agent the 14 knowledge-base MCP tools. First boot takes 60–90 seconds while pgvector initialises and the engine runs its migrations; the embedding model is a one-time, lightweight download.

Re-check the wiring at any time with the /env-check skill — it diagnoses that the MCP is connected and reports the available tools and primitives.

Prefer to do every step yourself, by hand — bring-up, embeddings, reading the token, registering the MCP server? The whole manual path lives in Advanced install.

4. Onboard your project

You are connected — now give your agent the structure to work against. The natural next step is not generic: it is to onboard your own project into the knowledge base. The /onboard-project skill does exactly that (/setup offers this chain itself when it finishes): 

/onboard-project <PROJECT_ID>

It bootstraps the structure of your project in the KB — a project (PRJ) entity, its components, the shared glossary and standards (GLO/STD), and a canonical CLAUDE.md for the repo. It auto-detects that it is running against the local Platform you just brought up. It works for a brand-new project, and for a project that already exists you can map its pieces one at a time: 

/onboard-project add-component <name>

Precise scope: /onboard-project scaffolds the project structure and a canonical CLAUDE.md. It does not crawl or analyse all the code in an existing repo for you — you (or your agent, as you work) fill in the detail. The win is that the skeleton your agent reads on every session now exists.

5. Your first win

With your project onboarded, your agent has the structured context it needs. Now see what it is for — this is the payoff, not the healthcheck. In Claude Code, ask your agent to plan something small in your own project:

Plan a small change in this project: add a rate limit to the login endpoint. Open a transaction in Kvendra, draft a short roadmap and a couple of tasks for it, and link them.

Driven by the Skills, the agent opens a transaction, drafts a roadmap and the tasks as typed entities, links them, and commits — so the plan now lives in a queryable knowledge base, not in a chat that scrolls away. Here is an illustrative shape of what you would see: 

# illustrative — your ids and titles will differ
TXN-… opened
  ROAD-…   "Rate-limit the login endpoint"      (draft → active)
  ISSUE-…  "Add token-bucket limiter to /login" (draft → active)
  ISSUE-…  "Add tests for the limit"            (draft → active)
  relations: ISSUE-… part_of ROAD-…
TXN-… committed

Then, later in the session (or a new one), ask the question that proves the point:

What did we decide about login throttling, and why?

The agent finds the roadmap and tasks by meaning and answers from them — even though you asked about “throttling” and the entities say “rate limit.” That is the whole idea: it stops re-deciding, because the decision is recorded and findable. (Illustrative — exactly what surfaces depends on your project.)

6. (Optional, and deferred) Add the CLI security broker

You do NOT need the CLI to start. Add it later only when you want your agent to run real ops (a git push, a deploy) without exposing your tokens. It is a foundational security layer — but optional to get started, and everything above works without it.

The CLI is currently pre-alpha. It is not yet on crates.io (a Homebrew formula is pending), so install it from source when you are ready: 

cargo install --git https://github.com/KvendraAI/kvendra-cli kvendra

It runs an MCP stdio broker plus a zero-knowledge vault, exposing seven primitives — git, github, npm, pypi, http and shell, with an unsafe.raw_token escape hatch. Sensitive operations are routed through the broker so the model orchestrating the work never sees a raw token or key.

How the pieces fit

Your agent (Claude Code, the host) talks to the Platform over MCP HTTP on port 7777 — that is the knowledge base. The Skills plugin runs on top, calling the same Platform tools, and is your day-to-day. The optional CLI adds a second MCP server (stdio) that brokers credentialed operations. Start with the Platform and Skills; add the CLI only when you need it.

Want to go step by step instead — from source, or against your own Postgres? Advanced install has the one-by-one detail.