Trove / Guides
Memory hierarchy
The L0 to L6 memory levels defined in Trove's source, and which of them the current engine actually builds, stores and retrieves, with its compression tiers.
On this page
Trove’s original design document, VISION.md, describes seven memory levels, from working memory (L0) to repository-wide knowledge (L6). The document is now marked historical and is no longer updated, but all seven levels exist as types in the trove-core crate. This page describes what the current code does with each one. Planned behavior that is not built is on the Roadmap.
First principles
Memory is useful at different time scales. The current edit matters for minutes. The symbols involved in a task matter for that task. A file’s purpose holds for weeks, a subsystem’s shape for months, and a decision can hold for years. Treating all of it as one pile means either loading too much or forgetting what lasts.
The hierarchy orders memory by scope and lifetime, and gives each level a different size: the wider and longer-lived the level, the fewer tokens it should take. That is what lets a query start wide and cheap and descend only where needed. In practice the engine builds the middle of the hierarchy (L1 to L4) from code, imports L5 from your troves, and leaves the ends (L0 and most of L6) as types without behavior.
Levels at a glance
| Level | Built by | Used by query |
|---|---|---|
| L0 Working | nothing | no |
| L1 Active Symbols | index |
yes |
| L2 Module | index |
yes |
| L3 Subsystem | index |
yes |
| L4 Architecture | index |
yes |
| L5 Historical | import-historical |
yes |
| L6 Repository | import-historical |
no |
This table is about trove query. trove ask reads the engine index (L1 to L4) and the trove folders directly, without going through L5 or L6. See Asking questions.
L0 Working Memory
The type exists, but no command writes working memory objects, and the query pipeline does not read them. The budget still reserves a 10% working memory slice.
L1 Active Symbols
Functions, classes, methods, structs, enums, traits, modules and Bash commands parsed with tree-sitter. See Indexing a repository for the per-language list. Queries return symbols whose name or path matches a query term.
L2 Module Memory
One summary per indexed file: symbol counts, exports, imports, and inferred assumptions and side effects. Built by fixed rules, not by a language model.
L3 Subsystem Memory
Files grouped by their top-level folder. The confidence is recorded as medium (0.6), with the reason clustered by top-level package directory.
L4 Architecture Memory
A single synthesized summary of the repository: counts, the largest subsystems, and fixed text describing the retrieval order.
L5 Historical Memory
trove import-historical reads trove entries (.md and .json files) from ./.claude/trove in the indexed repository and from ~/.claude/trove, and stores each as a historical object with the id historical:<slug>. It reads the flat entries/ folder and the conventions/, memory/ and context/ sections alike. Queries return up to three of them.
Two more kinds of record map to L5 in the source and are written to .trove/, but are not used by queries:
- Execution memory.
trove record open|search|commandappends an event to.trove/execution.json. The file keeps the most recent 500 events. - Patch memory.
trove patchappends a record with a path, before and after hashes and a reason to.trove/patches.json.trove shiplists the latest 30 in its decisions document.
L6 Repository Memory
trove import-historical also stores each trove’s INDEX.md as one repository object, repository:index. Both troves use the same id, so when both exist the personal trove’s index, imported second, replaces the project’s. The query pipeline does not read it.
Compression tiers
Every memory object carries text at several tiers: raw, summary (cut to 400 characters), ultra summary (cut to 100 characters) and up to five keywords. An embedding field exists but is never filled. Queries return the summary tier, and the ultra summary tier for oversized architecture summaries and dependency neighbors.
Default budgets per level
trove-core defines a default token budget per level (L0 20,000; L1 30,000; L2 40,000; L3 30,000; L4 30,000; L5 20,000; L6 10,000). The query pipeline does not use these values. It uses the percentage slices described in Retrieval levels.
How the troves fit
The personal and project troves are separate from .trove/. They are not a numbered level on their own: trove query sees them only after trove import-historical copies their entries into L5 and their indexes into L6. The plugin reads the troves directly through its skills and the SessionStart hook, and trove ask reads them directly too.