Skip to content
DimpleDimple

Retrieval

The pipeline

Section titled “The pipeline”
  query text
     │
     ▼
  embed ───────────────────────────┐
     │                             │
     ▼                             ▼
  tree descent (beam)        FTS5 lexical
  score only reached         exact names/ids
  leaves (bounded by         (whole content index)
  depth × maxLeafItems)           │
     │                             │
     └─────────────┬───────────────┘
                   ▼
          RRF fusion (k = 60)
                   │
                   ▼
        recency boost (optional)
                   │
                   ▼
     graph augmentation
     supersededBy · conflicts · supportedBy
                   │
                   ▼
  scoping: namespace · topics · concepts · contentType
                   │
                   ▼
  budgets: maxUnits / maxChars / maxMs ──▶ truncated?
                   │
                   ▼
        ranked results + one audit row

Tree descent

Section titled “Tree descent”

Algorithm — beam descent (the vector leg):

resolve_topics(query_vector):
  frontier = [__root__]
  for depth in 0..maxDepth:
    candidates = []
    for topic in frontier:
      candidates += score_children(query_vector, topic.children)
    frontier = top_k(candidates, beamWidth, tie-break by topic_key)
    if all frontier are leaves: break
  return frontier     → score ONLY these leaves' members

Scoring is bounded by depth + maxLeafItems per reached leaf — not by total memory count. The FTS5 leg runs in parallel and catches exact names/identifiers the vector leg might miss.

Hybrid fusion

Section titled “Hybrid fusion”

Algorithm — Reciprocal Rank Fusion:

for each leg, rank its hits:
  rrf_score(memory) = Σ_legs 1 / (k + rank_leg(memory))    k = 60 (default)


final score = rrf_score × (1 + recencyBoost × recencyFactor)
recencyFactor = 1 / (1 + ageDays)     (hyperbolic decay)

Then re-rank (stable — equal scores keep fused order) and attach graph context per result (supersededBy, conflicts, supportedBy).

Profile modes — "keyword" maps to pure-FTS ({vector: 0, fts: 1}), "semantic" to pure-vector ({vector: 1, fts: 0}), "hybrid" to the default fusion. The audited mode reflects the actual legs.

Scoping & sovereignty

Section titled “Scoping & sovereignty”
Scope Mechanism Use case
namespace filter on both legs code-vs-message partition
topics.topicKeys membership subquery on both legs “only from the deploy topic”
contentType (string or kinds[]) content_type IN (...) on both legs code vs plain text within one namespace
profile.conceptFilter concept annotation filter (vector leg) query sovereignty over clusters
budget: { maxUnits, maxChars, maxMs } post-fusion caps + truncation LLM context guardrail — results.truncated

Audit

Section titled “Audit”

Every query writes one fused retrieval_log row — the per-leg breakdown lives in query_profile (counts, top scores, weights, mode, filters), the contributing ids in sources. The query’s identity is a FNV-1a hash of the raw query (the vector mode hashes the full query vector so the hash is a true query identity, not a truncated prefix).

The row is written off the query path by the durable audit.write job — retrieval never blocks on audit, and a failure is visible (typed), never swallowed. “The answer to ‘why did the agent say this?’ is always reconstructible from logs.” Every query also emits a sync hybrid.search log line (INFO), empty-store queries included.