Implements five of the six enhancements from docs/kb-enhancements-proposal.htm,
closing the retrieval-quality gap identified in the qmd review.
- Cross-encoder reranking: new kb/reranker.py loads an optional reranking
model at startup (KB_RERANK_ENABLED, KB_RERANKER_MODEL,
KB_RERANK_CANDIDATES). Search degrades gracefully to plain hybrid
retrieval when the model is absent. Exposed via a "rerank" block in
/status, a rerank flag on search, and --no-rerank in the CLI.
- RRF rank fusion: FTS and vector lists now merge by reciprocal rank
fusion with a top-rank bonus, replacing the old score blend. Scores are
comparable across queries.
- Bench harness and explain traces: kb bench runs a query fixture against
each backend and reports precision@k, recall and MRR. --explain returns a
per-result score breakdown.
- Tag context descriptions: tags carry an optional one-line description
(kb tag-describe), returned as tag_contexts with search results. Adds a
tags.description column migration.
- Structured data ingestion: .json/.yaml/.toml files ingest as text via the
new "data" doc type, pretty-printing minified JSON before chunking.
Query expansion (proposal item 5) is deliberately left out pending bench
results. Requires engine v3.3.0.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Agents were misreading kb_search as keyword-only because the vector/semantic
component was only mentioned in the negative ("fts_only: no vector similarity").
Lead with hybrid semantic + BM25 + RRF in the server instructions, kb_search
docstring, and MCP.md so agents recognise it as a vector search tool.
The MCP SDK's DNS rebinding protection rejects remote clients with 421
when the Host header isn't in the allowlist. Add KB_MCP_ALLOWED_HOSTS env
var (comma-separated IPs/FQDNs) to configure additional allowed hosts
while keeping localhost always permitted.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- kb_status now returns authenticated: true/false so clients can verify auth
- Server instructions mention Bearer token auth requirement
- Add .env, .venv/, test_mcp_client.py to .gitignore
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New MCP server (mcp/) exposes kb operations as native MCP tools over
Streamable HTTP with Bearer token auth. Supports collections via tag
conventions, chunked file uploads, and agent-side search patterns.
Engine gains PATCH /api/v1/notes/{id} for in-place note updates with
transactional re-chunk/re-embed, and updated_at column on documents.
Go client adds updatenote command and Patch HTTP method.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
steve