Skip to content
Trove

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
  1. First principles
  2. Levels at a glance
  3. L0 Working Memory
  4. L1 Active Symbols
  5. L2 Module Memory
  6. L3 Subsystem Memory
  7. L4 Architecture Memory
  8. L5 Historical Memory
  9. L6 Repository Memory
  10. Compression tiers
  11. Default budgets per level
  12. How the troves fit

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|command appends an event to .trove/execution.json. The file keeps the most recent 500 events.
  • Patch memory. trove patch appends a record with a path, before and after hashes and a reason to .trove/patches.json. trove ship lists 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.