Skip to content
Trove

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
  1. First principles
  2. Query terms
  3. Scoring
  4. The budget
  5. The order of retrieval
  6. Reading the output
  7. Using it well

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

  1. 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.
  2. 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.
  3. 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.
  4. L1 Symbols. Up to 20 matching symbols. The content is the signature, or kind name when there is no signature. Symbol costs are counted against the code slice.
  5. 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.
  6. 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 index for the architecture object.
  • clustered by top-level package directory for subsystems.
  • derived from symbol index for modules.
  • symbol name/path match for symbols.
  • imported from Claude trove entries for 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.