Sources

What Are Sources?

Sources let you reference curated knowledge from other ByteRover projects. When you add a source, its context tree becomes searchable alongside your own — without copying any data. Results are attributed to their origin so you always know where knowledge came from. This is useful when:

Platform teams share auth patterns, infrastructure conventions, or API guidelines
Shared libraries document their conventions for downstream consumers
Design systems provide component guidelines to frontend teams
Cross-team collaboration requires visibility into each other’s curated knowledge

How It Works

Sources are declarative, one-way references stored in your project’s .brv/sources.json. Nothing is written to the target project — it doesn’t even know you’ve referenced it.

your-project/.brv/
  ├── config.json
  ├── context-tree/              # your local knowledge
  └── sources.json               # references to other projects

sources.json structure:

{
  "version": 1,
  "sources": [
    {
      "alias": "auth",
      "projectRoot": "/path/to/auth-service",
      "addedAt": "2026-04-10T12:00:00.000Z",
      "readOnly": true
    }
  ]
}

When you run a query, ByteRover searches:

Your local context tree first
Each configured source’s context tree
Returns combined results with origin attribution

Local results get a slight relevance boost, so your own knowledge ranks first when equally relevant.

Commands

All source commands are available as both CLI commands and TUI slash commands.

`source add`

Add a read-only knowledge source from another ByteRover project.

brv source add <path> [--alias <name>]

/source add <path> [--alias <name>]

Arguments:

Argument	Description	Required
`path`	Path to the target project (must have `.brv/config.json`)	Yes

Flags:

Flag	Description
`--alias`	Custom identifier for the source. Defaults to the target directory name

Examples:

# Add a source with default alias (directory name)
brv source add /path/to/shared-lib
# Output: Added source "/path/to/shared-lib" as "shared-lib".

# Add with a custom alias
brv source add ../auth-service --alias auth
# Output: Added source "../auth-service" as "auth".

`source list`

Display all configured sources and their validation status.

brv source list

/source list

Example output:

Knowledge Sources:
   shared-lib → /path/to/shared-lib (valid)
   auth → /path/to/auth-service (valid)

With a broken source:

Knowledge Sources:
   shared-lib → /path/to/shared-lib (valid)
   auth → /deleted/path [BROKEN - run brv source remove auth]

Broken sources (where the target’s .brv/ has been deleted) are excluded from search results but remain in the configuration until you explicitly remove them. This prevents silent data loss.

`source remove`

Remove a knowledge source reference. Only deletes the local reference — the target project is untouched.

brv source remove <alias-or-path>

/source remove <alias-or-path>

Arguments:

Argument	Description	Required
`alias-or-path`	The source alias or full path to the target project	Yes

Examples:

# Remove by alias
brv source remove auth
# Output: Removed source "auth" (/path/to/auth-service).

# Remove by path
brv source remove /path/to/shared-lib
# Output: Removed source "shared-lib" (/path/to/shared-lib).

Search Integration

When you query a project with sources configured, results include origin information:

brv query "JWT validation"

# Results might include:
# [local]:authentication/jwt-implementation/context.md     (your project)
# [auth]:security/token-validation/context.md              (from auth source)

Origin Attribution

Each result is prefixed with its origin:

Prefix	Meaning
`[local]`	From your project’s context tree
`[alias]`	From the named source’s context tree

Relevance Ranking

Local results get a slight score boost when relevance is similar
Results from all sources are merged and ranked together
The most relevant result wins regardless of origin

Write Protection

Sources are strictly read-only. ByteRover enforces write guards at the tool level:

Attempting to curate into a shared source fails with: Cannot write to shared source — sources are read-only.
All mutation tools (write_file, curate) check file paths against source paths before allowing writes
Protection is fail-closed: if context can’t be determined, writes are blocked

This ensures you never accidentally modify another project’s knowledge base through a source reference.

Error Handling

Error	Cause	Resolution
Target is not a ByteRover project	Path doesn’t have `.brv/config.json`	Initialize the target with `brv` first
Cannot add self as source	You tried to reference your own project	Add a different project
Duplicate source	Same path already configured	The source is already available — no action needed
Circular source detected	Target already references this project	Remove one direction to break the cycle
Source marked as BROKEN	Target’s `.brv/` was deleted or moved	Run `brv source remove <alias>` to clean up

Practical Examples

# Auth team curates their patterns
cd /auth-service
brv curate "JWT tokens use RS256, expire in 24h, refresh tokens in 7d"

# Product team references auth knowledge
cd /product-api
brv source add /auth-service --alias auth

# Product devs can now query auth patterns from their own project
brv query "token expiration policy"
# Returns: [auth]:security/jwt-tokens/context.md

Multi-Source Architecture

cd /frontend-app
brv source add /design-system --alias design
brv source add /api-gateway --alias api
brv source add /shared-utils --alias utils

brv source list
# Knowledge Sources:
#    design → /design-system (valid)
#    api → /api-gateway (valid)
#    utils → /shared-utils (valid)

brv query "button component variants"
# Searches: local + design + api + utils context trees

Combined with Worktrees

Sources configured in a parent project are automatically available from all linked worktrees:

# Parent project configures sources
cd /monorepo
brv source add /design-system --alias design

# Worktree inherits sources through the pointer
cd /monorepo/packages/web
brv query "color tokens"
# Searches: monorepo context tree + design-system source

Getting Started

LLM Providers

Agent Connectors

Context Tree

Knowledge Sharing

Memory Swarm

Git-Semantic Version Control

Review Changes

BRV Hub

Headless Mode

Daemon-First Architecture

Local Web UI

Reference

FAQs

Security

ByteRover Cookbook

What Are Sources?

How It Works

Commands

`source add`

`source list`

`source remove`

Search Integration

Origin Attribution

Relevance Ranking

Write Protection

Error Handling

Practical Examples

Multi-Source Architecture

Combined with Worktrees

​What Are Sources?

​How It Works

​Commands

​source add

​source list

​source remove

​Search Integration

​Origin Attribution

​Relevance Ranking

​Write Protection

​Error Handling

​Practical Examples

​Platform Team Sharing Auth Patterns

​Multi-Source Architecture

​Combined with Worktrees

What Are Sources?

How It Works

Commands

`source add`

`source list`

`source remove`

Search Integration

Origin Attribution

Relevance Ranking

Write Protection

Error Handling

Practical Examples

Platform Team Sharing Auth Patterns

Multi-Source Architecture

Combined with Worktrees