Skip to main content

Knowledge Base Vision

The thesis behind this handbook, and how the same idea becomes a product feature and an internal tool. Grounded in two references George shared: graph engineering and Cerebras — How we built our knowledge base.

The core idea​

A knowledge base is three things: a place to collect data where it already lives, a place to query it, and a layer that enforces auth + audit. The hard-won lessons from Cerebras that apply directly to us:

  1. Meet data where it lives. Don't force everything into one system. Ingest from Slack, GitHub, Firestore, docs — each stays ergonomic in its own tool; connectors pull into one query surface.
  2. Hybrid retrieval beats pure vector. Full-text (exact tokens: analyte names, drug names, error strings) + embeddings (paraphrase) + IDF (rare-token signal) + age decay (a protocol from six months ago may be superseded), fused with reciprocal rank fusion, then reranked.
  3. Distill before you embed. Turn a long thread into a structured question/summary/resolution — accuracy jumps versus embedding raw transcript.
  4. Planner → parallel fan-out → synthesis. Decide which sources matter, query them concurrently, normalize to one evidence schema, synthesize with citations.
  5. Retrieval primitives as tools (MCP). The agent orchestrates; the retrieval layer stays LLM-free and fast.

This is the same shape as graph engineering — router → tiered models → parallel fan-out → synthesis with a verification gate. We already do the orchestration spine well; the honest gaps are parallelism and adversarial verification (tracked as #574 and #575).

How it maps to our three surfaces​

1. Per-clinic knowledge base — a product feature​

A per-clinic KB already exists — this is an upgrade, not a greenfield build. Verified in code (2026-07-22):

  • Storage: clinicsv2/{clinicId}/settings/copilot → a knowledgeBase[] array, plus auto-synced entries (kbAuto from clinic config — services, products, memberships, locations; kbAutoStaff from clinicians) and uploaded documents (PDF/Word/Excel/ TXT/CSV, text-extracted). functions_kb_sync.py, functions_rag.py, functions_ai.py.
  • Clinic-facing UI: full CRUD in Copilot Settings (basisflow-web settings page) — add/edit/delete, upload + auto-tag.
  • Multi-tenant scoping: clinicId is in every path; no cross-clinic access. The PHI isolation I earlier called "the gate" is already solved for the KB.

The real gap is narrower and more concrete: the KB search endpoint (kb_search) is keyword-only — token overlap + a title bonus, returns top-2. Meanwhile the patient RAG path already does real vector search (Firestore find_nearest, cosine, a deployed vector index) over Vertex text-embedding-004 chunks. So the embedding + chunking + vector-index infrastructure exists and is proven — it just isn't wired to KB search.

The upgrade, precisely

Not "build graph-RAG." It's: (1) wire kb_search to the existing vector index (semantic, not just keyword), (2) fuse keyword + vector with reciprocal rank fusion so exact clinical tokens (analyte/drug names) and paraphrase both rank, (3) rerank by clinical relevance, (4) filter by the entry's appliesTo metadata, (5) recency-weight so a superseded protocol loses to the current one. Small, grounded, and it reuses infra that's already deployed.

2. Internal "ask anything" — a tool to operate + grow​

An internal KB over Slack + GitHub (we have Sourcebot) + Firestore + our own docs/claude/ corpus + agent-fleet outputs (Sentry, watchdogs, market-intel). "Where's X / who owns Y / what did we decide about Z." We already run Pinecone. Cerebras's "custom sources as plugin scripts writing one embeddings table" maps to our connectors; the planner→fan-out→synthesis is #574. This is also where third-party intel (#573 — GCP/Stedi changelogs, competitor newsletters) lands as a source.

3. This handbook — the human view of the same corpus​

The deepest insight: the docs site and the KB share one corpus, two consumption modes. Humans read the handbook; agents and humans query the KB. Building great markdown docs is therefore not separate from the KB — the docs folder is the seed corpus and the first connector (exactly how Cerebras ingests its own wiki). The sync-handbook.mjs script that surfaces docs/claude/ here is, literally, connector #1.

Status — real vs. aspirational​

PieceState
Handbook (human view over repo corpus)✅ this site
Per-clinic KB: storage + auto-sync + doc ingest + clinic UI✅ live (settings/copilot)
Per-clinic KB: multi-tenant / PHI isolation✅ done (clinicId in every path)
Vector search on patient data (chunk + embed + Firestore find_nearest)✅ live
Vector search on the KB itself⚠️ not wired — KB search is keyword-only (top-2)
Hybrid retrieval (keyword + vector fused via RRF + rerank + recency + metadata filter)⚠️ not built — the real upgrade
Parallel LLM fan-out⚠️ #574 (partial: ThreadPool is I/O-only today)
Adversarial verification gate⚠️ #575
Third-party intel source⚠️ #573

Nothing above is marked done that isn't. The next real step for the per-clinic KB is wiring kb_search to the existing vector index and adding the hybrid layer — reusing infrastructure that is already deployed. PHI isolation is not a blocker here; it's already solved.