br8n

br8n — 頭のための git stash

サイト · インストール · 仕組み · pip install br8n

このブランチで何をしていたか、忘れてしまいます。br8nなら忘れません。 作業を中断された瞬間に考えていたこと（ブランチ、開いているファイル、差分、そして一行の 理由）を保存し、戻ってきたときに30秒で読み返せる再開カードとして表示します。コードはすでに保存されています。保存されていないのは、この部分です。調査によると、中断後に集中を取り戻すには約23分かかり （Gloria Mark、UC Irvine）、複雑なコードではさらに長くかかります。(現在、スナップショットは2つの方法で取得されます。インストール済みの post-commit フックによってコミットの境界で自動取得する方法と、/br8n:capture でオンデマンドに取得する方法です。継続的な監視は行いません。)

ほとんどのツールが記録するのは 状態（ファイル、レイアウト、Git の履歴）です。br8n が記録するのは 意図、つまり頭の中にある一行の仮説です。「JWT の検証で古いトークンがキャッシュされている。」 これこそが重要な違いです。

今使っているデバイスの枠を超えて、br8n は 持ち運び可能なナレッジエンジン です。記録したインサイトは検索可能なジャーナルに保存され、Claude Code、iOS コンパニオン、または HTTP に対応するあらゆるツールからアクセスできます。マシン間で同期、検索、共有できます（有料プラン、今後提供予定）。

主な機能

1. 記録 — 作業を切り替える前に考えを保存する

会議の前、ブランチの切り替え前、または一日の終わりに /br8n:capture を実行します。br8n は1秒でワークスペースのスナップショットを取り、「何に取り組んでいましたか？」を記録します。一行の仮説は、要となる項目です。

Before:                    Capture:                   After:
┌─────────────────┐    /br8n:capture          ┌──────────────────┐
│ Fixing bug in   │  ───► br8n asks:  ───►  │ Finding saved:   │
│ auth flow       │       "What were    │      │ • git diff       │
│ files: [3]      │       you doing?"   │      │ • open files     │
│ branch: fix-#42 │       Fixing auth   │      │ • cursor pos     │
└─────────────────┘       bug            │      │ • hypothesis     │
                                         └──────────────────┘
                                         (stored in KB)

記録したスナップショットは、検索可能なジャーナルに保存されます。スナップショットごとに仮説は1つ。付箋に書き留めるような内容です。

2. 再開 — 中断したところから戻る

br8n を開く（またはエディターにフォーカスする）と、再開カードがすぐに表示されます。

• 最後の仮説（見出し）
• 最近のスナップショット（ここに何回来ましたか？）
• カバレッジバンド（このナレッジはどれくらい新しいですか？）

╔════════════════════════════════════╗
║ br8n — Where were you?           ║
╠════════════════════════════════════╣
║ 📌 Fixing auth bug in login flow   ║
║                                    ║
║ Recent snapshots:                  ║
║   • 5 min ago: auth middleware     ║
║   • 12 min ago: jwt validation     ║
║   • 45 min ago: session storage    ║
║                                    ║
║ Coverage: ████░ (rich)             ║
╚════════════════════════════════════╝

Git のログを掘り下げる必要はありません。「さて、どこまでやったんだっけ？」と迷うこともありません。30秒で作業に戻れます。

3. 探索 — ナレッジの不足を補う

カバレッジが gap の場合（しばらく離れていた、またはブランチを切り替えた場合）、ワンクリックでウェブ調査のパイプラインが実行され、変更されたドキュメント、新しい課題、更新された依存関係などの最新コンテキストを取得して、セッションのナレッジベースに統合します。

Resume card says "coverage: gap"
         │
         ▼
┌─────────────────┐
│ [Explore Now]   │  ─► web search (changed deps, docs)
└─────────────────┘  ─► fetch + parse relevant sources
         │            ─► extract + embed findings
         ▼
Coverage updates to "rich" + new context appears in the card

週末の後や、チームメイトが大きな変更をマージした後に戻ってくるときに最適です。

---

br8n は Delapan をベースにした自己完結型のフォークで、そのプリミティブ（Findings、pgvector 検索、tap/preamble）をチャットから自動記録へと転用しています。

2つの使い方

Claude Code プラグイン（オンデマンド）

あらゆる Claude Code セッションからスラッシュコマンドを実行できます。

/br8n:pickup          →  Show the current repo/branch resume card
/br8n:capture         →  Save a snapshot right now
/br8n:search <q>      →  Ask a question, grounded in your session history
/br8n:explore <topic> →  Force the gap-fill pipeline

例：Claude Code のセッションで認証の問題をデバッグしているとします。/br8n:search "how did I set up JWT validation?" と入力すると、記録済みのスナップショットから回答が得られます。

iOS コンパニオン（外出先で閲覧）

ネイティブの SwiftUI アプリです。閲覧機能を中心に設計されています。Sign in with Apple でサインインし、リポジトリをまたいだアクティビティを確認して、スマートフォンから再開カードを読めます。同じ /v1/projects + /v1/resume + /v1/activity API を使用し、ユーザーごとに認証します（詳細は以下を参照）。

ナレッジエンジン：ポータブルでアクセスしやすい

キャプチャしたスナップショットは、検索可能なナレッジジャーナルになります。エンジンは同じコードから2つの階層で動作し、違いはデータの保存場所です。

階層	無料／ローカル	有料／クラウド
ストレージ	デバイス上のSQLite	ホスト型Supabase（pgvector）
アクセス	ループバックのみ（localhost:8002）	どこからでも（APIキーが必要）
サインイン	なし	GoTrue
データ	~/.br8n/brain.db	暗号化済み、RLSで保護
選択	BR8N_BACKEND=local	BR8N_BACKEND=cloud + 認証情報

どこからでもナレッジにアクセス：

Claude Code (local/cloud)     iOS companion (cloud)     Browser (cloud, future)
     │                              │                            │
     └──────────────┬───────────────┴───────────────────────┘
                    │
              br8n API
                    │
            ┌───────┴────────┐
            │                │
        SQLite          Supabase
      (local db)      (cloud db)

無料プランは1台のデバイスのみで、同期はありません。有料プランでは、Claude Code、iOSアプリ、またはHTTPに対応するあらゆるツールからアクセスできます。チーム共有とリポジトリ横断検索は、今後の実装として設計されています。

有料プランの価値であるマシン間同期、リポジトリ横断検索、キー管理、チーム共有は、まだ提供されていません。

使用例

例1：会議による中断

14:32 — Debugging auth middleware
        Open file: middleware.py, line 45
        Hypothesis: "JWT validation is caching stale tokens"
        
14:35 — [Meeting call]
        /br8n:capture → br8n saves the snapshot
        
15:47 — [Back from meeting]
        /br8n:pickup → resume card appears:
        "🔸 JWT validation is caching stale tokens"
        Recent context shown. No "where was I?" moment.

例2：ブランチ間でのコンテキスト切り替え

You're on fix/session-timeout, about to switch to main
    /br8n:capture → snapshot saved against this branch
    
Hours later, switch back:
    git checkout fix/session-timeout
    /br8n:pickup → resumes from that branch
    → shows the last hypothesis + snapshots

例3：Claude Codeでの使用

You're in a Claude Code session, ask a question:
    /br8n:search "how did I set up the JWT secret?"
    
Claude Code queries your captured session history
    and answers from your own notes/decisions.

---

クイックスタート

Claude Codeプラグインをインストールします。venvもパスの編集も不要です。プラグインのMCPサーバーは初回実行時に独自の環境をセットアップします。

/plugin marketplace add anthonysuherli/br8n
/plugin install br8n@br8n

セッションを再読み込みしてから、/br8n:pickup、/br8n:captureなどを使用します。無料／ローカルプランでは、データは~/.br8n/brain.dbに保存されます。

キーなしで使える機能： キャプチャと再開です。スナップショットは埋め込みなしで保存されるため、再開カード、仮説、スナップショットの履歴は、アカウントもキーもなく利用できます。

キーが必要な機能： セマンティック検索（/br8n:search）には埋め込み用のキーが必要です。AI_GATEWAY_API_KEYまたはOPENAI_API_KEYを使用します。探索／ギャップ補完パイプラインには、それに加えてウェブ検索用のTAVILY_API_KEYが必要です。

キーなしのセマンティック検索： ローカルプランでは、pip install 'br8n[local-embeddings]'を実行すると、APIキーなしでセマンティック検索を利用できます。デバイス上でONNXモデル（bge-small-en-v1.5、約130MB、torch不要、初回使用時に一度だけダウンロード）を実行します。/br8n:embeddingsを使うと、現在有効なプロバイダーを確認したり、プロバイダーを切り替えたりできます。キーなしで実行するpython -m br8n.vault.reindexは、テキストだけでなく実際のベクトルを再構築します。

異なるモデルのベクトルは比較できないため、br8nでは有効な埋め込み空間を1つだけ保持し、プロバイダーを変更すると再埋め込みを行います。また、プロバイダーが意図せず変わることもあります。APIキーのないシェルではローカルモデルが選ばれます。br8nはベクトルを黙って破棄することはありません。環境から推測された変更は、適用されるのではなく提案されます。/br8n:embeddings（および--check）で保留中の切り替えを確認でき、承認すると切り替わります。提案が保留中でも、キャプチャと検索はキーがない場合とまったく同じように動作します。何も壊れず、何も失われず、承認後にバックログが自動で再埋め込みされます。明示的に依頼した切り替えは、すぐに適用されます。

ローカルインストールの動作確認には、python -m br8n.api.main --checkを実行します。Pythonのバージョン、設定されているバックエンド階層、sqlite-vecが読み込まれるかどうか、DBパスに書き込み可能かどうか、埋め込みキーと探索キーが設定されているかどうかが報告されます。不足しているものは明示されます。

APIを直接実行する（任意）

無料／ローカル（SQLite、1台のデバイス）：

BR8N_BACKEND=local python -m br8n.api.main   # listens 127.0.0.1:8002

有料／クラウド（Supabase、どこからでもアクセス可能）：

BR8N_BACKEND=cloud uvicorn br8n.api.main:app --reload --port 8002

ソースから実行する（コントリビューター向け）

br8nを使うのではなく、br8n自体を開発する場合：

git clone https://github.com/anthonysuherli/br8n
cd br8n/backend
python3.11 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp .env.example .env

pip install br8nで通常のパッケージとしてインストールすることもでき、br8n-mcpとbr8n-serverのエントリーポイントもインストールされます。Claude Code内でbr8nを使用する場合は、引き続きプラグインマーケットプレイス経由の方法が推奨されます。

設定

デフォルトでは、ナレッジベースは project（git リポジトリ名）と kb （git ブランチ）をキーとして使用します。BR8N_DB_PATH（ローカル）でデータベースのパスを上書きするか、クラウドでは .env に Supabase の認証情報を設定します。

クラウドティアはマルチユーザー対応です。各リクエストには Supabase GoTrue JWT が含まれます。この JWT は、POST /v1/auth/apple を通じて Apple でサインインして取得します（Supabase が Apple トークンを検証し、ユーザーをプロビジョニングします）。また、POST /v1/auth/refresh でローテーションします。バックエンドは SUPABASE_JWT_SECRET を使用して JWT を検証し、すべての読み取り／書き込み（ファインディング および アクティビティグラフ）を、行レベルセキュリティによって呼び出し元自身の組織に制限します。BR8N_API_KEY は内部呼び出し元専用のサービスキーとして引き続き使用されます。ローカルティアでは認証は不要です（ループバックのみ、シングルユーザー）。

設計原則

• 状態より意図を重視 — 何をしたかだけでなく、その理由を記録します（仮説を見出しにします）
• 手間を最小限に — 1 つのコマンドですべてをチェックポイントに記録でき、入力フォームは不要です
• 記録範囲を限定 — 重要なタイミング（会議の前、ブランチの切り替え時、一日の終わり）でスナップショットを取得します
• コンテキストの切り替えに対応 — フォルダー、ブランチ、マシンをまたいで動作します
• 処理を妨げない — 記録は実行後に制御を返す方式で、スナップショットごとに <1s です

アーキテクチャと開発

以下については CLAUDE.md を参照してください。

• モジュール構成（br8n/ コアエンジン、フォーク構造）
• API サーフェス（/v1/capture、/v1/resume、/v1/explore、/v1/auth/apple）
• ストレージティア（SQLite と Supabase）
• MCP ツールとプラグインスキル

ステータス

• コアエンジン — 記録、再開、探索のパイプライン
• Claude Code プラグイン — スラッシュコマンド（/br8n:pickup など）
• iOS コンパニオン — ネイティブ SwiftUI の閲覧機能（プロジェクト、再開カード、アクティビティ）
• ストレージティア — 無料（SQLite）と有料（Supabase）を 1 つのコードベースで提供
• マルチユーザー対応のクラウド認証（バックエンド） — ユーザーごとの Supabase JWT テナンシー、組織ごとの分離、/v1/auth/apple と /v1/auth/refresh
• ⬜ Apple サインインのエンドツーエンド対応 — Fly.io へのデプロイ、Supabase の Apple プロバイダー、iOS の接続（設計済み、開発中）
• ⬜ マシン間の同期 — 設計済み、未リリース
• ⬜ チーム共有 — 設計済み、未リリース

ライセンス

br8n は MIT License のもとで公開されているオープンソースです。著作権表示を保持すれば、商用利用を含め、あらゆる用途に使用できます。

「br8n」は Anthony Suherli が使用する名称です。ライセンスの対象はコードであり、名称ではありません（TRADEMARKS.md を参照）。br8n は Delapan エンジンの自己完結型フォークです。Delapan 自体は別途ライセンスされており、この MIT ライセンスの適用対象ではありません。

貢献を歓迎します。貢献の受け入れ条件と提供条件を一致させるルール（inbound = outbound rule）に基づき、DCO サインオフが必要です。詳しくは CONTRIBUTING.md を参照してください。ガバナンス全般（セキュリティに関する開示、プライバシー、行動規範）については、LEGAL.md を参照してください。