Why telemetry exists
A knowledge server that never learns what gets asked is guessing at relevance. Assembly treats agent usage as a first-class signal: queries become events, events become ranking input, and failed searches become a work list for the corpus.
The ingest service
telemetry-ingest is a small Go service that accepts usage events signed with HMAC (TELEMETRY_HMAC_SECRETS), so writers authenticate without ever touching the database directly. Query logging on the knowledge API side is toggled with QUERY_LOG_ENABLED.
What the data feeds
Usage-weighted ranking. Chunks that agents actually retrieve and use get a measured boost in future rankings — USAGE_BOOST, weight 0.002 by default, validated by eval numbers before it shipped. Details in Hybrid retrieval.
Miss analytics. GET /analytics/misses surfaces searches the corpus answered poorly. A recurring miss is a concrete instruction: document that pattern, add that story, tag those tokens. It turns “our agent seems confused” into a ranked to-do list.
Running it
Telemetry runs as a standalone service and has operated in production since July 2026. Deployment and operational guidance live in the repo: docs/TELEMETRY.md, docs/OBSERVABILITY.md, and docs/RUNBOOK.md.