QMD Retrieval

Veritas Kanban v4.1 adds QMD-backed retrieval for task/docs search, duplicate detection, and VERITAS chat context. QMD is optional; if it is unavailable, VK falls back to built-in keyword search across markdown files.

Collections

Retrieval searches these collections:

tasks-active — tasks/active/**/*.md
tasks-archive — tasks/archive/**/*.md
docs — docs/**/*.{md,mdx,txt}

Raw telemetry is intentionally excluded.

Backends

Backend	Behavior
`keyword`	Built-in filename/content matching; no external binary
`qmd`	Runs `qmd query --json` and falls back on failure
`auto`	Attempts QMD first, then keyword fallback

Default backend is keyword. Enable QMD globally with:

VERITAS_SEARCH_BACKEND=qmd

Setup

Install QMD and create the initial collections:

npm install -g @tobilu/qmd
pnpm qmd:setup

Then start VK with QMD enabled:

VERITAS_SEARCH_BACKEND=qmd pnpm dev

Refresh the index after larger task/doc changes:

pnpm qmd:refresh

Set VERITAS_QMD_SKIP_EMBED=true to run qmd update without qmd embed.

API

curl -X POST http://localhost:3001/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "semantic search duplicate detection",
    "limit": 10,
    "backend": "auto",
    "collections": ["tasks-active", "tasks-archive", "docs"]
  }'

The response includes backend, degraded, and optional reason fields so clients can show whether QMD or fallback search served the request.

App UI

Open the search dialog from the header search icon or the command palette action named Search Tasks and Docs. The dialog can query active tasks, archived tasks, and docs, and it shows whether the response came from QMD or keyword fallback.

Task results open directly in the board detail panel when the result path maps to a task markdown file.

Duplicate Detection

The create-task dialog checks active and archived task collections after the title has enough signal. Possible matches are shown inline and can be opened for inspection, but task creation remains available so intentional follow-up work is not blocked.

VERITAS Context Injection

VERITAS chat sends retrieve compact supporting context from active tasks, archived tasks, and docs before calling the gateway. The original user message is still saved unchanged; retrieved context is appended only to the gateway prompt inside a <veritas_context> block with source paths.

Clients can opt out per chat send by passing includeContext: false.

Index Maintenance

The authenticated API exposes POST /api/search/index/refresh for operators and automation. Send { "embed": false } to update collections without recomputing embeddings.

Scheduling

Add deployment-specific schedules as needed with pnpm qmd:refresh or POST /api/search/index/refresh.

3 KiB Raw Permalink Blame History