Talent KB

Proof of concept for evidence-based talent retrieval

Architecture

The system is intentionally simple in structure and opinionated in workflow shape.

Talent KB uses a local-first ingestion pipeline, a structured SQLite corpus, hybrid retrieval, and two consumption surfaces: REST for engineering integration and MCP for LLM-native clients.

Query execution

The technically interesting part is the retrieval path.

Talent KB is not impressive because it stores records. It is useful because it turns scoped questions into bounded retrieval workflows that stay grounded in exact evidence.

Technical retrieval sequence diagram showing scoped query execution, exact-text search, embedding search, ranking merge, digest shaping, and optional drill-down.

Search strategy

Hybrid retrieval is there to reduce blind spots, not to add novelty.

Talent KB already uses two search paths. The first is exact-match search over indexed segments in SQLite, which is strong for names, review phrasing, question text, and quoted wording from notes. The second is embedding-based search in Chroma, which is stronger when the user describes the idea differently than the original note or review text.

This is important because management questions are often paraphrased. A note may say “waiting on another team” while the user asks for “coordination friction.” Talent KB runs both search paths and then merges the ranked results, which improves recall without losing the precision of exact text matches.

Why hybrid

Exact wording and conceptual similarity solve different problems.

  • Exact-match search is strong for names, titles, review phrases, and quoted language but weaker when the user paraphrases a concept.
  • Embeddings are better at meaning-level similarity but less predictable for exact phrasing, filters, and auditability.
  • The hybrid path gives better recall without giving up precision, which matters when management questions can be both fuzzy and high-stakes.
  • Talent KB combines lexical and semantic retrieval so it does not have to choose between exactness and conceptual recall.

Exact-match search path

SQLite FTS5 handles exact language, names, ratings vocabulary, and query terms that should match the original source wording closely.

Meaning-based search path

Sentence-transformer embeddings are stored in Chroma so conceptually similar queries can still match the right notes even when wording differs.

Merged ranking

The two ranked lists are merged, then adjusted with light document-type weighting so reviews and 1:1s can rank more appropriately for talent questions.

Metadata gating

Manager scope, person identity, review cycle, relationship type, date windows, and reporting-chain filters are applied before or alongside ranking so retrieval stays bounded.

System map

How the pieces fit together operationally

Architecture diagram showing Paycor ingestion, normalization, indexing, API, MCP, and clients.

Data model

What gets stored after capture

The knowledge base keeps multiple layers of structure so review coverage, person scope, answer-level detail, and search can be reasoned about independently.

Entity Purpose Why it exists
people Directory and scoped reporting-chain context Stores person identity, title, current inferred manager context, and reporting-chain scope markers.
review_cycles Cycle-aware review semantics Holds cycle names, types, dates, and metadata so review coverage can be measured against the actual review cohort.
documents Primary unit of retrieved evidence One row per review, 1:1, or recognition item with shared metadata such as dates, people, URLs, cycle, and raw text.
review_answers Question-level review detail Stores responder identity, question text, answer text, and rating selections for annual and mid-year reviews.
document_segments Search and embedding units Breaks documents into bounded retrieval chunks so search and digests can stay precise and compact.
raw_records / ingest_runs Traceability and rerun safety Keeps payload lineage, capture metadata, and ingest accounting available for audits and debugging.

MCP in plain language

Why MCP matters more than another custom client integration

MCP is a standard way for LLM clients to discover and call tools. Instead of writing one custom integration per client, Talent KB exposes a protected MCP server that describes its workflows and reference resources in a way MCP-capable tools can understand directly.

That matters because a normal-language question like “summarize annual review themes under this manager” can be mapped to the right bounded workflow automatically, rather than forcing the user to know internal API shapes.

Endpoint types

How the application is exposed

Transport + discovery

  • `/mcp` for tool transport
  • `/authorize`, `/token`, and `/.well-known/*` for OAuth and discovery
  • Used by MCP-capable clients such as Claude, Codex, and other supported desktop or hosted tools

Tools

  • Workflow-oriented functions like team digests, person digests, review digests, recognition digests, and coverage summaries
  • Designed to return bounded, structured payloads rather than giant raw note dumps
  • Best path for plain-English manager questions

Resources

  • Stable reference material such as coverage, people, cycles, and document types
  • Useful when a client wants context before choosing tools
  • Read-only by design

REST API

  • Protected `/api/*` endpoints mirror the major workflows for engineering integrations
  • More conventional for direct application development and scripted calls
  • Coexists with MCP because engineering systems and LLM clients want different integration styles
MCP flow diagram showing an LLM client discovering tools and calling Talent KB workflows.

How an LLM consumes it

Coarse to fine instead of raw note dumping

  1. Connect to the authenticated MCP server.
  2. Discover tools and resources that describe what the knowledge base can do.
  3. Choose a bounded workflow such as a team digest or review digest instead of brute-force searching everything.
  4. Drill into documents only when the answer needs exact evidence or more nuance.
  5. Return a summary grounded in retrieved notes, reviews, and recognition rather than unsupported opinion.

Technology choices

The stack stays deliberately small and inspectable

Layer Choice Why this was chosen How it is used here
Capture Playwright + authenticated request replay Reliable for login/session handling and better than brittle DOM scraping when internal APIs are available. Used to capture review, one-on-one, and recognition payloads from Paycor Talent Development / 7Geese.
System of record SQLite Simple, durable, fast enough for the proof-of-concept scale, and easy to back up and inspect. Stores normalized people, cycles, documents, review answers, segments, raw records, and ingest runs.
Lexical search SQLite FTS5 Strong for exact terms, names, review phrases, and constrained metadata-aware retrieval. Indexes document segments for exact-text retrieval and complements vector retrieval.
Semantic search Chroma + sentence-transformers Useful when users ask conceptually similar questions that do not match the original wording in a note or review. Embeds document segments and merges vector results with BM25 results.
Application services FastAPI Fast to build, clear request models, and a good fit for protected JSON endpoints and lightweight server-rendered pages. Hosts the public briefing site, `/health`, and the protected `/api/*` surface.
LLM integration FastMCP with OAuth Allows modern LLM clients to discover tools and resources instead of forcing bespoke client integration. Exposes digests, search, coverage, and drill-down workflows over MCP at `/mcp`.
Deployment nginx + systemd Straightforward, durable Linux operating model with clear separation between public proxying and local services. Routes traffic for the public site, API, MCP transport, and OAuth discovery endpoints.