br8n

br8n — 给大脑用的 git stash

网站 · 安装 · 工作原理 · pip install br8n

你会忘记这个分支是做什么的，但 br8n 不会。 它会保存你被打断时的思路——分支、打开的文件、差异，以及一句话的原因——并在你回来时用一张 30 秒就能看完的恢复卡片呈现出来。代码已经保存好了；没保存的是这些内容。研究表明，打断后重新集中注意力的代价约为 23 分钟 （Gloria Mark，UC Irvine），处理复杂代码时则需要更久。（目前通过两种方式创建快照：在提交边界通过已安装的 post-commit 钩子自动创建，以及通过 /br8n:capture 按需创建。没有持续运行的监视器。）

大多数工具会捕获状态（文件、布局、Git 历史）。br8n 捕获的是意图——你脑海中的一句话假设：“JWT 验证正在缓存过期令牌。”这才是关键。

除了当前设备之外，br8n 还是一个便携式知识引擎：捕获的见解会保存在可搜索的日志中，你可以通过 Claude Code、iOS 配套应用或任何支持 HTTP 的工具访问。跨设备同步、搜索和分享（付费层级，未来推出）。

核心功能

1. 捕获 — 切换离开前保存你的思路

开会前、切换分支前或一天结束时，运行 /br8n:capture。br8n 会在一秒内为你的工作区创建快照，并记录“你刚才在做什么？”——那句承载核心信息的一句话假设。

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)

捕获的快照会保存在可搜索的日志中。每个快照记录一个假设——也就是你会写在便利贴上的那件事。

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）从聊天场景改造为自动捕获。

两种使用方式

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 应用——阅读主界面。使用 Apple 登录，浏览跨仓库活动，并在手机上阅读恢复卡片。使用相同的 /v1/projects + /v1/resume + /v1/activity API，并按用户进行身份验证（见下文）。

知识引擎：便携且易于访问

你捕获的快照构成了一本可搜索的知识日志。引擎使用同一套代码分为两种层级运行——区别在于数据存储的位置。

层级	免费 / 本地	付费 / 云端
存储	设备上的 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)

免费层：单台设备，不支持同步。付费层：可从 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 只保留一个启用的嵌入空间，并会在你更换提供方时重新生成嵌入。由于提供方也可能意外改变——例如，未配置 API 密钥的 shell 会使用本地模型——br8n 不会静默丢弃你的向量：根据环境推断出的变更只会提供给你确认，不会直接应用。/br8n:embeddings（以及 --check）会报告待处理的切换，确认后才会执行。在等待确认期间，捕获和搜索的行为与完全没有密钥时一样：不会出错，也不会丢失任何内容；确认后，积压内容会自动重新生成嵌入。你明确请求的切换则会立即应用。

运行 python -m br8n.api.main --check，可对本地安装进行基本检查——它会报告 Python 版本、已配置的后端层级、sqlite-vec 是否能加载、数据库路径是否可写，以及嵌入和探索所需的密钥是否已配置。缺少的项目都会明确列出。

直接运行 API（可选）

免费 / 本地（SQLite，单台设备）：

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 本身，而不是使用它：

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——通过 POST /v1/auth/apple 使用 Sign in with Apple 获取（Supabase 会验证 Apple 令牌并为用户开通账户），并通过 POST /v1/auth/refresh 轮换。后端会使用 SUPABASE_JWT_SECRET 验证 JWT，并通过行级安全策略，将所有读取和写入（包括 findings 和活动图）限定在调用者所属的组织内。BR8N_API_KEY 仍作为仅供服务内部调用者使用的密钥。本地层无需身份验证（仅限环回访问，单用户）。

设计原则

• 意图优先于状态——记录原因，而不只是内容（假设是标题）
• 低摩擦——一条命令即可保存所有检查点；无需填写表单
• 有界捕获——在重要时刻进行快照（会议前、切换分支时、一天结束时）
• 适应上下文切换——可跨文件夹、分支和机器使用
• 绝不阻塞——捕获即发即忘；每次快照耗时 <1s

架构与开发

参见 CLAUDE.md，了解：

• 模块布局（br8n/ 核心引擎、fork 结构）
• API 接口（/v1/capture、/v1/resume、/v1/explore、/v1/auth/apple）
• 存储层级（SQLite 与 Supabase）
• MCP 工具和插件技能

状态

• 核心引擎——捕获、恢复和探索流水线
• Claude Code 插件——斜杠命令（/br8n:pickup 等）
• iOS 配套应用——原生 SwiftUI 读取界面（项目、恢复卡片、活动）
• 存储层级——同一代码库中提供免费版（SQLite）和付费版（Supabase）
• 多用户云端身份验证（后端）——基于用户的 Supabase JWT 租户机制、按组织隔离、/v1/auth/apple + /v1/auth/refresh
• ⬜ 端到端 Apple 登录——部署到 Fly.io + 配置 Supabase Apple 提供商 + 接入 iOS（已设计，进行中）
• ⬜ 跨机器同步——已设计，尚未发布
• ⬜ 团队共享——已设计，尚未发布

许可证

br8n 根据 MIT License 以开源形式发布——可用于任何用途， 包括商业用途，只要保留版权声明即可。

“br8n”是 Anthony Suherli 使用的名称；许可证涵盖代码，不涵盖名称（参见 TRADEMARKS.md）。br8n 是 Delapan 引擎的独立 fork；Delapan 本身采用单独的许可证，不受此 MIT 授权约束。

欢迎按照入站即出站规则提交贡献，并通过 DCO 签署—— 参见 CONTRIBUTING.md。完整的治理指南（安全问题披露、隐私、行为准则）请参见 LEGAL.md。