byterover

ByteRover — 永続的なプロジェクトメモリ

ByteRover は、プロジェクトの知識を決定論的なコンテキストツリーとして保持します。あなたが頭脳であり、エンジンが LLM を呼び出すことはありません。 あなたが推論を行い、同梱された決定論的スクリプトを（Bash ツール経由で）実行して、知識を取得または保存します。

鉄則

1. 考える前にクエリする。 重要なタスクに着手する際は、プロジェクトがすでに把握していることを取得し、再度導き出したり、既存の知識と矛盾したりしないようにします。
2. 実装したら整理して保存する。 覚えておく価値のあること（決定事項、注意点、パターン）を完了したら、次のセッションに引き継がれるように書き戻します。

メモリの保存場所

エンジンは、作業ディレクトリに基づいて適切なコンテキストツリーを特定します。保存パスを計算、検索、上書きする必要はありません。 プロジェクト内（任意のサブディレクトリで構いません）でコマンドを実行すると、適切なツリーが自動的に見つかります。リゾルバーとレジストリはエンジン内部で処理されます。

言語

ユーザーの入力言語に合わせます。 人間が読む内容は、ユーザーが会話で使っている言語で記述してください。対象は、<bv-*> 要素の本文、リスト項目、および <bv-topic> の title / summary 属性です。設定やフラグはありません。返信時と同様に、会話から言語を判断します。

スキーマは英語のままにします。 ツールとの一貫性を保つため、タグ名（翻訳したタグではなく、<bv-fact>）、属性名（subject、category、severity）、列挙値（category="project"、subject="visa_required"）、および path 属性は英語のままにしてください。コードスニペットと識別子もそのまま保持します。

具体例（ベトナム語での会話）：path="travel/vietnam_visa" と subject="visa_required" category="project" は英語のままにし、title="Yêu cầu visa Việt Nam" と <bv-fact> の本文（Người Mỹ cần visa để vào Việt Nam.）はベトナム語にします。中国語、日本語、韓国語、ロシア語、アラビア語などでも同じルールが適用されます。

コマンド

プロジェクト内（任意のサブディレクトリで構いません）から実行します。トピックは <bv-*> HTML として保存されます。スペース（デフォルトを含む）は ByteRover デスクトップアプリで用意します。エージェントが作成することはありません。

必要な操作	コマンド
取得	node scripts/query.mjs "<question>" --limit 5
保存（複数要素を含むリッチなトピック）	node scripts/record.mjs "<topic-path>" --html '<bv-topic …>…</bv-topic>' — 以下の「リッチなトピックの作成」の実例を参照してください。この行をもとに形式を推測して作成しないでください
保存（シンプルな単一事実のトピック）	node scripts/record.mjs "<topic-path>" --title "T" --summary "S" --keywords a,b --body "..."
1 回の呼び出しで複数のトピックを保存	node scripts/record.mjs --batch --input <ndjson-file>（1 行につき 1 つの JSON 仕様を記述します：{"path":"...","html":"<bv-topic …>…</bv-topic>","overwrite"?:true}。バッチ全体で認証チェックとマニフェスト／インデックスの再構築を 1 回ずつ行います。N 件のトピックを 1 件ずつ記録するより大幅に高速です。行ごとの失敗は failed[] に報告され、実行は中断されません）

必須の<bv-topic>属性：pathとtitleは、トピックのルートに存在し、空でない必要があります。そうでない場合、ライターは呼び出しを拒否します。<bv-topic>のpathは、record.mjsに渡す位置引数の<topic-path>と一致させてください。属性の完全な仕様については、vocabulary.mdを参照してください。 | 読み取り | node scripts/brv.mjs read "<topic-path>.html" [--raw]（ディスク上のHTMLをバイト単位でそのまま取得するには--rawを使用します。record --htmlでラウンドトリップする場合に必須です。elements[].textでは、内部の<ul>／<li>／<strong>の書式がフラット化されるためです） | | 一覧表示 | node scripts/brv.mjs list | | マニフェストとインデックスを再構築 | node scripts/manifest.mjs | | 統合の機会を検出 | node scripts/dream.mjs --mode merge\|link\|prune\|synthesize（提案のみで、実行はしません） | | あるトピックを別のトピックに統合 | node scripts/merge.mjs <survivor> <loser> [--title "…"] [--summary "…"] [--tags a,b] [--keywords a,b] [--reason "…"] [--related @x.html,@y.html]（統合後の範囲を反映した新しいタイトルを残す側のトピックに付けるには、--titleを使用します。指定しない場合、統合後の内容がより広範になっても、残す側のトピックは元のタイトルを維持します） | | 冗長なトピックを削除 | node scripts/prune.mjs <topic-path>...（可変個の引数を受け付けます。アトミックに実行され、最初の失敗時に部分的なレポートを出して中止します） | | 複数のトピックを新しいトピックに統合 | node scripts/synthesize.mjs <new-path> --html '<bv-topic …>…</bv-topic>' --absorb a.html,b.html,c.html | | 現在のスペース内でトピックの名前を変更／移動／親を変更 | node scripts/move.mjs <topic-path> --to-path <new-path>（アトミックに実行され、兄弟トピックのrelated=参照は新しいパスに書き換えられます。シグナルのサイドカーも引き継がれます。名前の変更、新しい親への移動、階層をまたいだ親の変更、およびそれらの組み合わせすべてに対応します） | | 2つのトピック間のrelated=相互リンクを追加または削除 | node scripts/brv.mjs link "<a>" "<b>" [--bidirectional] [--remove]（<bv-topic related="…">属性をアトミックに編集し、バイト列を保持します。>文字を含むサマリーでは開始タグの手動編集は安全でないため、代わりにこのコマンドを使用してください。冪等で、リンクを再設定しても処理は行われません。存在しないトピックへの参照追加は拒否されます（参照先が宙に浮くため）。ただし、既存の宙に浮いた参照を整理できるよう、--removeでは存在しない参照先も許可されます） | | トピックを別のスペースに移動 | node scripts/move.mjs <topic-path> --from-space <name> --to-space <name>（両方のスペースでマニフェストとインデックスを再構築し、移動元の兄弟トピックに宙に浮くrelated=参照があれば報告します） | | レガシーMarkdownを移行 | node scripts/migrate.mjs [--dry-run] | | セルフホスト版v3 VPSからv4への移行（手順全体をガイド） | migrate-v3-to-v4.mdに従ってください | | ByteRoverの認証／ログイン | node scripts/auth.mjs — すぐに戻ります。ユーザーがブラウザーで承認した後、auth.mjs statusを実行してください。ByteRoverの認証を参照してください | | ログイン状態を確認（ローカルで確認し、ネットワークは使用しません） | node scripts/auth.mjs whoami — { ok, authed, providerKind }を出力します（認証情報がローカルに存在することを示します。サーバー側での有効性確認ではありません） | | ByteRoverからログアウト | node scripts/logout.mjs | | このフォルダーが使用するスペースを確認 | node scripts/space.mjs current | | スペースを一覧表示（team_nameごとにグループ化） | node scripts/space.mjs list | | このフォルダーをスペースにバインド | node scripts/space.mjs bind "<name>" |

トピックを削除する場合は、ユーザーに依頼を伝えてください。削除はByteRoverデスクトップアプリから行います。

すべてのコマンドはJSONの結果を出力します。{ "ok": false, ... }が返された場合は、troubleshooting.mdを参照してください。

取得したメモリの引用

query の回答が返されたヒットを実質的に利用した場合は、query エンベロープの citation_block を回答に追加して、ユーザーが何を利用したのか確認し、リンク先を開けるようにしてください。エンジンがブロックをあらかじめ整形しているため、あなたが判断するのは引用するかどうかだけで、整形は不要です。

query エンベロープの should_cite: true で、かつ回答が取得したメモリを実際に利用している場合：

1. 回答の後に空行を 1 行入れます。
2. citation_block 文字列を一字一句そのまま出力します。タイトルを囲む […](…) の Markdown リンク、存在する場合はインデントされた "snippet" 行、存在する場合は Updated by <agent> · <relative> の末尾行も含めます。エンジンが対象とするすべてのホスト（Codex CLI、Claude Code CLI、Claude Code Desktop）で、リンクで囲まれたタイトルがクリック可能なインラインリンクとして表示されます。
3. 引用の形式を変更したり、言い換えたり、エージェントが生成した関連性スコアを追加したりしないでください。関連性はタイトルを見てユーザーが判断します。
4. Markdown リンクをリンクなしのテキストに変換しないでください。 エンジンが意図的に - [Title · Recalled N×](http://…) を出力しています。これを URL を別の行に置いたタイトルだけの形式に書き換えると、長い URL をクリック可能なテキストの背後に隠す書式が損なわれます。スニペット行と更新者行も同様です。エンジンが出力したとおりにインデントを保ち、タイトル行に結合したり、先頭の空白を削除したりしないでください。

should_cite が false の場合、取得したヒットを回答に実際には利用していない場合、またはユーザーがソースを求めていない場合は、ブロック全体を省略します。 エンジンは信頼度の低い取得結果を意図的に抑制しています。文章内で補って提示しないでください。

回答の形式例（📚 … ブロックはエンジンから提供されるため、そのまま出力してください）：

ATM: Er Rak Error is a 2012 Thai romantic comedy by Mez Tharatorn …

📚 From ByteRover:
- [ATM: Er Rak Error (2012 Thai film) (fact)  ·  Recalled 14×](http://127.0.0.1:<port>/i/topic/<space-id>/context-tree/movies/atm_er_rak_error.html#bve-a1b2c3d4)
    "matched-context preview that explains why this hit ranked here"
    Updated by claude · 3d ago
- [Pee Mak Phra Khanong (2013) (highlights)](http://127.0.0.1:<port>/i/topic/<space-id>/context-tree/movies/pee_mak_phra_khanong.html#bve-e5f6g7h8,k1m2n3p4)

ByteRover で認証する

ユーザーがこのワークスペースで ByteRover の認証／ログイン／サインイン／接続／リンクを希望する場合（または ByteRover からセッションの有効期限が切れたと通知された場合）に実行します：

node scripts/auth.mjs

これはバックグラウンドプロセスが承認を待つ間、{ "ok": true, "pending": true, "verifyUrl": …, "userCode": …, "expiresInS": … } を直ちに返します。verifyUrl とコードをそのままユーザーに伝え、コードの有効期間（expiresInS。通常は数分間）を知らせ、ブラウザーで承認したら戻ってきて「approved」と伝えるよう案内してください。そこでターンを終了し、待機中にポーリングしたりコマンドを再実行したりしないでください。

ユーザーが戻ってきたら、次のコマンドで確認します：

node scripts/auth.mjs status

• { "state": "approved" } → 接続済みです。ユーザーに伝えます。
• { "state": "pending" } → まだ完了していません。ブラウザーでの手続きを完了するよう依頼し（結果に verifyUrl が再度含まれます）、もう一度案内します。
• { "state": "expired" } → コードの有効期限が切れています。node scripts/auth.mjs を再実行して新しいコードを発行し、ユーザーに再度伝えます。
• { "state": "denied" } → ユーザーが拒否しました。そこで終了し、その旨を伝えます。

認証フローの保留中に auth.mjs を再実行しても安全です。同じコードが返され（"reused": true）、別のコードが発行されることはありません。シークレットがチャットに貼り付けられることはありません。短いコードだけが表示されます。ログアウト／サインアウトするには：

node scripts/logout.mjs

非対話型環境または CI 環境でのみ、ファイルから API キーを指定できます（会話に直接入力しないでください）：node scripts/auth.mjs --key-file <path>。承認されるまでフォアグラウンドで待機するブロッキング版は、スクリプトでの使用向けです（会話では使用しないでください）：node scripts/auth.mjs --wait。

認証は必須ではありません。すべてのコマンドは認証なしで動作します。認証によって可能になることについては sync.md を、auth.mjs が { "ok": false } を返す場合は troubleshooting.md を参照してください。

リッチなトピックの作成

トピックは4 つのセクションでレンダリングされます。この構造を念頭に置いて作成してください。各 <bv-*> 要素は 1 つのセクションに属します。レンダラーはセクション内の順序を無視しますが、ソースを読みやすく保つため、セクション順に出力してください。

セクション	要素	含まれる内容
## Reason（WHY）	<bv-reason>	このキュレーションの「理由」を 1～2 文で記述します。ほぼ必ず含めてください。
## Raw Concept（WHAT と HOW）	<bv-task>、<bv-changes>、<bv-files>、<bv-flow>、<bv-timestamp>、<bv-author>、<bv-pattern>	コンセプトそのもの：主題、変更内容、関連ファイル、プロセスフロー、日付、作成者、正規表現パターン。
## Narrative（EXPLANATION）	<bv-structure>、<bv-dependencies>、<bv-highlights>、<bv-rule>、<bv-examples>、<bv-diagram>	構造に関するドキュメント、依存関係、主なポイント、プロジェクトのルール、実例、保持する図。
## Facts（抽出データ）	<bv-fact>	個別の照会が可能な事実を要素ごとに 1 つ記述します。Narrative に属する内容の置き場にはしないでください。
Runbook（任意のセクション）	<bv-decision>、<bv-bug>+<bv-fix>（兄弟要素）	独立した Runbook の記録。

すべてのトピックには、必ず次の内容を含めてください。

1. キュレーションの WHY を説明する <bv-reason>。なぜ記録されたのかという背景がなければ、トピックは役に立ちません。
2. トピックの内容を説明する <bv-task>（1 文）。または、「task」が適さない場合は <h1> と導入部の <p>。
3. task 以外の Narrative または Raw Concept 要素を少なくとも 1 つ： <bv-changes> / <bv-files> / <bv-flow> / <bv-structure> / <bv-dependencies> / <bv-highlights> / <bv-decision> / <bv-bug> / <bv-fix>。<bv-fact> の兄弟要素だけで構成されたトピックは、トピックではなくプレースホルダーです。
4. <bv-timestamp>。内容に基準日がある場合は ISO 8601 形式で指定します。
5. 抽出した事実ごとに <bv-fact subject="snake_case" category="…" value="…">canonical statement</bv-fact> を指定します。subject は snake_case、category は personal / project / preference / convention / team / environment / other のいずれか、value には抽出した形式を指定します。また、本文には正規の自然言語による記述を入れます（ラベルではありません）。

実例 — 調査／プロフィール形式のトピック

エージェントが作成すべき形式を示します。このひな形をコピーして各欄を埋めてください。より単純な構造に作り替えないでください。

node scripts/record.mjs "movies/atm_er_rak_error" --html '
<bv-topic path="movies/atm_er_rak_error"
          title="ATM: Er Rak Error (2012 Thai film)"
          summary="GTH 2012 romantic comedy by Mez Tharatorn — secretly-dating bank employees bet their jobs on recovering money from a malfunctioning ATM."
          keywords="atm_er_rak_error,gth,thai_romcom,mez_tharatorn,2012"
          tags="film,thai,gth,romcom"
          related="@movies/pee_mak_phra_khanong.html">

  <bv-reason>
    Anchor topic for cross-references between Thai GTH romcoms; documents
    the studio box-office record holder before Pee Mak (2013).
  </bv-reason>

  <bv-task>Profile of ATM: Er Rak Error (2012) — credits, plot, awards, legacy.</bv-task>

  <bv-timestamp>2012-01-19</bv-timestamp>

  <bv-highlights>
    Premise: a bank no-fraternization policy forces a secret 5-year couple
    into a winner-keeps-the-job bet over money from a glitching ATM.
    Was GTH biggest hit until Pee Mak (2013) topped it.
  </bv-highlights>

  <bv-structure>
    <p>Credits:</p>
    <ul>
      <li><strong>Director:</strong> Mez Tharatorn</li>
      <li><strong>Writers:</strong> Mez Tharatorn, Aummaraporn Phandintong</li>
      <li><strong>Studio:</strong> GTH (GMM Tai Hub)</li>
    </ul>
    <p>Lead cast:</p>
    <ul>
      <li><strong>Sua:</strong> Ter Chantavit Dhanasevi</li>
      <li><strong>Jib:</strong> Ice Preechaya Pongthananikorn</li>
    </ul>
  </bv-structure>

  <bv-flow>
    Sua and Jib are bank staff who dated secretly for 5 years under the
    bank no-fraternization policy. An ATM glitches and dispenses 130,000
    baht. They bet: whoever recovers the money keeps their job. The
    sequence escalates into a chaotic showdown involving manager Pakorn,
    Sergeant Sam, and Sam pet crocodile Jack.
  </bv-flow>

  <bv-fact subject="release_date" category="project" value="2012-01-19">
    The film was released theatrically in Thailand on January 19, 2012.
  </bv-fact>

  <bv-fact subject="runtime_minutes" category="project" value="123">
    The film runs 123 minutes.
  </bv-fact>

  <bv-fact subject="box_office" category="project" value="150.11 million baht">
    The film grossed 150.11 million baht, reaching Thailand 7th highest-
    grossing film within four weeks of release.
  </bv-fact>

  <bv-fact subject="record_vs_pee_mak" category="project" value="GTH highest-grossing film until Pee Mak (2013)">
    ATM was GTH/GMM Tai Hub highest-grossing film until Pee Mak surpassed it in 2013.
  </bv-fact>

  <bv-changes>
    <li>2013-11-30 to 2014-02-08: TV sequel ATM 2: Koo ver Error Er Rak aired (21 episodes, One 31).</li>
    <li>Chinese-language remake released as Welcome to the Beartown.</li>
  </bv-changes>

</bv-topic>'

各要素が何を担うかに注意してください。

• <bv-reason> はキュレーションの WHY を担います。これを省略するのは作成時に最もよくある失敗です。省略しないでください。
• <bv-task> + <bv-timestamp> は WHAT と WHEN を担います。
• <bv-highlights> + <bv-flow> は HOW を担います（説明とプロセス）。
• <bv-structure> は、出演者／クレジット／ファイル構成などのグループ化されたリストを担います。<bv-fact> の兄弟要素を大量に並べる場所ではありません。<bv-fact> は、発売日、実行時間、興行収入、受賞歴など、個別に照会できる主張に使用してください。

出力仕様（必須ルール）

スキーマは柔軟なため、違反があってもライターは警告なしに受け入れます。しかし、以下のルールを無視した出力は評価が下がり、読みづらくなります。

• すべての属性値をダブルクォートで囲んでください。 シングルクォートは使いません。
• すべての属性名を小文字にしてください。
• パスの各セグメントは、単語をアンダースコアでつないだ snake_case にしてください： movies/atm_er_rak_error。ハイフンを使った movies/atm-er-rak-error は不可です。
• related= は、ファイルを指定する場合は @path.html、フォルダー／ドメインを指定する場合は @path（拡張子なし）を使います。@ のプレフィックスは必須です。
• コードフェンスで囲まないでください。 --html 引数は生の HTML です。最初の文字は <、末尾は </bv-topic> にしてください。``` や ```html は使いません。
• <bv-topic> に createdat、updatedat、id、importance、maturity、recency を設定しないでください。 最初の 3 つはライターがシステム側で付与します。最後の 3 つはサイドカーの実行時シグナルであり、LLM は設定しません。
• 19 種類の <bv-*> 語彙にない独自要素や、各要素のドキュメント化されたスキーマにない属性を作らないでください。

機密性 — 共有する事実に印を付けます

トピックは、full（すべて）、redacted （<bv-fact disclosure="public"> と構造を示す文章のみ）、metadata （内容を含まない不透明なカタログハンドル）の3つのビューで共有できます。共有する事実には disclosure="public" を付けてください。そうでない場合、事実はデフォルトで制限対象となり、redacted ビューから除外されます。

記述する際は、次の3つのルールに従ってください。

• <bv-fact> は、項目ごとの制限を設定する唯一の単位です。 トピックの title とすべての文章（<bv-structure>、<p>、<bv-flow>、 <bv-highlights> などの内部）は契約上公開されており、redacted ビューにもそのまま残ります。タイトルや文章に秘密を記載しないでください。秘密は <bv-fact> に移してください（その場合、デフォルトで制限対象になります）。
• disclosure がない場合や、スペルが間違っている場合は、制限対象として扱われます。 フェイルクローズ方式のため、誤記によって誤って公開されることはありませんが、誤って非表示になることはあります。スペルをよく確認してください。
• <bv-topic visibility> を指定しても、事実が公開されるわけではありません。 これは情報を示すラベルにすぎません。redacted ビューでは、トピックレベルのデフォルト値ではなく、各事実の disclosure 属性を参照します。

モデル全体、標準的な例、個々の事実を公開または制限対象にする際の指針については、vocabulary.mdを参照してください。

2種類の記録形式

• シンプル形式（--title --body） は、本文を1つの <bv-fact> で囲みます。トピックが本当に1つの事実だけで構成される場合（「OAuth 2.0 と PKCE を使用している」など）にのみ使用してください。それ以外の場合、このラッパー構造は適切ではありません。
• リッチ形式（--html） は、それ以外すべてに使用します。たとえば、プロフィールのダンプ、決定事項＋理由＋ルール＋事実、バグ＋修正手順書、調査メモなどです。

要素の全レジストリ、スキーマレベルの属性、規範となるアンチパターン一覧については、 vocabulary.mdを参照してください。コミット品質の記録に関する指針については、 record.mdを参照してください。

何をいつ読むか

• リポジトリを初めて使用する場合、またはプロジェクトのメモリが存在しない場合 → onboarding.md
• 取得する前 → query.md
• 知識を保存する前 → record.md
• 適切な <bv-*> 要素を選ぶとき → vocabulary.md
• 定期的なクリーンアップ／統合 → dream.md

注：トピックは HTML の <bv-*> であり、Markdown ではありません。scripts/*.mjs は @byterover/skill-runtime から pnpm build:skill によって生成されます。存在しない場合は、まずビルドしてください。