byterover

# ByteRover Knowledge Management

Use the `brv` CLI to manage your project's long-term memory. Knowledge is stored in `.brv/context-tree/` as human-readable Markdown.

Install: `npm install -g byterover-cli`. **No authentication needed. No LLM provider needed.** `brv query`, `brv search`, `brv read`, `brv curate`, and `brv vc` (local version control) all run locally. Your own LLM drives any synthesis or HTML authoring step. Login is only required for remote sync (`brv vc push` / `brv vc pull`).

## First-Turn Routing

**Check this before anything else on every user turn.**

If the user message reads as a request for an introduction, tour, or overview of ByteRover — for example:

- "Show me how ByteRover works" (canonical phrase from the install docs)
- "Walk me through ByteRover" / "Give me a ByteRover tour"
- "How does ByteRover work?"
- "Intro me to ByteRover" / "Show me ByteRover"
- Any semantic equivalent ("can you walk me through this", "explain ByteRover to me", etc.)

→ **Stop reading this file. Open `onboarding.md` and follow it.** Do NOT run `brv query`, `brv search`, or `brv curate` before the tour — the tour itself runs those commands as part of the demonstration.

For every other request, continue below to the Iron Law.

## The Iron Law

```
QUERY BEFORE THINKING. CURATE AFTER IMPLEMENTING.
```

`brv query` first — retrieve relevant context from the context tree before forming an answer or starting a change. `brv curate` after — save new patterns, decisions, or learned facts before claiming done. **Violating the letter of the rule is violating the spirit of the rule.** No exceptions without your human partner's permission.

## Curate Dispatch — Read This Before Calling `brv curate`

`brv curate` is a multi-step session (kickoff → author → continuation → validate, ~10-60s per topic) that BLOCKS the user's conversation when run inline. Your default for any substantive curate is to dispatch it to the **saved `brv-curate` sub-agent** — the operational protocol (HTML contract, session state machine, envelope path, `--response-file` form, `path-exists` merging, retry cap, return shape) lives in the saved agent's definition, so your dispatch ONLY hands over the facts.

**Claude Code** — tool-call dispatch:

```ts
Agent({
  subagent_type: "brv-curate",
  description: "brv curate (background)",
  prompt: `Curate the following 1-5 facts:\n1. <summary>\n   Body: <context>\n...`,
  run_in_background: true,
})
```

**Codex** — conversational dispatch (Codex has no `subagent_type` tool param; it spawns named agents on explicit instruction):

> Spawn the `brv-curate` agent with the following 1-5 facts. Return the aggregate `{ completed, pending_review, failed, file_paths }`.
>
> 1. `<summary>` — Body: `<context>`
> 2. `<summary>` — Body: `<context>` ...

**Decision in one line:**

| Situation | Dispatch shape |
|---|---|
| 1 substantive curate | **One** dispatch carrying that one fact. |
| 2-5 substantive curates this turn | **One** dispatch carrying all of them — the worker handles them sequentially. |
| 6+ substantive curates (bootstrap / repo scan) | **Multiple** dispatches, each carrying a 2-5-fact chunk, fired sequentially (wait for chunk N's completion before firing chunk N+1). |
| Trivial / one-fact / user said "wait" / turn-dependent on the result | Run inline. |

**Do NOT** run a substantive curate inline. **Do NOT** fan out N parallel sub-agents on the same project — the daemon's overlap lock will reject every sub-agent after the first. **Do NOT** inline the curate protocol into the dispatch prompt — the saved agent definition has it.

The saved agent definition MUST be deployed at the right path for each surface:

| Surface | Deployed path | Falls back if missing |
|---|---|---|
| Claude Code | `.claude/agents/brv-curate.md` (project) or `~/.claude/agents/brv-curate.md` (user) | `subagent_type` resolves to the default general-purpose agent — which lacks `permissionMode: bypassPermissions` and hits the auto-deny problem. |
| Codex | `.codex/agents/brv-curate.toml` (project) or `~/.codex/agents/brv-curate.toml` (user) | Named-agent dispatch fails — Codex runs the curate in the main thread instead of a worker. |

Full dispatch shape, permission pre-authorization, the chunked-orchestrator pattern, and both saved-agent definitions all live in `curate.md`. Open it before your first curate dispatch in any session.

## When To Use This Skill

Invoke `brv` when:

- The user wants you to recall something from this project
- Your context does not contain information you need
- Before performing any action, to check for relevant rules, criteria, or preferences
- You need to recall your capabilities or prior actions
- The user wants you to remember something
- The user intentionally curates memory or knowledge
- There are meaningful memories from user interactions worth persisting
- There are important facts about what was done, what is known, or what decisions and actions have been taken

## When NOT To Use This Skill

Do NOT invoke `brv` when:

- The information is already present in your current context
- The query is about general knowledge, not stored memory
- The information is already stored unchanged
- The information is transient (only relevant to the current task) or general knowledge

## Decision Flowchart

```dot
digraph brv_flow {
    start [label="User message arrives", shape=doublecircle];
    need_context [label="Need project context\nfor the next step?", shape=diamond];
    skip [label="Skip brv.\nRespond from context.", shape=ellipse];
    know_path [label="Already know the\nexact topic path?", shape=diamond];
    paths_only [label="Need ranked paths /\nexcerpts only?", shape=diamond];
    swarm_cfg [label="2+ memory providers\nconfigured?\n(brv swarm status)", shape=diamond];
    query [label="brv query <text>\n--format json", shape=box, style=filled, fillcolor="#ccffcc"];
    search [label="brv search <text>", shape=box, style=filled, fillcolor="#ccffcc"];
    read [label