03 // HOW SO SMART?
Vagus makes local evidence easy to retrieve. BM25 remembers the words, vectors remember the meaning, and a state-of-the-art agent harness reads the evidence and finishes the job.
ONE QUERY // TWO INSTINCTS
“why did Firefox stall on the first request?”send down both channels ↓
Tokenize the query, reward rare matching terms, account for repetition and document length, then rank chunks containing the literal vocabulary.
firefox · stall · first · requestIDF(firefox) > IDF(request)error codes win hereBEST AT filenames, commands, ticket IDs, error strings, product names, and wording you can quote.
Turn the query into 768 local numbers, compare its direction with indexed chunk vectors, then rank passages whose meaning points the same way.
task: search result | query:text → [0.03, −0.11, …] × 768gist survives paraphraseBEST AT concepts, paraphrases, descriptions, and the memory you can explain but cannot quote.
RECIPROCAL RANK FUSION // k = 60
BM25 scores and cosine values live on unrelated scales. RRF ignores those raw magnitudes and adds rank evidence instead. A chunk can survive by dominating either channel; agreement lifts it higher.
RRF(d) = Σ 1 / (60 + rankchannel(d))
| candidate chunk | BM25 | vector | fused signal |
|---|---|---|---|
| cold-load diagnosis | #4 | #1 | both agree |
| literal Firefox error | #1 | #12 | exact survives |
| generic browser advice | #9 | #5 | falls behind |
Illustration only—the real lists are chunk IDs, deeper than these three rows, and deterministic ties use a stable ID.
Below 10,000 embedded chunks, semantic search uses exact cosine automatically; larger vaults use the local usearch HNSW sidecar. --exact remains the ground-truth escape hatch. The optional reranker can improve precision, but it is measured rather than presumed better.
INDEX TIME // PAY ON CHANGE
MEASURED CHANGED-NOTE PATH
A synthetic five-section note was filed five times in an isolated vault on an M1 Pro with model files cached. The median instrumented run took 1.878 s.
The exact shape depends on note length, model cache, hardware, and index size. These bars explain the work; they are not a universal speed promise.
*Residual is honest subtraction, not a separately instrumented phase. It includes embedder initialization and local-store orchestration. Phase medians need not sum exactly to the median total.
SEARCH TIME // 5,022 CHUNKS
The query embedder dominates a one-shot CLI process. BM25 and rank fusion are tiny by comparison.
Reranking roughly doubles this query. Wider adjacent context costs more, so it stays explicit.
Vagus v0.13.0 · Apple M1 Pro · 566 notes / 5,022 chunks · median of five separate invocations · model files present locally; no network · fixed non-private query · --no-index. Exact cosine is automatic at this corpus size. The timer covers the retrieval core, not agent reasoning or shell startup.
Normal search first performs an incremental mtime refresh. When nothing changed, it does not load the document embedder. open timing record ↗
Issue, task, meeting, or investigation enters the harness with live project context.
Hybrid retrieval returns exact + semantic candidates and their full bodies.
The harness rejects weak or redundant hits and cites the evidence it actually used.
The harness edits code, answers the ticket, and captures the durable outcome as Markdown.
Similar notes and existing PARA folders become candidate destinations—not commands.
Ticket context and Vagus recommendations meet; your approval policy controls the move.
THE TANDEM
The harness knows what just happened in the repository. Vagus knows which local notes and PARA neighborhoods resemble the result. Let the harness file away completed ticket knowledge in tandem with Vagus location recommendations instead of asking either side to guess alone.
RECOMMENDATION ≠ AUTHORITY // KEEP HUMAN APPROVAL OR SET YOUR OWN EXPLICIT POLICY
# 1. retrieve evidence for the active ticket
$ vagus search "$ticket" \
--json --full --rerank --exact
# 2. create-note skill pipes the outcome to 00-Inbox
$ note=$(vagus add-note "$title" --source "$ticket" \
--print-path <<'NOTE'
<durable ticket outcome>
NOTE
)
# 3. ask the vault topology; harness evaluates
$ vagus file "$note" --suggest --json
→ ["10-Projects/…", "30-Resources/…"]
# 4. after the configured approval gate
$ vagus file "$note" --to "$destination"vagus skills installvagus skills install --agent pivagus … --jsonWant the corpus numbers behind the claims?
04 // inspect field data →