> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byterover.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Context Tree Structure

<Tip>
  Prefer a visual workflow? See [Contexts in the web UI](/local-web-ui/contexts).
</Tip>

## What is a Context Tree?

A context tree is your project's hierarchically organized knowledge base stored in `.brv/context-tree/`. It captures patterns, best practices, and learnings in a structured format that's both human-readable and intelligently searchable.

## Structure

The context tree organizes knowledge into a three-level hierarchy. ByteRover also automatically maintains several system-generated files alongside your curated content — described in detail in the sections below.

### 1. Domains

Top-level folders that group related knowledge areas. ByteRover automatically detects and creates domains on-demand as you curate, letting your context tree structure emerge naturally from your project.

```
.brv/context-tree/
├── authentication/
│   └── context.md        # auto-generated domain overview
├── api-design/
│   └── context.md
└── database/
    └── context.md
```

### 2. Topics

Specific subjects within each domain:

```
.brv/context-tree/
├── authentication/
│   ├── context.md
│   ├── jwt-implementation/
│   │   └── context.md    # auto-generated topic overview
│   ├── oauth-flow/
│   │   └── context.md
│   └── session-management/
│       └── context.md
├── api-design/
│   ├── context.md
│   ├── rest-endpoints/
│   │   └── context.md
│   └── graphql-schema/
│       └── context.md
└── database/
    ├── context.md
    ├── user-models/
    │   └── context.md
    └── migration-strategy/
        └── context.md
```

### 3. Subtopics (Optional)

Deeper organization within topics (maximum one level):

```
.brv/context-tree/
└── authentication/
    ├── context.md
    └── jwt-implementation/
        ├── context.md
        ├── jwt_token_generation.md
        └── refresh-tokens/               # Subtopic
            ├── context.md                # auto-generated subtopic overview
            └── refresh_token_rotation.md
```

## Auto-Generated Overview Files

ByteRover creates a `context.md` file at each hierarchy level when you first curate into a domain, topic, or subtopic. These overviews document the scope and purpose of each node, making the tree self-describing and easier to navigate.

**Domain-level `context.md`** — describes what the domain covers and its boundaries:

```markdown theme={null}
# Domain: authentication

## Purpose
Covers all authentication and authorization patterns used in this project.

## Scope
Included in this domain:
- JWT token generation and validation
- OAuth 2.0 flows
- Session management and refresh tokens

Excluded from this domain:
- API rate limiting (see api-design)
- Database user models (see database)

## Ownership
Backend team

## Usage
Reference when implementing login flows, token handling, or access control.
```

**Topic-level `context.md`** — summarizes the topic's focus and connections:

```markdown theme={null}
# Topic: jwt-implementation

## Overview
Patterns and conventions for JSON Web Token generation, validation, and rotation.

## Key Concepts
- Access tokens expire after 24 hours
- Refresh token rotation prevents replay attacks
- Token signing uses RS256 algorithm

## Related Topics
- authentication/oauth-flow
- database/user-models
```

**Subtopic-level `context.md`** — narrows focus within a parent topic:

```markdown theme={null}
# Subtopic: refresh-tokens

## Focus
Refresh token rotation strategy and revocation handling.

## Parent Relation
Part of jwt-implementation — covers the token renewal lifecycle.
```

## Hierarchical Summaries (`_index.md`)

After each curation, ByteRover automatically generates an `_index.md` file inside every directory that received new or updated content. The summary propagates upward through the hierarchy — a change to a subtopic file triggers regeneration at the subtopic, topic, domain, and root levels.

Each `_index.md` contains a system-generated condensed summary of the directory's knowledge with YAML frontmatter:

```markdown theme={null}
---
children_hash: "a3f9c2..."
compression_ratio: 0.18
condensation_order: 2
covers:
  - context.md
  - jwt-implementation/_index.md
covers_token_total: 3400
summary_level: d2
token_count: 612
type: summary
---

Summary of this domain's knowledge: authentication covers JWT-based token generation
with RS256 signing, OAuth 2.0 authorization code flows, and session management via
httpOnly refresh tokens. Key conventions: 24-hour access token TTL, single-use refresh
rotation, tokens stored in PostgreSQL for revocation...
```

**`condensation_order`** indicates depth relative to the context tree root:

| Level    | `condensation_order` | Description                          |
| -------- | -------------------- | ------------------------------------ |
| Root     | `3` (d3)             | Broadest — covers all domains        |
| Domain   | `2` (d2)             | Covers all topics in a domain        |
| Topic    | `1` (d1)             | Covers all knowledge in a topic      |
| Subtopic | `0` (d0)             | Narrowest — covers a single subtopic |

`_index.md` files are **not synced** with `vc push`/`vc pull` — they are regenerated locally after each curate. They are also excluded from BM25 search indexing, but injected as structural context when ByteRover uses an LLM to answer a query (Tier 3/4).

## Knowledge Abstracts

ByteRover generates two companion files for each knowledge file, providing compressed representations at different levels of detail:

| Type            | File Suffix    | Size           | Purpose                                                                 |
| --------------- | -------------- | -------------- | ----------------------------------------------------------------------- |
| **L0 Abstract** | `.abstract.md` | \~80 tokens    | One-line summary capturing the core topic and key insight               |
| **L1 Overview** | `.overview.md` | \~1,500 tokens | Structured overview with 3–7 key points, notable entities, and patterns |

For example, `jwt_token_generation.md` produces two siblings:

* `jwt_token_generation.abstract.md`
* `jwt_token_generation.overview.md`

Both are generated deterministically (temperature 0) by an LLM. The source content is truncated to 20,000 characters before processing to handle large files. Generation runs in a background queue — one file at a time with exponential backoff (500ms, 1s, 2s) and up to 3 retries.

The manifest service prefers `.abstract.md` siblings when injecting context for LLM queries, falling back to the full knowledge file if the abstract hasn't been generated yet. This reduces token usage while preserving the key information the agent needs.

## Manifest (`_manifest.json`)

ByteRover maintains a `_manifest.json` at the root of the context tree. It provides a token-budgeted registry of all context entries, organized into three lanes:

| Lane        | Contents                             | Ordered By                          |
| ----------- | ------------------------------------ | ----------------------------------- |
| `summaries` | All `_index.md` files                | Condensation order (broadest first) |
| `contexts`  | All regular `.md` knowledge files    | Importance score (highest first)    |
| `stubs`     | All `_archived/*.stub.md` ghost cues | Insertion order                     |

For LLM-based queries (Tier 3/4), ByteRover reads the manifest to determine which files to inject as structural context without scanning the full tree on every request. The manifest is rebuilt opportunistically after each curation (if summaries changed) and lazily on query if stale. It is **not synced** with `vc push`/`vc pull`.

## Archive System

Knowledge files that fall below an importance threshold are eligible for archiving. A file qualifies when it meets both criteria:

* **Maturity**: `draft` (has not yet been promoted to `validated` or `core`)
* **Decayed importance**: below 35 after applying the recency decay function

When a file is archived, it is replaced with two derived files under `_archived/`, mirroring the original path:

```
authentication/jwt-implementation/old_draft.md
  → _archived/authentication/jwt-implementation/old_draft.stub.md
  → _archived/authentication/jwt-implementation/old_draft.full.md
```

### Archive Stub (`.stub.md`)

A compact ghost cue (\~220 tokens) that remains **BM25 searchable**. It contains a system-generated summary of the original content and frontmatter with lineage metadata:

```markdown theme={null}
---
evicted_at: "2025-04-15T10:00:00Z"
evicted_importance: 22.4
original_path: "authentication/jwt-implementation/old_draft.md"
original_token_count: 890
points_to: "_archived/authentication/jwt-implementation/old_draft.full.md"
type: archive_stub
---

Describes an early-draft authentication flow that used symmetric HMAC-SHA256 signing
before the team standardized on RS256. Key entities: jwt_secret, sign(), verify()...
```

Stubs appear in search results like any other knowledge file. They are **not synced** with `vc push`/`vc pull`.

### Full Archive (`.full.md`)

A lossless copy of the original file. It is **not searchable** and **not synced**. Its sole purpose is to be readable on demand when you need the complete original content.

### Full Structure Example

With all components in place, a mature context tree looks like this:

```
.brv/context-tree/
├── _manifest.json                    # auto-generated manifest
├── _index.md                         # auto-generated root summary
├── authentication/
│   ├── _index.md                     # auto-generated domain summary
│   ├── context.md                    # auto-generated domain overview
│   ├── jwt-implementation/
│   │   ├── _index.md                 # auto-generated topic summary
│   │   ├── context.md                # auto-generated topic overview
│   │   ├── jwt_token_generation.md
│   │   ├── jwt_token_generation.abstract.md   # auto-generated L0 abstract
│   │   ├── jwt_token_generation.overview.md   # auto-generated L1 overview
│   │   └── refresh-tokens/
│   │       ├── _index.md             # auto-generated subtopic summary
│   │       ├── context.md            # auto-generated subtopic overview
│   │       ├── refresh_token_rotation.md
│   │       ├── refresh_token_rotation.abstract.md
│   │       └── refresh_token_rotation.overview.md
└── _archived/
    └── authentication/
        └── jwt-implementation/
            ├── old_draft.stub.md     # searchable ghost cue
            └── old_draft.full.md    # lossless archive (not synced)
```

## Knowledge Files

Each topic (and subtopic) contains markdown knowledge files with descriptive names. These files use YAML frontmatter for semantic metadata (title, summary, tags, related, keywords, timestamps) alongside the knowledge content.

**File format:**

````markdown theme={null}
---
title: "JWT Token Generation"
summary: "Access and refresh token pair generation with RS256 signing and single-use rotation"
tags: ["auth", "jwt", "security"]
keywords: ["token", "access_token", "refresh_token", "RS256"]
related: ["authentication/session-management", "database/user-models/token-storage"]
createdAt: "2025-03-18T10:00:00Z"
updatedAt: "2025-04-02T14:30:00Z"
---

## Raw Concept

**Task:**
JWT token generation and rotation pattern

**Files:**
- src/auth/jwt.ts
- src/auth/refresh.ts

**Flow:**
Login request → Validate credentials → Generate access token → Generate refresh token → Store refresh in DB → Return token pair

## Narrative

### Structure
Access and refresh tokens are generated as a pair on every login.

### Rules
- Access tokens expire after 24 hours
- Refresh tokens expire after 7 days
- Refresh tokens are single-use with rotation

### Examples
```typescript
function generateTokens(userId: string) {
  const accessToken = jwt.sign(
    { userId, type: 'access' },
    process.env.JWT_SECRET,
    { expiresIn: '24h' }
  );

  const refreshToken = jwt.sign(
    { userId, type: 'refresh' },
    process.env.REFRESH_SECRET,
    { expiresIn: '7d' }
  );

  return { accessToken, refreshToken };
}
```

## Facts
- **jwt_secret**: Access tokens are signed with RS256 algorithm [convention]
- **refresh_token**: Refresh tokens are single-use and rotated on each renewal [convention]
- Token pairs are stored in the database for revocation tracking [project]
````

### Frontmatter Fields

| Field       | Type      | Description                                             |
| ----------- | --------- | ------------------------------------------------------- |
| `title`     | string    | Knowledge file title                                    |
| `summary`   | string    | One-line summary of the file's content                  |
| `tags`      | string\[] | Tags for categorization                                 |
| `keywords`  | string\[] | Search keywords                                         |
| `related`   | string\[] | Paths to related topics (e.g., `domain/topic/title.md`) |
| `createdAt` | string    | ISO 8601 creation timestamp                             |
| `updatedAt` | string    | ISO 8601 last-update timestamp                          |

<Note>
  Since 3.8.0, `brv curate` and `brv dream` always write all seven fields. Files written by earlier versions without `summary` still load fine — the field is optional on read.
</Note>

### Content Sections

Knowledge files can contain up to three optional sections:

* **Raw Concept** — Technical metadata: task description, relevant files, execution flow, patterns
* **Narrative** — Descriptive context: structure, dependencies, rules, examples, diagrams (Mermaid, PlantUML)
* **Facts** — Structured factual statements extracted during curation, each with an optional subject, value, and category (`personal`, `project`, `preference`, `convention`, `team`, `environment`, `other`)

## Scoring Metadata

Every knowledge file carries scoring signals that determine how it ranks in search results and where it sits in the maturity lifecycle. These signals live in a per-project sidecar outside the context tree, so `brv vc status` and `brv vc diff` stay clean even as search and curation update them in the background.

**Importance** (0–100) — Reflects how valuable this knowledge is. Starts at 50 for new files:

* +3 each time the file appears in search results (batch-flushed during index rebuild)
* +5 each time the file is updated via curation
* Decays by `0.995^days` when idle (\~78% remaining after 50 days of non-use)

**Recency** (0–1) — Reflects how fresh this knowledge is. Decays exponentially over time:

* Resets to 1.0 whenever the file is updated
* Halves roughly every 21 days (`e^(-days/30)`)

**Maturity tier** — Lifecycle stage based on importance score (see below).

These three signals feed into a [compound scoring formula](/context-tree/query-engine#compound-scoring) used during search to balance relevance, value, and freshness.

<Note>
  Context trees created before 3.7.1 may carry these signals in markdown frontmatter. They continue to parse — stale fields are ignored on read, so no migration is needed.
</Note>

## Maturity Lifecycle

Knowledge files progress through three maturity tiers based on their importance score. Promotion and demotion thresholds are offset (hysteresis) to prevent rapid oscillation when a score hovers near a boundary.

```
                importance ≥ 65            importance ≥ 85
  ┌───────┐ ──────────────────► ┌───────────┐ ──────────────► ┌──────┐
  │ draft │                     │ validated  │                 │ core │
  └───────┘ ◄────────────────── └───────────┘ ◄────────────── └──────┘
                importance < 35            importance < 60
```

| Tier          | Search Boost | Description                               |
| ------------- | ------------ | ----------------------------------------- |
| **draft**     | ×0.85        | New or infrequently accessed knowledge    |
| **validated** | ×1.0         | Actively used and regularly updated       |
| **core**      | ×1.15        | High-value, frequently accessed knowledge |

Hysteresis means a file must drop significantly below its promotion threshold before being demoted — a `core` file promoted at importance 85 won't demote until it falls below 60.

`draft` files whose decayed importance falls below **35** become eligible for archiving — replaced by a searchable stub and a lossless full archive (see [Archive System](#archive-system) above).

## Relations

Relations create explicit connections between topics using path notation in the frontmatter `related` field:

```yaml theme={null}
related:
  - "authentication/session-management"
  - "api-design/rest-endpoints"
  - "database/user-models/token-storage"
```

**Why relations matter:**

* Enable **graph-like navigation** between related knowledge
* Not based on similarity scores — these are explicit, intentional links
* Help find comprehensive context by following connections
* Prevent knowledge silos

When you query about authentication, ByteRover can intelligently follow these relations to gather comprehensive context.

## Why This Matters

**Human-readable and git-friendly:**

* Browse the context tree in your file explorer
* Edit markdown files with any text editor
* Track changes with git
* Review in pull requests

**Hierarchical organization prevents "context soup":**

* Knowledge is categorized by domain and topic
* Self-documenting via auto-generated `context.md` at every level
* `_index.md` summaries give instant high-level overviews without reading individual files
* Clear structure vs flat document storage

**Scoring and maturity surface what matters:**

* Frequently used knowledge ranks higher in search
* Stale knowledge naturally fades without manual cleanup
* Core knowledge gets priority when results are tight
* Low-importance drafts are archived automatically, keeping the active tree lean

**Explicit relations enable precise navigation:**

* ByteRover follows connections between topics
* More reliable than similarity-based search
* Intentional knowledge graph vs automatic clustering