Latency Improvement

​

Tier 0: Exact Cache Hit (0ms)

​

Algorithm

1. Normalize query: lowercase, trim, collapse whitespace
2. Build cache key: normalized_query
3. Map.get(key) — O(1) lookup
4. Validate TTL: (now - storedAt) < 60s
5. Validate fingerprint: MD5 hash of sorted path:mtime pairs must match current context tree state
6. HIT — return cached response immediately

​

Context Tree Fingerprint

• Glob all .md files in .brv/context-tree/
• Sort by path, concat path:mtime joined by |, MD5 hash, take first 16 hex chars
• The fingerprint itself is cached for 30s to avoid repeated glob I/O
• If any file is added, removed, or modified, the fingerprint changes and all cache entries are invalidated

​

Parameters

​

Tier 1: Fuzzy Cache Match (~50ms)

​

Algorithm

1. Tokenize query: split on whitespace, remove stopwords, filter tokens shorter than 2 chars
2. Skip fuzzy matching if query has fewer than 2 meaningful tokens
3. For each cache entry:
   • Skip if fingerprint mismatch (cheap string compare)
   • Skip if TTL expired (cheap timestamp compare)
   • Compute Jaccard similarity: |A ∩ B| / |A ∪ B|
4. Return the highest-similarity match if similarity >= 0.6

​

Jaccard Similarity

Optimization: always iterate the smaller set, check membership in the larger set.
intersection = count of shared tokens
union = |A| + |B| - intersection
similarity = intersection / union

​

Parameters

​

Out-of-Domain Short-Circuit

• Returns: “This topic is not covered in the knowledge base.”
• The OOD response is cached to prevent repeated misses from hitting the LLM

​

Supplementary Entity Search

​

Algorithm

1. Split query into words, filter stopwords, keep words with length >= 3
2. Take top 3 entities
3. Run searches in parallel via Promise.allSettled()
4. Deduplicate results by path
5. Merge into original result set

​

Tier 2: Direct Search Response (~100-200ms)

​

Algorithm

1. Filter search results with score >= 0.7, take top 5
2. Read full document content from .brv/context-tree/ in parallel
3. Run canRespondDirectly() decision:
   • Gate 1: topResult.score >= 0.85 (minimum threshold). If not, fail.
   • Gate 2a: topResult.score >= 0.93 — score is so strong that dominance check is skipped. Pass.
   • Gate 2b: gap = topScore - secondScore >= 0.08 — clear separation between top and runner-up. Pass.
4. Format response: Summary + Details (max 5000 chars/doc, max 5 docs) + Sources + Gaps
5. Cache result and return

​

Why Gap-Based, Not Ratio-Based?

​

Parameters

​

Tier 3: Optimized Single LLM Call (<5s)

​

Algorithm

1. Filter results with score >= 0.7, build a pre-fetched context string (excerpts formatted as markdown sections)
2. Inject search data into sandbox as variables:
   • __query_results_{taskId} = search results array
   • __query_meta_{taskId} = {resultCount, topScore, hasPreFetched}
   • Build prompt with pre-fetched context embedded directly
3. Execute with tight LLM overrides: maxTokens=1024, temperature=0.3
4. LLM answers from the embedded context. If insufficient, it can use code_exec with silent: true to read additional documents from the sandbox variables
5. Cache result and return

​

Parameters

​

Tier 4: Full Agentic Loop (8-15s)

​

Algorithm

1. Same sandbox variable injection as Tier 3
2. Build prompt WITHOUT pre-fetched context — LLM must discover answers via tool use
3. Execute with relaxed LLM overrides: maxTokens=2048, temperature=0.5
4. LLM reads search results via code_exec, may call tools.readFile() to load documents, may loop through multiple tool calls
5. Protected by doom-loop detection (max iterations limit)
6. Cache result and return

​

Parameters

​

Knowledge Scoring

compoundScore = (W_RELEVANCE x BM25 + W_IMPORTANCE x importance/100 + W_RECENCY x recency) x tier_boost

​

Tier Boost Multipliers

​

Maturity Lifecycle (Hysteresis)

draft --(importance >= 65)--> validated --(importance >= 85)--> core
draft <--(importance < 35)-- validated <--(importance < 60)-- core

​

Decay Functions

• Importance decay: importance x 0.995^days (~78% remaining after 50 days of non-use)
• Recency decay: e^(-days/30) (half-life of ~21 days)

​

Complete Query Flow

User Query
    |
    |--- Fire parallel searches (local)
    |
    v
[Tier 0] Exact Cache Lookup
    |--- HIT --> Return (0ms)
    |
   MISS
    v
[Tier 1] Fuzzy Cache (Jaccard >= 0.6)
    |--- HIT --> Return (~50ms)
    |
   MISS
    v
[OOD] All searches returned 0 results?
    |--- YES --> "Not covered" response (0ms, cached)
    |
    NO
    v
[Entity Search] Initial results < 3?
    |--- YES --> Run supplementary entity searches (parallel)
    |
    v
[Tier 2] Direct Response (score >= 0.85 + dominant)
    |--- PASS --> Return formatted markdown (100-200ms)
    |
   NOT DOMINANT
    v
[Tier 3] Single LLM + Pre-fetched Context (score >= 0.7 exists)
    |--- PASS --> Return LLM response (<5s)
    |
   NO CONTEXT
    v
[Tier 4] Full Agentic Loop
    |--- Return LLM response (8-15s)