MESA Core · v0.9.3
Adaptive query planning
This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.
Adaptive query planning#
This maintained decision records design rationale at v0.9.3. Current architecture and runtime contracts define implemented behavior; retired decisions remain historical context.
Read the maintained reference#
The source below includes status, rationale and consequences. Start with the decision index and architecture.
Source reference for this page
The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.
- Status: Accepted
- Baseline: MESA 0.7.1 at
9f27c82 - Extends: ADR 0013 and ADR 0014
- Supersedes: ADR 0014 only where it deferred retrieval planning outside 0.7.x
Context#
MemoryDAO.search_v4_memory is the canonical deterministic single-query
retrieval primitive. It applies the authorized scope to the vector, BM25,
assertion and graph lanes, fuses those lanes with RRF and materializes evidence
provenance. ContextBuilder calls that primitive once and then owns the only
model-visible evidence-packing and token-budget pass.
The legacy HybridRetriever has an optional multi-hop decomposition path.
That path splits a question into research subqueries and is not semantic query
reformulation, so its contract and behavior remain unchanged.
This decision advances only ADR 0014's previously deferred retrieval-planner
stage. It does not change that ADR's closure, release-gate or production
NO-GO requirements; the new mode remains disabled by default and requires
external A/B evidence before default enablement.
Decision#
Bounded adaptive retrieval will be a mesa_memory.retrieval module above the
storage layer. Its small interface accepts server-authored search scope
arguments, captures them once in the retrieval operation and returns one fused
candidate list plus bounded diagnostics.
The module always runs the normalized original query first. A pure trigger
requests planning only when the result is empty or none of the first three
candidates has at least two retrieval origins. Planning makes at most one call
through the existing BaseUniversalLLMAdapter interface and accepts at most
two validated semantic reformulations. Retrieved evidence is never included in
the planner prompt.
Every accepted reformulation is sent to the same
MemoryDAO.search_v4_memory method with the exact original scope arguments.
Query result lists are fused with the existing deterministic RRF function at
weights Q0=1.0, Q1=0.5 and Q2=0.5. Canonical assertion/evidence/candidate
identity deduplicates results, while query_origins records query ID and rank.
The existing inner lane provenance and scores are preserved; the outer score is
stored separately as query_fusion_score.
ContextBuilder gains an opt-in retrieval_mode of adaptive and accepts the
adaptive retriever by dependency injection. Its default remains single,
which follows the existing direct DAO call. Both modes feed exactly one final
candidate list into the unchanged packing implementation.
Runtime composition creates the planner with AdapterFactory only for an
adaptive context request. The V4 context endpoint, sync/async clients and
mesa_get_context propagate the optional mode. Session authorization continues
to derive tenant, agent and dataset scope on the server; planner output is only
query text and cannot alter scope.
Bounds and failure behavior#
- Default mode: one retrieval, zero planner calls.
- Adaptive mode: at most one planner call and two additional retrievals.
- Context packing: exactly one pass, with the existing 2048-token default.
- Invalid output, provider failure or zero valid expansions preserves Q0 and
returns a bounded diagnostic status.
- A failed optional expansion preserves Q0 and any successful expansion.
- A failed original retrieval keeps the existing core failure semantics.
Deliberate exclusions#
No recursive planning, question decomposition, planner cache, answer
generation, reranker, learned confidence, dynamic weights, new provider
abstraction, persistent schema or retrieval-lane change is introduced.
