Search

Route to the most relevant ATOMS in the trusted knowledge base (David's saved opinions + tracked artifacts). This is a ROUTER, not an answer: each hit is a thin card — matched-chunk snippet + a pointer (source_url / raw_ref / atom_id) + ranks — NOT a statement of what the source says. To assert what a source actually claims, call open(atom_id) and read its raw text. That split is the whole trust model.

RETURNS {hits, notices, insights, trace, frontier_atoms} — and the non-hit keys are read DIFFERENT ways: • notices — finished sentences about what your QUERY did (a filter that matched nothing, a handle that resolved to nobody or to two people, results truncated). Surface these to the user when the list is non-empty; they are written to be repeated as-is. [] on a healthy query, which is the normal case. • insights — VALUES about the evidence: authors/sources/topics counts, date_span, body_state, saved_vs_crawled, corpus_newest, filter_cost (what each filter cost you), and resolved_who when you passed who=. These describe hits ONLY. On a default call saved_vs_crawled therefore lists no crawled atoms — they are in frontier_atoms, not missing. • trace — VALUES about what the ENGINE did: ran (which arms actually ran), score_scale (the units score is in), candidates/ranked/showing, cutoff, fts_query, filters as applied. • frontier_atoms — a SECOND, separately ranked list: atoms found by the user's standing keyword queries rather than saved or written by anyone they follow. Present only on a default call (see entry_mode). Same card shape as hits, capped at 8 and floored at a fraction of its own top score, with floor.dropped saying how many the floor removed. Offer it as "and from the frontier crawl…", never merged into hits: its scores are ranked against other frontier atoms and mean nothing next to theirs.

frontier_atoms is NOT the frontier key you may also see here. That one is the Frontier QUEUE's push notice — staged candidates not yet in the KB — and it appears at most once a session. These are atoms already in the KB that matched THIS query.

insights and trace are for your reasoning — do not recite them to the user. They are bare values on purpose. Use them to decide what to do next (open something, re-query, drop a filter, warn about a lopsided result); say the CONCLUSION in your own words, never the fields. Only notices is written to be read out.

score is not comparable across calls unless trace.score_scale matches. It is a raw cosine under semantic (and under a hybrid run that dropped its keyword arm), a reciprocal rank under bm25, and a fused rank sum under a true hybrid run. 0.03 in one scale can outrank 0.7 in another. A known bias rides the cosine: a longer document max-pools higher for having more chunks to draw from, so weigh a long hit's lead over a short one as smaller than it looks.

Retrieval: an optional tag/kind/source/author pre-filter, then a BM25 arm and a semantic arm, fused by rank. Ranking is pure relevance — there is no trust re-rank. mode="hybrid" often runs only the semantic arm: a conceptual query with no literal token (most natural-language questions over three words) gives BM25 a weight of 0 and the keyword arm is skipped. trace.ran says which arms really ran; do not assume both.

Read body_state before quoting a snippet. It says how much of the source we actually stored: "complete" (the whole body), "partial" (knowingly short of it — a paywall teaser, a truncated feed entry), "absent" (no body, the card is all there is), or "pending" (not yet determined). On "partial" or "absent", do not present the text as the full thing — say what you have, and follow source_url for the rest. body_basis says how that was decided: "observed" (we saw the boundary), "stated" (the source declared it), "assumed".

Read when_precision before reporting a date, especially under date_from/date_to. when_ts always LOOKS like a day, and for two values it is not one: • "year" — only the YEAR is known (common for papers); when_ts is that Jan 1 as a FLOOR, not a real day. Such a hit is included whenever its year OVERLAPS your window, deliberately — a wrongly-included atom you can see and discard, a wrongly excluded one you cannot. Caveat it to the user ("published sometime in 2025"), never as a confirmed date match. • "push" — GitHub's LAST-PUSH date, NOT a publication date. A repo matching "after May" was ACTIVE then and may have been created years earlier. A different KIND of date, not a coarser one, and the easiest thing here to misreport. Atoms with NO recorded date are excluded by either bound, and a notice says how many.

Each hit also carries payload — whatever extras that atom's SOURCE had, returned verbatim. It is NOT a fixed schema and it is NOT filterable: GitHub atoms carry stars/code_language, X atoms like_count/is_thread, papers citationCount/venue. Read the keys that are there; never assume a key exists because another hit had it.