Trove / Guides
Retrieval levels
How trove query ranks memory objects, walks from the architecture summary down to symbols, splits its token budget into slices, and decides when to stop.
On this page
trove query assembles context from the index top-down. It starts with the most compressed, repository-wide view and adds more specific layers until a budget slice is used up.
trove query "modify vendor onboarding" --budget 200000
First principles
An agent about to change code needs orientation before detail: which part of the system this is, which files are involved, which functions. Detail without orientation is expensive to read and easy to misplace. And the cheapest orientation, one architecture summary, costs a few hundred tokens, while the source of one large file can cost thousands.
So query reads the layers in order of cost: architecture first, then subsystems, modules and symbols. Each layer gets a fixed share of the budget and stops when its share is used, so a small budget still returns a complete top-down picture instead of the first few files in full. Unused budget is fine; it is context the agent did not have to spend.
Use trove query for orientation before a change. Use trove ask to find the single best source for a question: it ranks across every source kind and puts the best match first, while query always returns its layers in order.
Query terms
The query is split on every character that is not a letter or digit. Terms of two characters or fewer are dropped, and the rest are lowercased. A query such as "ab" has no terms, so nothing scores above zero, but the pipeline still returns the architecture summary and the top subsystems and modules in stored order.
Scoring
Architecture, subsystem, module and historical objects are ranked by a keyword score:
- +3 for each term found in the object id, path, summary or raw text (each field counts separately).
- +2 for each of the object’s keywords that contains the term.
Symbols are filtered, not ranked: a symbol is kept when its name or path contains at least one term, and the first 20 matches in index order are used.
Token cost is estimated as the text length in bytes divided by 4, plus 1.
The budget
--budget sets the total token budget, 200,000 by default. It is split into slices:
- Working memory: 10%
- Architecture: 15%
- Active files: 20%
- Dependency expansion: 20%
- Code: 20%
- Tool output: 15%
The working memory and tool output slices are computed but not used by the current pipeline.
The order of retrieval
- L4 Architecture. The best-scoring architecture object, at summary tier. If the summary is larger than the architecture slice, the ultra summary is used instead.
- L3 Subsystems. Up to 3 subsystems by score, at summary tier. Stops when the running total would pass the architecture slice plus half the active files slice.
- L2 Modules. Up to 8 modules by score, at summary tier. Stops when the running total would pass the architecture slice, the active files slice and half the active files slice combined.
- L1 Symbols. Up to 20 matching symbols. The content is the signature, or
kind namewhen there is no signature. Symbol costs are counted against the code slice. - Dependency expansion. Starting from the retrieved modules, the pipeline walks one hop in the dependency graph and adds up to 10 neighboring symbols at ultra summary tier, within the dependency expansion slice.
- L5 Historical. Up to 3 imported trove entries by score, at summary tier. Only present after
trove import-historical.
The subsystem, module and historical steps also stop when the running total reaches the total budget. The stopped early flag in the output is true when any step stopped because of a budget limit.
In the current code, step 5 does not add items: module ids (module:<path>) are not graph node ids (which are file paths and symbol ids), so the walk finds no neighbors.
Because the output is ordered by level, imported trove entries always come last. In the repository’s retrieval evaluation they land at ranks 12 to 15 of the assembled items. To find a trove entry first, use trove ask.
Reading the output
Text output, per item:
## L2 Module Memory [summary] module:crates/trove-retrieve/src/budget.rs
- Package area: crates - 1 class(s) - 1 struct(s) - 2 function(s) - ...
_confidence: derived from symbol index | path: indexer -> crates/trove-retrieve/src/budget.rs_
- The heading has the level label, the compression tier and the object id.
- The last line has the confidence reason and the retrieval path.
The confidence reasons you will see are:
synthesized from indexfor the architecture object.clustered by top-level package directoryfor subsystems.derived from symbol indexfor modules.symbol name/path matchfor symbols.imported from Claude trove entriesfor historical entries.
With --json, the same data comes back as one JavaScript Object Notation (JSON) object:
{
"query": "graph expand neighbors",
"estimated_tokens": 901,
"stopped_early": false,
"items": [
{
"level": "l4_architecture",
"object_id": "architecture:root",
"tier": "summary",
"content": "Trove-indexed repository with 1372 symbols across 3 subsystems. ...",
"confidence_reason": "synthesized from index",
"retrieval_path": ["indexer", "architecture"]
}
]
}
level is one of l1_active_symbols, l2_module, l3_subsystem, l4_architecture or l5_historical. tier is summary or ultra_summary.
Using it well
The plugin’s query skill describes the intended use: read the layers in order, stop expanding once you have enough detail, and open full source files only when the summaries are not enough. Prefer higher-layer items first.