Trove / Guides
Indexing a repository
What trove index walks, which languages and symbol kinds it parses, how summaries are built without a model, and what it writes into the .trove/ folder.
On this page
trove index walks a repository, parses source files with tree-sitter, and writes four layers of memory plus a dependency graph into .trove/.
trove index
trove index --full
trove --repo /path/to/repo index
Run it from the repository root or pass --repo; it uses the current directory as the repository.
First principles
Reading source is the most expensive way for an agent to learn a codebase: a file costs tokens whether or not it turns out to matter. But most questions about a repository do not need the source. They need to know that a function exists, which file holds it, what the file exports and roughly how the folders are organized.
That information can be extracted once and stored in layers that shrink as they widen. A symbol is one line. A module summary is a few lines per file. A subsystem summary covers a folder. One architecture summary covers the whole repository. Retrieval can then start at the top, where the cost is small, and descend only where the task needs it.
The extraction uses fixed rules rather than a language model, so it runs offline, costs nothing and gives the same summaries for the same code. The price is depth: summaries list names and flags, not intent.
Which files are read
The walker uses the ignore crate with these rules:
.gitignore, the global Git ignore file and.git/info/excludeare respected when the folder is a Git repository.- Hidden files are included unless ignored. A project trove and its rendered skills under
.claude/are indexed like any other Markdown and show up as modules in query results. .trove/,target/and.git/at the repository root are always skipped.- Files that cannot be read as 8-bit Unicode Transformation Format (UTF-8) text are skipped.
Every file that passes becomes an L2 module, including Markdown, JavaScript Object Notation (JSON) and configuration files. Only files in a supported language also produce symbols.
Languages and symbols
The language is chosen by file extension.
- Rust (
.rs): functions, structs, enums, traits,implblocks (recorded asclass),moditems, andusedeclarations as imports. - Python (
.py): functions and classes, including decorated ones, andimportandfrom ... importstatements. - JavaScript (
.js,.jsx,.mjs,.cjs) and TypeScript (.ts,.tsx): function declarations, classes, methods,constarrow functions, andimportstatements. Both.tsand.tsxuse the TypeScript grammar. - Go (
.go): functions, methods, type declarations (recorded asstruct), and imports. - Bash (
.sh,.bash): functions and command invocations (recorded ascommand).
Each symbol records its path, start and end line, kind, a signature (the first line of the node, for functions, methods and structs), a content hash of the file, and a complexity estimate based on branch keywords and length. The symbol id has the form path:kind:name:line.
How the layers are built
- L1 Symbols. One object per symbol, in
.trove/symbols/, plus the full list in.trove/symbols.json. - L2 Modules. One summary per file, in
.trove/modules/. It lists the top-level folder, symbol counts by kind, exported functions, structs, classes, traits and enums, the file’s imports, and flags inferred from the text:unwrap()orexpect(, TODO or FIXME markers,unsafeblocks, filesystem access, database access and network access. These flags are simple substring checks. - L3 Subsystems. Files that have symbols are grouped by their first path segment, so
crates/trove-index/src/graph.rsbelongs to thecratessubsystem. Each subsystem lists its files and symbol counts by kind. - L4 Architecture. One
architecture:rootobject with the symbol count, subsystem count, graph size, and up to 12 subsystems ordered by symbol count. - Dependency graph.
.trove/graph.jsonhas a node per file and per symbol, and animportedge from each file to each import it declares. Relative imports are resolved against the file’s folder; others are kept as written.
No language model is involved. Every object’s text is compressed by rules:
- Summary: the first 12 non-empty lines that do not start with
//or#, joined and cut to 400 characters. - Ultra summary: the summary cut to 100 characters.
- Keywords: the five most frequent identifier-like words of three or more characters, excluding common stop words.
Output
Indexed 134 files, 1372 symbols, 134 modules, 3 subsystems (0 stale rebuilt)
With --json, the same counts come back as files_scanned, symbols, modules, subsystems and stale_rebuilt.
Incremental and full runs
Without --full, the indexer loads the previous symbols.json and module objects and reuses a file’s symbols and module when the stored hash matches. --full ignores the existing index.
In the current code the module object stores a hash of its generated summary, while the check compares it with the hash of the file content. The two never match, so every file is reported as stale and rebuilt on each run, and the result is the same as --full. Indexing the Trove repository a second time in a row reports (134 stale rebuilt).
Files that were deleted since the last run are dropped from symbols.json and from the manifest counts. Their old JSON files in .trove/modules/ and .trove/symbols/ are not removed. To start clean, delete .trove/ and run trove index again.
After indexing
trove queryandtrove askread the new index at once.- In a project trove, run
trove.sh context(or/trove:index, which runs both steps) to refresh the generated context entries and the<project>-contextskill. See Project troves. - See .trove directory format for every file and folder the index writes.
Known limitations
- Rust structs, enums, traits,
implblocks and inlinemodblocks, and JavaScript classes, get an empty name when the opening brace is on the same line, because the name is taken from the last word of the first line. Structs keep the full first line as their signature; the other kinds have no signature. In the Trove repository, 175 of 1,372 symbols have an empty name, 173 of them in Rust. - Tests are not captured as their own symbol kind. They appear as ordinary functions.
- The graph contains import edges only. It has no call graph or inheritance edges.