ByteRover Skill: A Context Tree That Stops AI Agents From Rediscovering the Same Things Twice

23,000+ downloads and 70 stars — byterover by @byteroverinc (ByteRover Inc.) is a project-level knowledge management system for AI agents. The core workflow is two commands: brv query before starting work, brv curate after completing it.

The result is an agent that starts each session with relevant context from previous sessions, without you re-explaining the codebase every time.

The Problem It Solves

AI agents are fast at writing code but slow to learn about specific codebases. Every session starts fresh. The agent has to re-discover:

• What authentication patterns you use
• Why a particular decision was made
• What the naming conventions are
• Which bugs have already been solved

The fix isn't a better model — it's a persistent knowledge layer between the model and the codebase. ByteRover is that layer.

The Two-Command Workflow

The skill is built around two operations:

# Before starting work: retrieve what's known
brv query "How is authentication implemented?"
 
# After completing work: store what was learned
brv curate "Auth uses JWT 24h expiry, tokens in httpOnly cookies" -f src/auth.ts

That's the entire workflow. Query to not repeat research. Curate to not lose knowledge.

Querying Effectively

# Pattern discovery
brv query "What validation library is used for API request schemas?"
 
# Architecture questions
brv query "How are background jobs structured?"
 
# Before implementing anything new
brv query "Are there existing patterns for error handling in this codebase?"

Use precise questions. ByteRover searches a knowledge tree — specific queries return faster and more relevant results than vague ones.

Curating Knowledge

The format is: context string + optional file references.

# Simple fact
brv curate "Database uses UUID primary keys, not auto-increment integers"
 
# With file reference (ByteRover reads the file — don't read it yourself first)
brv curate "Auth middleware validates JWT and attaches user to req.user" -f src/middleware/auth.ts
 
# With multiple files (max 5)
brv curate "Notification system: WebSocket for real-time, Redis pub/sub for scaling" \
  -f src/notifications/gateway.ts \
  -f src/notifications/service.ts

Let ByteRover read the files directly via -f. Don't read them yourself and paste the content — that wastes context.

What to Curate

Curate these:

• Architecture decisions with their reasoning
• Non-obvious patterns and conventions
• Bug root causes (so the same bug isn't diagnosed twice)
• Library choices and why
• Gotchas specific to this codebase

Don't curate:

• Obvious facts ("Uses TypeScript")
• Temporary states ("Currently debugging X")
• Anything in the README already

Updating Stale Knowledge

When you refactor or replace something, explicitly tell ByteRover to clean up:

# Signal that old context is outdated
brv curate "OUTDATED: Previous auth used session cookies in Redis. \
NEW: Migrated to JWT with refresh tokens. \
Access token in memory (15min), refresh token in httpOnly cookie (7d). \
Remove/update any session-based auth context." \
-f src/auth/jwt.ts -f src/auth/refresh.ts

The OUTDATED: / NEW: prefix tells ByteRover to supersede old entries on the same topic.

Breaking Down Large Changes

For significant features, multiple focused curations beat one massive dump:

# After adding a payment module — break into separate topics
brv curate "Payment overview: Stripe integration with webhooks for subscription management" \
  -f src/payments/
 
brv curate "Payment checkout: cart validation → createPaymentIntent → client confirmation. \
Errors: use PaymentIntentError types, surface StripeError.code to users" \
  -f src/payments/checkout.ts
 
brv curate "Webhook handling: verify STRIPE_WEBHOOK_SECRET, \
use processed_events table for idempotency, \
handle: payment_intent.succeeded, payment_intent.failed, customer.subscription.*" \
  -f src/payments/webhooks.ts

Smaller chunks are easier to retrieve than one monolithic topic.

Setup Check

# Verify ByteRover is running
brv status

ByteRover uses client-server architecture — the user runs brv to start the server (interactive REPL), and agent commands connect to it. If brv status shows errors, the user needs to start the server in a separate terminal before agent commands will work.

How to Install

clawhub install byterover

Workflow Patterns

The skill documents six common workflow patterns:

1. Explore before implement — Query first, then work
2. Capture immediately after completing — Don't wait until end of session
3. Break large changes into multiple curates — One topic per curate
4. Update stale context explicitly — Use OUTDATED: signal
5. Comprehensive documentation — Multiple curates for complex systems
6. Exploratory documentation — Curate as you understand, not just when complete

Comparison: byterover vs Alternatives

Practical Tips

1. brv query before every non-trivial task — Even if you think you know the codebase, querying first takes 5 seconds and might surface a gotcha that saves 30 minutes.

2. Curate gotchas immediately when you find them — "PostgreSQL JSONB queries need explicit casting for arrays" is exactly the kind of thing to capture the moment you discover it, not later.

3. Use file references for specificity — The same description plus -f src/specific-file.ts gives ByteRover the actual code to ground the knowledge in, making future retrievals more precise.

4. The server must be running — ByteRover's client-server architecture means the brv REPL must be active in a terminal. Build this into your session startup routine.

5. Start sessions with a status check — brv status tells you if the server is up and the project is initialized. One command, no surprises.

Considerations

• Server must be running — Agent commands require the brv server active. This is different from skills that just run scripts.
• Max 5 files per curate call — For large changes with many files, split into multiple curations by logical area.
• Knowledge tree quality depends on curation quality — Vague curations produce vague results on retrieval. Specific, actionable context with file references is most useful.
• Project must be initialized — Run /init in the brv REPL before first use. This sets up the project-specific knowledge tree.

The Bigger Picture

ByteRover makes a specific bet: that the bottleneck in AI-assisted development isn't the model's capability, it's the model's knowledge of your specific codebase. The context tree is the answer — not generic training data, but project-specific, continually-updated knowledge that accumulates with every session.

With 23,000+ downloads, it's found its audience among developers who work on long-running projects where codebase knowledge compounds over time.

View the skill on ClawHub: byterover