GBrain 新手攻略 从零把 AI 代理接上你的第二大脑

GBrain · 新手攻略

从零把 AI 代理接上你的"第二大脑"

项目：github.com/garrytan/gbrain（Garry Tan / YC 出品，MIT 许可）
本攻略基准：v0.48.3.0（2026-09-06 发布，约 29.7k star）
适用对象：没用过 OpenClaw/Hermes、没用过 MCP、只会敲基本终端命令的新手

一句话看懂 GBrain

GBrain 是给 AI 代理用的"记忆 + 知识检索"后端。搜索工具给你 10 段原文碎片，GBrain 给你一个带引用、并且明说"大脑里还不知道什么"的答案。

想直接读？看完整篇只需 约 30 分钟；想立刻上手，跳到第 4 章路线 1，15 分钟、零 API key。

第 0 章先花 3 分钟搞清楚：GBrain 到底是什么

一句话：GBrain 是给 AI 代理用的"记忆 + 知识检索"后端。搜索工具给你 10 段原文碎片，GBrain 给你一个带引用、并且明说"大脑里还不知道什么"的答案。

它的产品定位可以拆成三块，理解了这三块，后面所有安装路线都不会晕：

Brain repo（大脑仓库）

一个普通的 git + Markdown 仓库，你的知识真正的"户口所在地"。系统真源（system of record）是这些 .md 文件，数据库只是索引；删掉 git 仓库，大脑就没了。

Engine（引擎）

存索引和检索用的数据库。两种：PGLite（本地嵌入式，2 秒启动，免 Docker 免服务器）/ Postgres + pgvector（Supabase 或自建）。个人大脑 ≤ ~5 万页用 PGLite 完全够。

MCP server（gbrain serve）

把大脑以工具形式接到 Claude Code / Codex / Cursor / ChatGPT 等客户端。CLI 和 MCP 共用同一套 contract-first operations，100+ 操作可暴露成工具。

Skills（技能包）

50+ 个 Markdown 写的"玩法说明书"，告诉代理什么时候查脑、什么时候写脑。技能是 markdown，不是硬编码逻辑。

它跟普通笔记软件的根本差别是两个东西：

  1. 合成层（synthesis）：gbrain think 会在检索结果上写一篇带引用的答案，并附"知识缺口"提示。
  2. 自动接线的知识图谱：每次写页面都会从 [[wiki/people/bob]] 这类引用里抽出类型化边（works_at / invested_in / attended…），零 LLM 调用。官方基准：240 页语料 P@5 49.1% / R@5 97.9%，比关掉图谱的变体高 +31.4 个百分点的 P@5。

作者的原始生产数据规模：155,795 页、24,589 人物、5,340 公司、66 个 cron 任务。你不需要一上来就这么大，但这就是"为什么要建大脑"的答案。

第 1 章⚠️ 第一个坑，必须先说

⚠️ 冒充包陷阱

npm 上那个叫 gbrain 的包跟这个项目毫无关系，是抢注的。绝对不要执行 npm install -g gbrain 或 bun add -g gbrain——你会装到别的东西，而且它可能把你的真二进制在 PATH 上遮蔽掉。

注意

网上有些中文教程（例如博客园那篇流传很广的《GBrain 项目详解》）写的 bun add -g gbrain 就是错的，那是 2026 年 4 月的旧版说明，别照抄。

唯一正确的安装来源（官方明确列了两条）：

bash 
# 方式 A（推荐）：从 GitHub 装
bun install -g github:garrytan/gbrain

# 方式 B（方式 A 报 postinstall 错时的兜底）：克隆后 bun link
git clone https://github.com/garrytan/gbrain.git ~/gbrain
cd ~/gbrain && bun install && bun link

如果你已经误装过 npm 版：npm uninstall -g gbrain / bun remove -g gbrain，再按上面重装。gbrain doctor 会检测出"被 npm 版遮蔽"这种状态并打印修复命令。

还有一个新手常见的版本坑：锁 #latest-stable，不要每天跟 master 走：

bash 
bun install -g github:garrytan/gbrain#latest-stable

第 2 章我该走哪条路线？（决策表）

你的情况走哪条耗时成本章节
有 ChatGPT 订阅（用 Codex）或 Claude Code，想让代理变成一个有身份、有记忆、跨会话的常驻个人代理路线 1：bootstrap 粘贴块（官方推荐新手起点）~15 分钟0 额外（跑在你现有订阅上）第 4 章
只想在自己终端里手动玩转大脑，先感受一把路线 2：CLI standalone~10 分钟0第 5 章
主力是编码代理（Claude Code / Codex / Cursor），只想让它别"失忆"路线 3：给它挂个记忆层~5 分钟0第 6 章
想要"睡觉时也在给自己变聪明"的 24/7 全托管（服务器 + Telegram + Supabase）路线 4：OpenClaw/Hermes 全套~2 小时$100–150/月 起第 7 章

官方对成本路径的说明写得很直白：always-on 那条路"超出聊天订阅的成本量级"，先感受再上服务器。

我的建议

新手一律先走路线 1（15 分钟，零 API key），跑通了再决定要不要往路线 3 或 4 扩。下面按这个顺序写。

第 3 章第 0 步：环境准备（5 分钟）

3.1 装 Bun

GBrain 是 TypeScript + Bun 项目（仓库 97.7% TypeScript），运行时需要 Bun。

bash 
# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# 验证（关掉重开终端让 PATH 生效）
bun --version

3.2 装代理客户端（路线 1/3 需要）

  • Codex（官方首推，因为跑在你已有的 ChatGPT 订阅上，零 API key）：桌面版 ChatGPT App 里打开 Codex，或终端里装 codex CLI。
  • Claude Code：装好后终端里能敲 claude。
  • 检查方法：终端敲 codex --version / claude --version，能找到就行。README 里也提醒：如果 claude 找不到，得先装 Claude Code。

3.3 API key：哪些必要、哪些可选

这一步很多人被"要不要买 key"卡住，答案是：必要的一个都不需要。

Key不给会怎样给了多解锁什么
无（keyless）完全能跑：关键词检索 + 代理自己写的记忆—
VOYAGE_API_KEY向量检索与重排缺位官方默认组合：embedding voyage-4 + reranker rerank-2.5，一个 key 全覆盖，价格约为 OpenAI 嵌入的一半
OPENAI_API_KEY同上语义检索备选 + 自动事实抽取 + 对话模型
ANTHROPIC_API_KEY同上事实抽取 + 对话模型 + 查询扩展（提升搜索质量）

Key 放哪：环境变量，或 ~/.gbrain/config.json（init 也会读）；用 gbrain config set <KEY> <值> 写也行。

bash 
export VOYAGE_API_KEY=pa-...
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
提醒

ZEROENTROPY_API_KEY 已废弃，托管 API 于 2026-09-04 关停，别再用它做教程基准。

读回来看值：gbrain config get <key> 默认打码（任何含 key/secret/token/password 的键名打 ***，数据库 URL 的账号密码段也被替换），脚本要原值才加 --raw。这是防止 key 掉进 shell history 和代理转写里。

第 4 章路线 1（推荐）：15 分钟 bootstrap 一个常驻个人代理

这条路是官方给新手的默认门。你不需要自己敲安装命令——代理自己照着一份 runbook 把活干完。

4.1 步骤

  1. 新建一个空文件夹（重点：不是已有的代码项目！这个目录之后会变成你代理的私有 GitHub 仓库的本地工作区）。
  2. 在这个目录里打开 Codex（桌面 App 里 "open Codex on a folder"，或终端 codex）。Claude Code 同理。
  3. 粘贴下面这段（Codex 与 Claude Code 用的是同一个块）：
bootstrap 
Read and follow every step of:
https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/BOOTSTRAP_FOR_AGENTS.md
Goal: set yourself up as my persistent personal agent in this folder, with gbrain
as your memory. Interview me before writing any identity file — never invent
answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.
  1. 过程中 Codex/Claude 会弹命令批准——这是沙箱按设计工作，批准即可。
  2. 它会先面试你 6 个必填问题，然后才生成身份文件（SOUL.md / USER.md / MEMORY.md）——答案全部来自你的回答，绝不编造。认真答，这几份文件就是你代理的人格与背景。
  3. 它会创建本地 PGLite 大脑（2 秒，无服务器无 Docker）、接好 MCP、创建并校验一个私有 GitHub 仓库作为代理的持久躯体。
  4. 判断是否真装好：gbrain bootstrap verify 退出码为 0 才算完成。没到 0 就是没装完，别急着往下走。

4.2 想自己建仓库？可以，但有硬性条件

你不放心让代理替你建仓库的话：自己新建一个空的私有仓库，必须在你个人账号下（不要 org 仓库），不要 README/.gitignore/license，clone 下来，在这个 clone 里打开代理，粘贴同一段——bootstrap 会检测到并"收养"它而不是新建。

4.3 装好后必做的"见证奇迹"这一步（官方称为 the click moment）

这一步是理解整个产品的关键，务必亲手验一次：

  1. 告诉代理一件小事让它记住（例如"记住：我下周三要跟张三聊定价"）。
  2. 重启代理会话（把聊天上下文清空）。
  3. 新会话里问它回来。

答案只能来自大脑，不可能来自这次聊天——因为这次聊天的上下文已经被重启清掉了。这就是跨会话往返，"这才是整个产品"。（对比："我叫什么名字"是从身份文件答的，虽然也不错，但不是同一个把戏。）

4.4 装好后的两个认知要点

  • 你拥有大脑：每条记忆都是那个私有仓库里的 markdown 文件。可以读、可以 clone 到第二台机器、可以删掉——删了大脑就没了。
  • 第一个要跑的技能是 cold-start：对它说 "fill my brain"，代理会一步步（每步都要你同意）把你的 Gmail、日历、通讯录导进来。走原生连接器（gbrain google setup，token 存在 gbrain 本地凭据保险库里，代理根本不碰）、或走 ClawVisor 托管 OAuth 网关、或走 Google Takeout 离线归档。
官方的说法

空的大脑是个数据库，装满的大脑才是记忆。

第 5 章路线 2：纯 CLI，手动把大脑玩一遍（10 分钟）

想先脱离代理、自己搞清楚"数据是怎么进去又怎么出来的"，走这条。官方给的五连：

bash 
bun install -g github:garrytan/gbrain
gbrain init --pglite          # 2 秒，本地大脑（无 Docker、无服务器）
gbrain doctor                 # 体检，确认健康
gbrain import ~/notes/        # 把你已有的 markdown 目录索引进来
gbrain query "我的笔记里反复出现的主题是什么？"

5.1 init 时会发生什么（新手最容易懵的点）

  • gbrain init --pglite 会自动探测你环境里的 embedding provider：跑 init 之前就把 VOYAGE_API_KEY / OPENAI_API_KEY 之类的 env 设好，或者显式传 --embedding-model <provider>:<model>。同时设了多个 key 时，init 会弹交互式选择器（非 TTY 环境自动选 Voyage 默认）。
  • 一个 key 都没有：init 会继续，进 keyless 模式（只有关键词检索），并给一个很响的通知。之后想加语义检索：gbrain init --force --embedding-model voyage:voyage-4；或者一开始就想明确不要嵌入，传 --no-embedding。
  • Postgres 优先的阶梯（如果你想直接上 Postgres）：gbrain init --prefer-postgres，顺序是 env URL → Supabase token 发现 → 本地 Postgres → 可选 Docker → 兜底 PGLite。

5.2 两种查询方式，务必分清

这是 GBrain 与普通笔记检索工具的分水岭：

bash 
# 原始检索：返回按混合分排序的 top 页面，快，无 LLM 花费
gbrain search "谁在投后公司里做 AI 代理？"

# 大脑层：跑同样的检索，然后合成一篇带引用的答案 + 明说大脑还不知道什么
gbrain think "谁在投后公司里做 AI 代理？"
  • search = 你要粗看的原料（代理上下文、找某句原话、引用查证）。
  • think = 答案本体。多了"缺口分析"：哪一页过期了、哪条断言没引用、哪两页互相矛盾、哪里有洞该补。

日常习惯建议：先看 search，需要判断和整理时用 think。想看某结果为什么排第一：gbrain search "<query>" --explain，会打印每个阶段的加分来源（基础分、每种 boost 乘了多少）。

5.3 三种搜索模式（成本/质量的旋钮）

conservative / balanced / tokenmax 三种命名模式把一堆参数打包成一个配置键。要点：

  • 安装时的选择器默认给你 tokenmax（对 Haiku 级子代理或 keyless 场景它推荐 conservative）。
  • 没设 search.mode 的大脑在查询时解析为 balanced。
  • 交叉编码器重排：balanced 和 tokenmax 里开，conservative 里关；默认 Voyage rerank-2.5，没有 key 时按融合顺序 fail-open，gbrain search modes 和 gbrain doctor 会如实告诉你。
⚠️ 官方自己给的坑

tokenmax 的 LLM 多查询扩展在 k=5 上是有害的（LongMemEval 严格 recall_all@5 只有 54.89%，对比 balanced 的 93.19%）。小 k 召回别用 tokenmax。

gbrain think "<问题>" --with-calibration 这类进阶能力（用你的历史判断校准来反偏差）见第 9 章。

第 6 章路线 3：给编码代理装记忆（5 分钟，两条子路径）

场景：你主力用 Claude Code / Codex 写代码，它们对代码很强，但对"你上次会议决定了什么"完全失忆。GBrain 就是补这一层的。

6.1 路径 B：从零开始（本地大脑 + 本地代理）——新手选这个

三步，官方称"整个产品里摩擦最低的一条路"：

bash 
# B1 建本地大脑
gbrain init --pglite                  # 2 秒，WASM 里的嵌入式 Postgres，无 Docker

# B2 装点东西进去（很重要，空大脑答不出任何东西）
gbrain import ~/notes/                # 批量导入一个 markdown 目录
gbrain capture "决定：默认引擎用 PGLite，<1000 文件的场景零配置优先。"

# B3 接到代理
claude mcp add gbrain -- gbrain serve --surface verbs   # Claude Code
codex  mcp add gbrain -- gbrain serve --surface verbs   # Codex

无需 token、无需 URL、无需隧道：代理把 gbrain serve 当 stdio 子进程拉起，直连你的本地大脑。

--surface 是什么、为什么新手该加 verbs

surface暴露什么什么时候用
--surface verbs恰好 7 个记忆动词：recall / remember / entity / synthesize / forget / context_pack / delta（MEMORY_VERBS v1，冻结 + 只增不改）新手默认选这个，代理看到的是紧凑稳定的面，而不是 110 个工具墙
--surface starter7 动词 + 日常主力集（核心页面/搜索/图谱 + capture），约 27 个操作代理要干更多活时
省略 / --surface full全部 100+ 操作老手；注意默认值就是 full，老配置不受影响

B4 验证：在代理里说 "search my brain for PGLite"（或你刚 capture 的东西），能把页面拿回来就通了。同一个大脑也能从 CLI 查（gbrain query "..."）。

隐私默认

代理保存的记忆默认对整个大脑可见（每个连上的代理都能 recall）。只想本机/私有的事实，传 visibility: "private"。

6.2 路径 A：你已经有一个远程大脑

bash 
# A1 在主机上开 HTTP（两个 flag 最容易漏）
gbrain serve --http --bind 0.0.0.0 --public-url https://your-host.example.com
# A2 在主机上铸 token
gbrain auth create "laptop-agents"
# A3 在笔记本上一条命令接一个代理（--install 会顺手冒烟测试 token）
gbrain connect https://your-host.example.com/mcp --token gbrain_xxx --install
gbrain connect https://your-host.example.com/mcp --token gbrain_xxx --agent codex --install

三个必看的坑：

  1. --bind 0.0.0.0 不能省：默认只绑 127.0.0.1，会静默拒绝所有远程连接。"代理连不上大脑"八成是这个。
  2. Skills: not published：启动横幅里这行若是 not published，连上来的代理能搜能写但看不到你的技能目录。修：gbrain config set mcp.publish_skills true（gbrain init 会写这个键；缺这个键的大脑会一直 OFF，这是 OpenClaw 用户最常见的那个坑）。
  3. token 是长期全访问密钥，当密码对待；云上托管优先用带 scope 的 OAuth client。Codex 在运行时从 $GBRAIN_REMOTE_TOKEN 读 bearer，所以 token 不会掉进 Codex 配置文件——你得把这个变量一直导出在 shell profile 里。

6.3 装好之后：把"大脑优先协议"贴进代理指令

连接只是简单部分，价值来自教代理几个习惯。官方给了一段可直接粘进 CLAUDE.md（Claude Code）/ AGENTS.md（Codex、Cursor 等）的协议：

markdown 
## Brain-first protocol

你通过 MCP 接了一个知识大脑。回答任何关于人、公司、决策、项目或过往上下文的问题之前：

1. **大脑优先——按问题的形状路由。** 精确名字/已知 token → `search`（便宜的混合检索，无扩展）。
   概念、版图、"所有做 Y 的 X"类问题 → 先 `query`——它能找回 `search` 漏掉的同义表述，
   而 `search` 有结果并不等于覆盖完整。在 verbs 面上这个分工是 `recall`（取回）vs `synthesize`（推理作答）。
   在凭记忆回答或问我之前，先查大脑。绝不要在没查脑前先问"X 是谁""关于 Y 我们定了什么"。
2. **写回去。** 当我做了决策、提到新的人/公司、或落下值得留的想法，写进大脑：
   verbs 面用 `remember`（单条事实，带出处），full 面用 `put_page`（实体页放 people/、companies/；决策放 decisions/ 或 notes/）。
   一个洞见，一个页面，建立链接。
3. **引用。** 从大脑作答时，点名你用了哪一页。

配合四个值得照抄的模式：

  1. Brain-first lookup：代理问你"哪个仓库？谁负责这个？"之前先去搜。最高价值的一个习惯。
  2. Ambient capture：告诉代理"我们干活时，任何决策或新想法静默存进大脑，别打断我"。一个月后你就有几百个互相链接的页面。
  3. Briefing from your brain："下午 2 点跟 Acme 开会我需要知道什么"——拉会议史、相关人、未了结事项，以及"大脑还不知道的部分"。
  4. whoknows（专家路由）："我认识的人里谁在 Postgres 上做过限流器？"（find_experts，full 面），大脑里人数超过一小把之后就开始有用。

第 7 章路线 4：全托管 always-on（OpenClaw / Hermes，约 2 小时，$100–150/月）

这是"按设计意图使用 GBrain"：跑在你控制的服务器上的 24/7 cron、持续摄入、以及夜间的 dream cycle 在你睡觉时丰富大脑。也是最贵的一条。

7.1 官方给出的架构

Telegram→ AlphaClaw(harness)→ OpenClaw(agent)→ GBrain(knowledge/skills)→ Supabase(embeddings/search)

四个部件：大脑（git 仓库）/ harness（OpenClaw via AlphaClaw）/ 聊天入口（Telegram）/ 技能（50+）。

7.2 十步清单

前置：GitHub 账号、Render 账号、Telegram 账号、OpenAI + Anthropic key（至少）、$100–150/月预算。

  1. 建两个 GitHub 仓库（不是一个！）：workspace 仓库放代理配置/技能/记忆/cron；brain 仓库放知识内容。都私有，都从空开始。
  2. 生成 fine-grained PAT：只勾选这两个仓库，Contents/Metadata/Pull requests 读写权限。官方吐槽这是整个流程最痛的一段——建完仓库后可能要刷新页面它们才出现在选择器里。
  3. 建 Telegram bot：@BotFather → /newbot → 存 token。
  4. AlphaClaw 部署到 Render：填 workspace 仓库（不是 brain 仓库）+ PAT + bot token，deploy，首次约 5 分钟。内存是关键：基础档太小跑不动 GBrain + OpenClaw，Pro（约 $85/月）是最低可用。
  5. 填 provider key（AlphaClaw → Providers）：OpenAI、Anthropic 必填；Voyage 推荐（一个 key 同时管 embedding + rerank，价约 OpenAI 一半）；Perplexity 可选（网页搜索）。
  6. 装 GBrain（两个命令，分别落在不同仓库）：
    bash
    # 在 BRAIN 仓库里：
gbrain init --supabase
# 在 AGENT WORKSPACE 仓库里：
gbrain skillpack scaffold --all    # 把 50+ 内置技能作为一等文件拷进工作区，可自由编辑
  7. 配 Supabase，三个坑按顺序过（官方称"我踩过的硬跟头"）：
    • 7a 打开 pgvector：Dashboard → Database → Extensions → 打开 vector。忘了这步，schema 一建，每个 embed 写入都会报 type vector does not exist。UI 里 5 秒，漏了 debug 一小时。
    • 7b 用 Transaction Pooler 串，不是 Direct：Connect → Connection String 里有三条几乎一模一样的串。直连（5432，db.XXX.supabase.co）是 IPv6-only，Render 机器多半没 IPv6 出站会失败。用 6543 端口的 transaction pooler 串，GBrain 就是照它调的（会自动关掉 prepared statements，并把 migration/DDL/worker 锁路由到另一条直连）。配法：
      bash
      gbrain config set database_url "postgresql://postgres.YOUR-PROJECT:YOUR-PASSWORD@aws-0-us-west-1.pooler.supabase.com:6543/postgres"
    • 7c 修 DDL/worker 锁的 IPv4 问题：GBrain 会从 pooler 串推一条直连（host 换成 db.YOUR-PROJECT.supabase.co:5432），那是 IPv6-only。两种修法：免费——把直连指向 session pooler（同 host、5432、走 IPv4）：
      bash
      export GBRAIN_DIRECT_DATABASE_URL="postgresql://postgres.YOUR-PROJECT:YOUR-PASSWORD@aws-0-us-west-1.pooler.supabase.com:5432/postgres"
      付费——Supabase 加个约 $4/月的 IPv4 add-on（Pro 及以上，Project Settings → Add-ons → IPv4 address）。症状：gbrain doctor 报 network unreachable 或连接卡死，就是这两条都没做。
    • 7d 验证：gbrain doctor，看 schema / connectivity / pgvector / embedding provider 四项是否全绿。
  8. Telegram 里发消息验证：能带着上下文回答、能搜大脑，就上线了。
  9. 成本认知：Render Pro ~$85 + Supabase 免费到 $25 + OpenAI embeddings $5–20 + Anthropic $50–500，最低约 $100–150/月。官方还有一句给团队用的运营提醒：Supabase 通常是扩展瓶颈（不是 CPU 也不是 LLM 调用），大量摄入前早点升实例——小实例卡住的症状（静默失败的 insert、sync 超时、嵌入回填停住）看起来像三个不同的 bug，其实是同一个。
  10. OpenClaw / Hermes 的自动化安装路径：如果你已经有平台，直接向代理粘贴：
    text
    Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md
    代理会装 GBrain、建大脑、要你的 API key、加载 50+ 技能、配置 dream cycle、并做端到端验证。约 30 分钟。

第 8 章把数据灌进大脑（这一章决定你好不好用）

再强调一次：空大脑只是数据库。官方反复强调的第一个动作就是 cold-start。

8.1 随手记：capture

bash 
gbrain capture "此刻想记住的一句话"
gbrain capture --file ./notes/today.md
echo "管道内容" | gbrain capture --stdin
SLUG=$(gbrain capture "..." --quiet)

一次动作同时落库 + 落盘。默认 slug 形如 inbox/YYYY-MM-DD-<hash8>，方便你在一个可预测的位置集中分流。thin-client 安装下这个动词会通过 MCP 路由到服务器，命令和体验一致。

对代理说："Remember this: …" / "存进我的大脑" / "Capture this."

8.2 一次性导入已有笔记

bash 
gbrain import ~/my-knowledge          # 批量导入一个目录
gbrain sync --watch                   # 实时同步一个 git 仓库（autopilot 模式）

旧笔记迁移（Obsidian/Notion/Logseq/Roam/CSV/JSON）有专门的 migrate 技能；Obsidian 风格跨目录裸 [[note-name]] 链接可以按 basename 解析：gbrain config set link_resolution.global_basename true（默认关，gbrain doctor 会先告诉你开了能多几条边再决定）。

8.3 Gmail / 日历 / 通讯录（原生连接器）

bash 
gbrain google setup     # 连 Gmail/Calendar/Contacts → 首次同步 → 首份摘要
gbrain waiting          # 谁在等你、你答应了什么，附收据
gbrain google calendars # 列出账号能读的所有日历；传 id 给 sources add --calendar-id 同步次级日历
gbrain loops mute sender <email>     # 不再为某个发件人开环
gbrain loops unmute sender <email>   # 撤销，精确且只向前

gbrain google setup 走"自带 OAuth"全流程：你自己的免费 Google Cloud 客户端，你拥有这个 app，token 只存在本地凭据保险库，代理从不持有。

对代理说："Who is waiting on me?" / "open loops" / "列出我的 Google 账号能读的日历"。

8.4 把你和其他代理的对话史倒进来

bash 
gbrain transcripts ingest                     # 发现可导入的会话日志
gbrain transcripts ingest --all               # 全部导入
gbrain transcripts ingest ~/Downloads/conversations.json   # ChatGPT/Claude.ai 消费端导出（先解压）
gbrain transcripts status                     # 每个 harness 的 found vs imported

支持 Claude Code / Codex / OpenClaw / Hermes / Grok Build 的会话日志，以及 ChatGPT / Claude.ai 的 conversations.json。要点：密钥在写入前从正文/标题/说话人/session metadata 里 scrub 掉；bulk backfill 默认关嵌入；重跑免费（内容 hash 不变就跳过）。

8.5 持续同步 ChatGPT / Claude 历史

bash 
gbrain connectors auth chatgpt --cookie -             # 粘 Cookie 头（走 stdin，别让它进 argv）
gbrain connectors sync chatgpt --dry-run              # 预览 → 然后 --limit 5 → 然后 --full
gbrain config set connectors.chatgpt.auto_sync true   # 选入每日自动同步（配合 gbrain autopilot --install）

凭据只留在本机（~/.gbrain/connectors/*.json，权限 0600），且只发给对应厂商自己的主机。

别把方向搞混

Connectors（入站）是把 gbrain 作为 MCP 连接器装进 ChatGPT/Claude/Perplexity，让那边能搜你的大脑；gbrain connectors 是反方向，把对话史从那些账号拉进大脑。

8.6 Webhook / 移动端

bash 
curl -X POST https://your-brain/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/markdown" \
  -d "# 来自一个 Shortcut 的想法"

移动端：inbox folder source 会捡任何丢进 ~/.gbrain/inbox/ 的东西（iOS Shortcuts / AirDrop / Drafts / Finder）。

第 9 章让大脑自己在夜里变锋利

官方哲学的原话："造一个 24/7 跑的 daemon 去摄入、丰富、巩固，比让代理在聊天里一直加班要容易。"

核心循环（六拍）：

signal→ search→ respond→ write→ auto-link→ sync
  • signal detector：代理收到的每条消息都跑，捕获想法、实体提及、限时待办、名字、链接。
  • brain-first lookup：任何外部 API 调用之前先查大脑——它是你最便宜、最快、最私人的信息源。
  • auto-link：每次写入都触发，纯模式匹配 [[wiki/people/bob]]，无 LLM；新实体 → 新页面 stub → 图谱长大。
  • cron 驱动的丰富：你睡觉时跑去重人物页、修引用、算 salience、找矛盾、准备明天的任务。

新手要动的开关只有两个：

bash 
gbrain autopilot --install      # 后台 daemon，夜间丰富
gbrain dream                    # 手动跑一次 dream cycle

对代理说的活术："Set up autopilot" / "Run dream" / "Did the dream cycle run?"

9.1 ambient memory writeback（可选，个人大脑）

开启后，你随口说出的偏好、决策、承诺会被代理自动存成带出处的持久事实，临时事实（感冒、行程）会自己到期。默认关闭；个人大脑在 init/升级时会被问一次，公司大脑永不弹这个提示。

对代理说："Turn on ambient memory writeback"——它会跑 gbrain config set memory.auto_writeback salient 和 gbrain bootstrap harness --yes。

9.2 schema pack：大脑的形状

大多数笔记工具只有一种固定布局，GBrain 让你声明自己的形状。内置：

  • gbrain-base-v2（默认）：15 类 DRY/MECE 规范分类（14 个 canonical + note 兜底）：person company media tweet social-digest analysis atom concept source deal email slack writing project note。
  • gbrain-base（legacy，24 类，可升级：gbrain onboard --check --explain → 提交 unify-types job）。
  • gbrain-recommended：在 base 之上加 13 个目录（source/place/trip/conversation/personal/civic/project…），gbrain schema use gbrain-recommended 激活。
  • 你自己的 pack：schema detect 从你实际文件系统聚类出候选类型 → schema suggest 跑一轮 LLM 精炼 → schema review-candidates --apply 人工闸门提拔。三条命令，大脑就认识你的形状了。
bash 
gbrain schema active     # 当前跑哪个 pack，由哪一层解析出来的
gbrain schema list       # 内置 + 已安装
gbrain schema detect     # 从文件系统提议类型

为什么值得折腾：激活的 pack 会贯穿所有读写路径——parseMarkdown 按 pack 的路径前缀推页面类型；whoknows 只在声明 expert_routing: true 的类型上做专家路由；extract_facts 只在 extractable: true 的类型上跑。

9.3 calibration（判断校准）

代理会给你算 Brier 分数、总结"你在战术判断上很准、在宏观上平均晚 18 个月"这类模式陈述，并在你写高置信度论断时实时 nudge（14 天冷却）。gbrain calibration 看档案，gbrain calibration --regenerate 重算。

第 10 章新手日常命令速查（照抄就够用）

健康与自检

bash 
gbrain doctor                    # 全能体检；每个黄灯都印修复命令
gbrain bootstrap verify          # bootstrap 路线的完成判据（必须 exit 0）
gbrain engine status --probe     # 引擎是哪个、URL 从哪来、锁情况
gbrain models                    # 哪些模型被配去干哪些事
gbrain search modes              # 我在哪个搜索模式、reranker 到底在跑没有

写

bash 
gbrain capture "一句话"          # 最快入口
gbrain put / gbrain import 目录
gbrain tag / gbrain link / gbrain timeline-add

读

bash 
gbrain search "关键词"           # 原始检索
gbrain search "关键词" --explain # 看每条为什么排上来
gbrain query "语义问题"          # 混合 RRF + 扩展
gbrain think "需要推理的问题"    # 合成答案 + 引用 + 缺口
gbrain get people/alice
gbrain graph-query / gbrain backlinks / gbrain whoknows

运维

bash 
gbrain sync --watch
gbrain autopilot --install
gbrain dream
gbrain upgrade                   # 会跑 schema 迁移 + 升级后提示（只在 TTY 里跑）
gbrain db-repair                 # Postgres 连不上时的诊断→分级修复

第 11 章排障手册（新手命中率最高的十几种）

手机上左右滑动表格查看完整内容。

症状真因处方
装了个 gbrain 但行为完全不对 / 命令互相打架装到了 npm 抢注包npm uninstall -g gbrain；gbrain doctor 会指认遮蔽并给修复命令
bun install -g 报 postinstall 错某些环境 Bun 拦 postinstall hook按提示跑 gbrain doctor → gbrain apply-migrations --yes；兜底：clone + bun install && bun link
PGLite 启动崩 RuntimeError: Aborted()（常在 macOS 升级后）不是 macOS 不兼容——是升级重启把 gbrain 写一半打断、WAL 撕裂①默认自动修：跑任意命令即可（数据保留、留备份）②gbrain pglite-repair --dry-run → --yes ③gbrain reinit-pglite ④换引擎
gbrain import 报 expected N dimensions, not M嵌入模型/维度不匹配跑 gbrain doctor，它会打印确切修复命令（config set ... 或 gbrain embed --stale / migrate embeddings）。别删 ~/.gbrain
语义检索完全不工作压根没有 key / key 在 init 之后才设init 前把 VOYAGE_API_KEY 等设进 env 或 ~/.gbrain/config.json，或 gbrain init --force --embedding-model voyage:voyage-4
代理"连不上大脑"serve --http 只绑了 loopback带 --bind 0.0.0.0 重启
代理看不到技能目录mcp.publish_skills 没开gbrain config set mcp.publish_skills true
每 embed 写入都报 type vector does not existSupabase 的 pgvector 扩展没开Dashboard → Database → Extensions → 开 vector
读能过、但 migration 挂住 / worker 锁成孤儿（Supabase + Render）直连主机是 IPv6-only，你的机器只有 IPv4 出站GBRAIN_DIRECT_DATABASE_URL 指向 session pooler（免费），或买 Supabase IPv4 add-on（$4/月）
gbrain doctor 警告 default_source_local_pathdefault source 没有 local_path 且这个空指针确实在破坏 write-through（null 本身是合法拓扑，会报 ok）这是"改指针"不是"搬文件"：gbrain sources set-path default <path>，它会先打印旧值，并拒绝嵌进/吞掉别的 source 的树（exit 6，--force 绕过）
gbrain sync 在大脑上卡死不前进、CPU 高某个文件/某条正则卡住GBRAIN_SYNC_TRACE=1 gbrain sync --no-pull --no-embed --yes 看最后一行 begin import；或 gbrain sync --no-schema-pack --no-pull --no-embed --yes 跳过 schema pack；PGLite + 活的 serve 时 sync 会通过本地 IPC 交给锁持有者
每小时 cron sync 老超时单次全量太重换 per-source 循环 + timeout(1)：gbrain sync --break-lock --all --max-age 1800 然后逐个 timeout 600 gbrain sync --source "$src" --timeout 540。超时会以 partial 状态 exit 0、last_commit 不变，下次靠 content_hash 短路
gbrain brainstorm 返回 judge_failed: true，scored 0你在一个旧构建上gbrain upgrade 就是全部修复，无需改配置或跑迁移
gbrain reindex --markdown 之后 enrichment / auto / dream 标签全没了旧构建的删除行为gbrain upgrade：标签调和是只增不删。已知残留权衡：从 frontmatter 里删掉一个 tag，下次 sync 不会从 DB 删它
gbrain init --migrate-only / schema 迁移在 Windows 上 getaddrinfo ENOTFOUND每个 phase 都 spawn 子进程 gbrain init，子进程在 Windows+bun+Supabase pooler 下 DNS 解析失败gbrain upgrade（改为进程内分阶段执行，消灭 spawn）
空结果（路线 3 的 B 路径）大脑里真的什么都没有gbrain import ~/notes/ 或 gbrain capture "..."
unknown tool: capture你的 token 的 surface 被收窄，或主机版本过旧升级主机（capture 在 starter 和 full 面上）；收窄的 token 上改用 put_page，verbs 面上用 remember
Render 安装期 OOM实例太小升 Pro（$85/月），基础档跑不动
GitHub PAT 看不到仓库建仓库后页面没刷新刷新页面重来；确认 fine-grained token 的仓库选择

通用排障咒语：对代理说 "Run a brain health check and fix what you find" → 路由到 maintain 技能 → 跑 gbrain doctor → 要么自动修要么打印确切修复命令；也可以说 "Get my brain health score to 90" 用带成本上限的补救规划器。

11.1 升级时的专项注意事项

v0.48.3.0 有硬性提醒：已存在的搜索 chunk 需要重建之后远程 chunk 检索才会恢复；语义结果缓存临时禁用；存的矛盾报告和 code-inspection 工具有 local-only 限制。

官方给的对代理说法："Upgrade gbrain and check whether my search index needs rebuilding." 详细重建命令、嵌入成本与重建后仍存留的限制见 skills/migrations/v0.48.3.0.md。

另外：升级只在 TTY 下交互，非 TTY 会带着信息性 stderr 跳过提示。

第 12 章中文用户的三个额外注意点

这三条官方文档只给了零件，没给完整配方，所以本攻略明确标为"需要你自己验证"。

1. 关键词检索的分词语言

Postgres 全文检索的分词器由 GBRAIN_FTS_LANGUAGE 控制，默认 english；查询侧（websearch_to_tsquery）和写入侧（填 pages.search_vector / content_chunks.search_vector 的触发器）都尊重这个设置。可用配置列表：psql -c "SELECT cfgname FROM pg_ts_config"。改已过迁移的大脑用专门命令：

bash 
export GBRAIN_FTS_LANGUAGE=portuguese
gbrain reindex-search-vector --dry-run
gbrain reindex-search-vector --yes
中文没有空格分词

官方文档覆盖的是 portuguese / spanish / pt_br（unaccent + 词干）这类有空格分词的语言。中文没有空格分词，Postgres 内置配置里没有中文分词器，需要 zhparser / pg_jieba 一类扩展自建 text search config——官方 recipe 里没写。现实建议：中文大脑把语义检索当主力（务必配 embedding key），把 gbrain search 的关键词臂当补充，并亲自用 gbrain search diagnose "<query>" --target <slug> 追踪哪一层把页面捞出来（或漏掉）来验证效果。

2. embedding provider 的中文能力

默认是 Voyage voyage-4 @ 1024d，覆盖列表还包含 OpenAI / OpenRouter / Google Gemini / Azure / MiniMax / DashScope / Zhipu（智谱，中文友好）/ 本地 Ollama / 本地 llama-server / LiteLLM 代理——完整矩阵与决策树在 docs/integrations/embedding-providers.md。中文内容多，值得亲自对比国产/本地 provider 与 Voyage 的召回差。

3. reranker 的中文

重排默认 Voyage rerank-2.5（与嵌入同一个 key）；也有完全本地的方案 llama-server-reranker recipe（Qwen3-Reranker 权重跑在 llama.cpp 上）。不想让中文内容出机器时，这条路值得看。

第 13 章学习路径：按这个顺序读文档

官方给代理准备的入口是 AGENTS.md（非 Claude 代理）/ CLAUDE.md（Claude Code）；给 LLM 的地图是 llms.txt（目录）或 llms-full.txt（目录 + 核心文档内联，一次抓取）。人类新手推荐阅读顺序：

  1. README.md 的 Install 与 "Two ways to query" 两节
  2. skills/RESOLVER.md——短语手册。这是最重要的一份：一张"你说这句话 → 哪个技能被触发"的表。你不会按名字调用技能，你说意图，代理负责路由。
  3. docs/tutorials/connect-coding-agent.md（记忆层，两条路径 + 协议 + 4 个习惯）
  4. docs/guides/bootstrap.md（常驻个人代理契约：面试、身份文件、hooks、私有仓库、安全姿态、卸载）
  5. docs/GBRAIN_SKILLPACK.md（中文社区普遍标为必读的 playbook：两仓库架构、子代理模型路由、三种搜索模式、大脑记忆 vs 代理记忆三层）
  6. docs/GBRAIN_RECOMMENDED_SCHEMA.md（目录与页面格式规范：Compiled Truth + Append-only Timeline）
  7. 按需：docs/INSTALL.md、docs/mcp/*（每个客户端的具体接法）、docs/architecture/（拓扑与检索理论）、docs/guides/、docs/ethos/（thin harness, fat skills 的哲学与起源）

几个"对代理说"的样例（不用记命令，直接讲人话）：

"Ingest this PDF" / "What's happening today?" / "Fill my brain" / "Brain health" 或 "check backlinks" / "Is my brain set up right?" / "Did the restart break anything?" / "Run this as a background task" / 完全不确定就问 "What can my brain do?" 让代理把 resolver 读给你听。

想给项目贡献代码：bun run test（快循环）、bun run verify（pre-push 闸门）、bun run ci:local（完整 Docker 支撑的 CI）。社区 PR 走"批量成 wave 合入"而非逐个 merge，署名通过 Co-Authored-By: trailer 保留，CHANGELOG 里逐个致谢。

第 14 章你的第一周 Checklist

Day 1（30 分钟内做完）

  • 装 Bun，bun --version 有输出
  • 确认没有装过 npm 版 gbrain（装过就先卸）
  • 走路线 1 或路线 2：gbrain init --pglite 建本地大脑
  • gbrain doctor 全绿（黄灯就读它的修复命令）
  • gbrain capture 记 3 条你自己知道的判断
  • gbrain search 和 gbrain think 各问一次，亲手感受"检索"和"答案"的差别

Day 2

  • gbrain import 把你已有笔记的一个目录灌进来
  • 跑一次"click moment"验证：记一件事 → 重启代理 → 要回来
  • 把 brain-first 协议粘进 CLAUDE.md / AGENTS.md

Day 3–4

  • 说 "fill my brain" 跑 cold-start（选一个数据源即可：Gmail 或日历或通讯录）
  • 决定并确认 search.mode：gbrain search modes 看一眼；需要小 k 高召回时别用 tokenmax
  • gbrain schema active 看当前 pack；形状不对就 schema detect → suggest → review-candidates

Day 5–7

  • 开 autopilot：gbrain autopilot --install，然后 gbrain dream 手动跑一次并问 "Did the dream cycle run?"
  • 决定要不要开 ambient memory writeback（记住默认：写入的记忆是大脑范围内可见的）
  • 每周例行：gbrain doctor（含 batch_retry_health / graph_signals_coverage 这些专项检查）
要花钱再做的

路线 4（Render + Supabase + Telegram），预算 $100–150/月，先看第 7 章那三个 Supabase 坑。

附录 A值得知道的几个进阶能力

  • Minions 任务队列：BullMQ 形状、Postgres 原生的队列。崩溃可恢复的 durable 子代理（pending→done 两阶段持久化）、shell 任务带审计、级联超时子任务、出站 provider 的速率租约、附件走 S3/Supabase。可选 per-job 进程隔离（gbrain jobs work --job-isolation process），卡住的 handler 能被真 SIGKILL。
  • 评测框架：gbrain eval longmemeval（公开 LongMemEval 基准）、gbrain eval brainbench（跨 harness 记忆一致性：know-to-ask / push 精确率召回率 / write-back 保真 / 跨会话连续性，默认密闭、无 key、秒级）、gbrain eval retrieval-quality（NamedThingBench 硬闸门）、gbrain eval suspected-contradictions（大脑一致性，接入夜间 dream）。
  • HTTP server 的管理面：gbrain serve --http 自带 /admin SPA、/admin/events SSE 活动流、DCR 式客户端注册、read / write / admin 分级 scope、限流。部署文档覆盖 ngrok / Railway / Fly.io。
  • 多大脑区分：gbrain config set mcp.instructions "Team wiki brain — 产品/路线图问题路由到这里"，会随每次 initialize 响应带上 Deployment identity: 横幅，让接进来的代理分辨哪个是哪个大脑；重启 gbrain serve 生效，GBRAIN_MCP_INSTRUCTIONS 按进程覆盖。
  • gbrain agent run "..."：通过 Minions 队列把同一套表面暴露给子代理，崩溃安全持久。
  • 第三方 skillpack 注册表：gbrain skillpack init/pack/doctor/search/info/scaffold，10 维度质量标尺（5 必须核心 + 5 徽章 → 决定 tier 资格），确定性 tarball + TOFU 信任记录。
  • Memorable（程序性记忆，可选，默认关）：把干完的会话变成可回放的 procedure，下次类似任务 memorable recall "..." 直接复用。闭合源的第三方 npm CLI，需要你自己的知情同意：gbrain config set integrations.memorable.enabled true 这一步必须由你交互确认，relay 在此之前保持关闭；GBRAIN_MEMORABLE=0 可一键全杀。开之前请读"the fine print"。

附录 B链接清单

  • 仓库：github.com/garrytan/gbrain
  • 文档地图（给 LLM）：llms.txt / llms-full.txt
  • 代理入口：AGENTS.md / CLAUDE.md / BOOTSTRAP_FOR_AGENTS.md / INSTALL_FOR_AGENTS.md
  • 教程：docs/tutorials/personal-brain.md（全栈 2 小时）/ company-brain.md（团队 90 分钟）/ connect-coding-agent.md（记忆层）/ improving-skills-with-skillopt.md
  • 评测仓库（BrainBench 记分卡）：github.com/garrytan/gbrain-evals
  • 中文解读（注意其中有已过时的安装命令）：博客园《GBrain 项目详解》、知乎《6.9k Star！YC 总裁开源智能体知识记忆系统 GBrain》
  • 作者本人的安装推文（早期 OpenClaw 版本流程，仅作背景理解）：x.com/garrytan