这是什么样子

假设你明天和 Alice 有个会议。你想走进去时记得她做什么工作、你们上次谈话是什么时候、以及你们之间还有什么未解决的问题。以下是你输入的内容，以及你得到的回复。

你问：

“明天和 Alice 开会前我需要知道什么？”

大多数个人知识工具会给你一个页面列表。 类似这样：

1. people/alice — Alice runs engineering at Acme...
2. meetings/2026-03-15-alice-q1 — Q1 product review with Alice...
3. meetings/2026-01-08-acme-kickoff — Kickoff meeting with Acme team...
4. customers/acme — Acme is a series-B fintech we work with...
5. notes/2026-04-22 — Quick chat with Alice about pricing...

五个你现在必须自己打开和阅读才能实际准备的页面。工具找到了正确的材料，但它没有做工作。

GBrain 给你答案，并附来源：

Alice runs engineering at Acme (a series-B fintech). You last spoke
on April 22 in a quick pricing chat. Three things are still open
from that conversation:

1. She owes you the security review for the new tier
   (deadline was May 1; no update since).
2. You committed to pricing for a 500-seat tier
   (you sent it April 25; no response yet).
3. She mentioned they're hiring a CISO; you said you'd intro
   someone from your network.

Heads up: nothing's been added to the brain about Alice or Acme
since April 22, six weeks ago. She may have replied through email
or Slack DM, channels the brain doesn't see. Worth asking her to
catch up before assuming any of this is still current.

每个声明背后都有一个来源页面。结尾的“提醒”告诉你大脑还不知道什么，这样你可以直接问 Alice，而不是感到意外。大脑刚刚完成了你的会议准备。

这就是搜索引擎和大脑之间的区别。搜索找到页面。大脑为你阅读它们并写出答案。

安装

[!WARNING] GBrain 不在 npm 上分发。 名为 gbrain 的 npm 包是一个无关的 包，与本项目没有任何联系。不要运行 npm install -g gbrain 或 bun add -g gbrain ——你会得到别的东西，它可能会遮蔽你 PATH 上的真实二进制文件。仅通过以下记录的路径安装和升级 (bun install -g github:garrytan/gbrain或 git clone + bun install && bun link)。 如果你已经错误地运行了 npm 安装： npm uninstall -g gbrain / bun remove -g gbrain，然后从 GitHub 重新安装。 gbrain doctor 检测到 遮蔽的 npm 安装并打印修复方法。

GBrain 设计为由 AI 代理安装和操作。GBrain 新手？从 Codex 开始——它在你已有的 ChatGPT 订阅上运行，约 15 分钟，不部署任何东西。已经生活在 Claude Code 中？其路径相同。想要 GBrain 以设计的方式运行——始终在线，全天候丰富你的大脑？那就是 OpenClaw 或 Hermes，需要真实的服务器 + API 成本。以下每条路径都是完整的。（想手动接线？跳到 CLI 独立 或 MCP 表。）

对于 Codex——推荐的第一步

将 Codex 变成你的持久个人代理。（只想要大脑 + 技能而不想要完整代理？ codex plugin marketplace add garrytan/gbrain@codex-plugin 然后 codex plugin add gbrain@gbrain ——参见 docs/mcp/CODEX.md。下面的粘贴块构建整个代理。）适用于 ChatGPT 桌面应用（在文件夹上打开 Codex）和 Codex CLI（在终端中codex ）——相同的安装，相同的结果。在一个新的空文件夹（不是现有代码项目）中打开 Codex——该文件夹将成为你的代理自己的私有 GitHub 仓库，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.

Codex 在安装过程中会请求命令批准——批准这些请求正是沙箱按预期工作的表现。大约 15 分钟后你将获得：一次简短访谈（6 个必答问题）→ 你的代理身份（SOUL.md、USER.md、MEMORY.md）完全根据你自己的回答生成，绝不凭空捏造 → 一个本地 PGLite 大脑（2 秒完成，无需服务器，无需 Docker）→ 接入 MCP，使每个会话都能搜索和写入记忆 → 一个私有 GitHub 仓库，已创建并通过隐私验证，作为你代理的持久载体。零 API 密钥即可运行——关键词搜索加上代理自行写入的记忆；一个可选密钥即可升级能力（OpenAI：语义搜索 + 自动事实提取；Voyage：语义搜索；Anthropic：事实提取）。Codex 每轮通过其工具读取大脑上下文（拉取式）。关键时刻：告诉它一件小事让它记住，重启 Codex，然后向它询问——答案来自大脑，而非本次聊天的上下文（重启已将其清空）。这种跨会话的往返正是整个产品的核心；"我的名字是什么 / 我的首要任务是什么？"这类问题从你的身份文件中得到回答，这很好，但并非同一回事。

运行起来后有两件事值得理解：你拥有大脑——每条记忆都是该私有仓库中的一个 markdown 文件（可读取、可克隆到第二台机器，删除后大脑即消失）——以及第一个要运行的技能是 cold-start：说"填充我的大脑"，你的代理就会导入你的 Gmail、日历和联系人——通过原生连接器（gbrain google setup，令牌存放在 gbrain 的本地凭据库中，代理从不持有），通过 ClawVisor（一个托管的 OAuth 网关），或从离线存档（如 Google Takeout）导入——一次一个经同意的步骤。空大脑是数据库；填满的大脑才是记忆。

更愿意自己创建仓库？ 在你自己的 GitHub 账户下新建一个空私有仓库（不要 README/.gitignore/license），克隆它，在 Codex 中打开该克隆，然后粘贴同一段代码——引导程序会检测到你的空仓库并采用它，而不是新建一个。仓库必须为空且归个人账户所有；组织拥有的仓库会被拒绝（在你的账户下创建一个，或让引导程序创建）。

对于 Claude Code——将其变成你的持久个人代理

适用于桌面应用和CLI（claude 在终端中）——相同的框架，相同的结果。在一个新的空文件夹（而非现有代码项目）中打开 Claude Code——该文件夹将成为你代理自己的私有 GitHub 仓库，已为你创建并通过隐私验证。然后粘贴同一段代码：

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.

Codex 路径的所有内容均适用——访谈、基于你自己回答的身份、本地大脑、私有仓库、无密钥模式——此外 Claude Code 还获得每轮上下文钩子（默认开启，可选择退出）：你的大脑自动加载到每个提示中，你的工作按每轮节奏持久化到你的私有仓库（本地约 5 分钟防抖，云沙箱中每轮执行——这覆盖了 /exit 框架从不触发会话结束钩子的情况），如果推送失败，下一轮会收到通知。这在 Claude Code 云会话中同样有效，不仅限于你的笔记本电脑：当沙箱阻止 GitHub API 时，验证会回退到纯 git 协议，并且 gbrain bootstrap cloud-setup-script 会打印环境设置配方。关键时刻：告诉它一件小事让它记住，重启会话，然后向它询问——新会话没有聊天上下文，因此答案只能来自大脑。这种跨会话的往返正是整个产品的核心（"我的名字是什么？"从你的身份文件中得到回答——很好，但并非同一回事）。与 Codex 路径相同的两个后续步骤：你拥有大脑（私有仓库中的 markdown），以及 cold-start 是第一个要运行的技能——"填充我的大脑"导入你的邮件、日历和联系人（ClawVisor）或离线存档，一次一个经同意的步骤。完整契约、安全态势、云沙箱和卸载说明：docs/guides/bootstrap.md。

更愿意自己创建仓库？ 在你自己的 GitHub 账户下新建一个空私有仓库（不要 README/.gitignore/license），克隆它，在 Claude Code 中打开该克隆（CLI 或桌面应用的打开仓库流程），然后粘贴同一段代码——引导程序会采用你的空仓库，而不是新建一个。仓库必须为空且归个人账户所有；组织拥有的仓库会被拒绝。

对于 OpenClaw 或 Hermes——GBrain 的本意，始终在线

这是 GBrain 按设计用途使用的方式：一个服务器托管的代理，配备 24/7 定时任务、持续摄取，以及在你睡觉时丰富大脑的夜间梦境循环——无论你的笔记本电脑是否打开，你的代理都在工作。这也是成本最高的路径：一台部署的服务器（8GB+ 内存）加上随代理运行强度增长的原始 API 令牌用量，远超聊天订阅。如果你想从第一天起就获得完整体验，从这里开始；如果你想先感受一下，从上面的 Codex 开始。如果你还没有运行中的平台，两者均可一键部署：

• OpenClaw — 在 Render 上部署 AlphaClaw（一键，8GB+ 内存）
• Hermes — 在 Railway 上部署（一键）

然后将此粘贴到你的代理中：

Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md

代理会安装 GBrain、创建大脑、询问你的 API 密钥、加载 50+ 个捆绑技能、配置梦境循环，并端到端验证安装。约 30 分钟。你回答问题，它完成工作。

从未设置过 AI 代理平台？ 个人大脑教程 会带你走完整条路径——选择 OpenClaw 还是 Hermes、部署它、将其指向 INSTALL_FOR_AGENTS.md、获取 API 密钥，并验证第一次查询。如果以上任何内容对你来说是新的，请从这里开始。

更轻量的入门方式

只想为你的编码代理添加记忆——不需要身份，不需要仓库。 用两条命令启动一个本地大脑并连接它——零服务器、零令牌、零隧道。 --surface verbs 为你的代理提供七动词记忆协议（recall, remember, entity, synthesize, forget, context_pack, delta — MEMORY_VERBS v1，冻结且永久可扩展），而非完整的工具墙；为每个操作添加该标志：

gbrain init --pglite                                    # 2-second local brain (no Docker)
claude mcp add gbrain -- gbrain serve --surface verbs   # or: codex mcp add gbrain -- gbrain serve --surface verbs

如果找不到 claude ，请先安装 Claude Code——或使用 协议文档 中各框架的代码块。提醒：代理保存的记忆默认对大脑全局可见（所有连接的代理均可回忆）；传递 visibility: "private" 以保存仅本地的信息。

已在远程主机上拥有大脑（OpenClaw、Hermes 或任何 gbrain serve --http)？用一条命令将你的笔记本电脑代理指向它—— --install 会在交接前完成连接并对令牌进行冒烟测试：

gbrain connect https://your-host/mcp --token gbrain_xxx --install               # Claude Code
gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex --install # Codex

将整个代理工具链接入共享大脑？在脑主机上， gbrain agent register <name> --harness claude-code 会生成一个受限的 OAuth 客户端以及一个 30 天的令牌，并打印可直接粘贴的接线块——适用于日常驱动和写隔离的编码代理。 接入决策表说明了哪条路径适合。

仅将大脑安装到另一个编码代理中（Cursor、Claude Cowork，或任何能获取 URL 并运行 shell 命令的工具）——粘贴上面的 OpenClaw/Hermes 块（INSTALL_FOR_AGENTS.md)；它会安装大脑、技能和梦境循环，而不包含个人代理身份层。已在 Codex、Claude Code、Claude Cowork、Cursor 和 AlphaClaw 上测试。

→ 完整教程：为你的编码代理赋予记忆 —— 仅记忆路径的端到端流程，以及你粘贴到 CLAUDE.md / AGENTS.md 中的大脑优先协议，还有四个能真正改变你工作方式的习惯。

CLI 独立使用（无代理）

bun install -g github:garrytan/gbrain
gbrain init --pglite     # 2 seconds; no server, no Docker
gbrain doctor            # verify health
gbrain import ~/notes/   # index your markdown
gbrain query "what themes show up across my notes?"

Postgres 规模化、Supabase 和瘦客户端设置路径位于 docs/INSTALL.md。

将 GBrain 连接到你的 AI 客户端（MCP）

GBrain 将其 100 多项操作中的几乎所有操作都作为 MCP 工具暴露（stdio 和 HTTP；少数仅限本地的操作保留在 CLI 侧）——或者仅使用七个记忆动词，配合 --surface verbs。具体代码片段取决于你使用的客户端：

升级现有大脑： 现有搜索分块需要在远程分块检索恢复之前重建。语义结果缓存暂时禁用；存储的矛盾报告和代码检查工具具有仅限本地的限制。请遵循 升级恢复指南中的重建命令、嵌入成本以及重建后仍然存在的限制。 对你的代理说： "升级 gbrain 并检查我的搜索索引是否需要重建。"

• Claude Code — 插件： /plugin marketplace add garrytan/gbrain + /plugin install gbrain@gbrain （MCP + 技能；角色变体 gbrain-coding / gbrain-daily 安装精选子集——请只选择一个 gbrain 插件）。无市场技能： gbrain skillpack scaffold --harness claude-code 将角色精选的技能集复制到你的用户级技能目录，并带有尊重本地编辑的更新视角。或本地单行命令： claude mcp add gbrain -- gbrain serve （零服务器，零隧道）。仅使用承载令牌的远程连接： gbrain connect https://your-host/mcp --token gbrain_xxx 打印一个可粘贴的块（或 --install 进行接线并对令牌进行冒烟测试）。
• Codex — 插件（推荐）： codex plugin marketplace add garrytan/gbrain@codex-plugin + codex plugin add gbrain@gbrain 安装 MCP 服务器和精选技能集。或仅连接： gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex （或 --install); Codex 在运行时从 $GBRAIN_REMOTE_TOKEN 读取承载令牌，因此令牌永远不会出现在 Codex 配置中。
• Cursor / Windsurf / 任何 stdio MCP 客户端 — 相同形式，将 {"command": "gbrain", "args": ["serve"]} 添加到你的 MCP 配置中。
• Hermes — printf 'Y\n' | hermes mcp add gbrain --env GBRAIN_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve. 将 --args 放在最后，并使用 hermes mcp test gbrain 进行验证（即使失败，add 也会以 0 退出）。
• Grok Build — grok mcp add gbrain -e "GBRAIN_HOME=$HOME" -- gbrain serve --surface verbs. 该 add 是惰性的（退出码为 0 而不连接）——使用 grok mcp doctor gbrain验证，它会启动服务器并报告 7 tools discovered。已针对 Grok Build v1.0.4 验证。
• opencode （opencode.ai / SST — 不是 OpenClaw） — opencode mcp add gbrain --env GBRAIN_HOME=$HOME -- gbrain serve --surface verbs，或让 gbrain bootstrap hooks --harness opencode 为你写入配置（opencode 是一个支持引导的工具链——它原生读取 AGENTS.md）。该 add 是惰性的——使用 opencode mcp list验证，它会启动服务器（✓ gbrain connected)。远程： gbrain connect https://your-host/mcp --token gbrain_xxx --agent opencode [--install] — 配置仅存储 {env:GBRAIN_REMOTE_TOKEN} 插值。已针对 opencode v1.18.18 验证。
• OpenClaw — ClawHub 捆绑插件会自动注册 gbrain（openclaw.plugin.json 随此仓库提供），或将 {"command": "gbrain", "args": ["serve"]} 添加到 ~/.openclaw/config.json的 mcpServers。
• Claude Desktop (Cowork) — 设置 → 集成 → 添加你的 HTTP 服务器 URL。仅限远程；本地 claude_desktop_config.json 不适用于远程服务器。
• Claude Cowork（团队计划） — 组织所有者需在组织设置 → 连接器下添加连接器。
• Perplexity Computer — gbrain connect https://your-host/mcp --agent perplexity --oauth --register 会生成一个最小权限的 OAuth 客户端，并打印 Issuer/Client ID/Secret 以粘贴到设置 → 连接器中（OAuth 是云连接器的正确路径；承载令牌也适用于本地使用）。需要 Pro 订阅。
• ChatGPT — 使用带有 PKCE 的 OAuth 2.1（硬性要求）。从管理仪表板注册一个 chatgpt 客户端，授权类型为 authorization_code。

对于 HTTP 服务器本身：

gbrain serve              # stdio MCP (local subprocess; for Claude Code, Cursor, Windsurf)
gbrain serve --http       # HTTP MCP with OAuth 2.1 + admin dashboard at /admin
                          # (required for Claude Desktop, Cowork, Perplexity, ChatGPT)

HTTP 服务器包括 DCR 风格的客户端注册、范围门控访问（read / write / admin)和速率限制。部署指南（ngrok、Railway、Fly.io）位于 docs/mcp/。

在一个工具目录后面运行多个大脑？为每个大脑赋予一个身份： gbrain config set mcp.instructions "Team wiki brain — route product and roadmap questions here" 在每个传输的 initialize 响应中携带一个 Deployment identity: 横幅，以便连接的代理能区分你的大脑。重启 gbrain serve 以生效；serve 进程环境中的 GBRAIN_MCP_INSTRUCTIONS 会覆盖该进程的设置，而 gbrain config unset mcp.instructions 则恢复为裸契约。对你的代理说： "告诉已连接的代理这是哪个大脑" — 你的代理会运行 gbrain config set mcp.instructions "<identity>"。

查询大脑的两种方式

原始检索（大多数个人知识工具提供的功能）和综合层，后者能给你一个实际答案。它们服务于不同的任务。

# raw retrieval: top pages by hybrid score, fast, no LLM cost
gbrain search "who's working on AI agents at portfolio companies?"

# brain layer: synthesized answer with citations and gap analysis
gbrain think "who's working on AI agents at portfolio companies?"

gbrain search 返回排名靠前的检索页面，按混合评分排序（向量 + 关键词 + RRF + 来源层级提升 + 重排序器）。当你想要原始材料进行浏览时使用它：代理上下文窗口、引用查找、寻找特定引文。

gbrain think 执行相同的检索，然后跨结果综合出一个带明确引用源页面的答案，并诚实说明大脑尚不知道的内容。差距分析是差异化所在：答案会告诉你页面何时过时、何时声明无引用、何时两个页面相互矛盾、何时存在你应该填补的空白。

对你的代理说： "我们对 acme-example 了解多少？" — "告诉我关于 alice-example 的情况，在我明天的会议之前" — "搜索谁在从事 AI 代理工作。" 你的代理会自动将这些路由到大脑；你永远不需要自己输入命令。

为何能形成复利。 将大脑层与 find_trajectory 配对，你就能得到类似 "公司的指标如何变化，团队现在是什么样，他们承诺/分享了什么，我们上次见面是什么时候，我能在这里提供什么增值" 的答案：评分良好、引用充分、一次搞定。这就是战略护城河。这就是为什么构建一个 15 万页的大脑值得付出努力。

gbrain agent run "..." 通过 Minions 队列向子代理暴露相同的界面，并具有崩溃安全的两阶段持久化。相同的答案，持久可靠。

如何导入数据

一条命令，本地或托管，同步接收：

gbrain capture "the thought I want to remember"
gbrain capture --file ./notes/today.md
echo "from a pipe" | gbrain capture --stdin
SLUG=$(gbrain capture "..." --quiet)

页面在一次操作中同时进入数据库和磁盘。默认 slug 为 inbox/YYYY-MM-DD-<hash8> ，因此捕获内容会聚集在可预测的分类位置。在瘦客户端安装中，该动词通过 MCP 路由到服务器：相同的命令，相同的用户体验。

对你的代理说： "记住这个：..." — "把这个想法保存到我的大脑" — "捕获这个。" 要从你现有的生活中填满一个空大脑："填满我的大脑"（冷启动技能会逐步征得同意，遍历你的电子邮件、日历、联系人和存档）。

环境记忆回写（可选加入，个人大脑）。 无需再说"记住这个"：一旦启用，你的代理会保存你随口说出的持久事实——偏好、决定、承诺——并带有来源，而临时事实（如感冒、旅行）会自动过期。默认关闭；在个人大脑上，gbrain 会在初始化/升级时询问你一次；公司大脑永远不会被提示。对你的代理说： "开启环境记忆回写" — 你的代理会运行 gbrain config set memory.auto_writeback salient 和 gbrain bootstrap harness --yes。完整机制、隐私立场和每个工具的限制：docs/guides/ambient-writeback.md。

对于 Webhook 摄取（Zapier / IFTTT / Apple Shortcuts）：

curl -X POST https://your-brain/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: text/markdown" \
  -d "# a thought from a Shortcut"

对于移动端捕获，收件箱文件夹源会拾取放入 ~/.gbrain/inbox/ 中的任何内容，来自 iOS 快捷指令 / AirDrop / Drafts / Finder。

你的 Gmail、日历和联系人会原生同步。 gbrain google setup 全程引导 自带 OAuth 端到端流程（你自己的免费 Google Cloud 客户端——你拥有 应用和令牌，它们只存在于本地凭据库中），注册一个 --kind google 源，执行有界首次同步，并以 开放循环引擎的杀手级输出结束：

gbrain google setup       # connect Gmail/Calendar/Contacts → first sync → first digest
gbrain waiting            # who is waiting on you, what you promised, with receipts
gbrain google calendars   # every calendar the account can read; pass an id to
                          #   `sources add … --calendar-id <id>` to sync a secondary one
gbrain loops mute sender <email>     # stop opening loops for a sender (or `thread <id>`)
gbrain loops unmute sender <email>   # undo it — exact and forward-only

对你的代理说： "谁在等我？" / "开放循环"（路由到 google-loops 技能，该技能也涵盖静默发件人——你的代理运行 gbrain loops mute sender <email>，以及 gbrain loops unmute sender <email> 来撤销）— "列出我的谷歌账户可以读取的日历"（你的代理运行 gbrain google calendars)。

设置 + 故障排除：docs/guides/google-connect.md。 开放循环引擎如何决定谁在等待：docs/guides/open-loops.md。

你其他代理的历史记录可以通过一条命令导入。 gbrain transcripts ingest 解析代理会话日志（Claude Code、Codex、OpenClaw、Hermes、Grok Build）以及提取的 消费者聊天导出（ChatGPT / Claude.ai conversations.json) 为可读的 对话页面，并带有指向确切会话文件的来源。在写入任何内容之前， 秘密信息会从消息正文、标题、发言者和会话元数据中清除，批量回填默认关闭嵌入， 重新运行是免费的——未更改的会话会按内容哈希跳过：

gbrain transcripts ingest                    # discover importable session logs
gbrain transcripts ingest --all              # import everything discovered
gbrain transcripts ingest ~/Downloads/conversations.json  # consumer export (unzip first)
gbrain transcripts ingest --max-bytes 4gb <store>          # oversized store; omit to keep per-format caps
gbrain transcripts status                    # found vs imported, per harness

对你的代理说： "从 ~/Downloads/conversations.json 导入我的 ChatGPT 导出中的对话" — "归档我的会话记录" — 之后，"我第一次讨论代理记忆是什么时候？"（归档会用带日期的引文回答起源问题）。

或者连接账户，完全跳过手动导出。 gbrain connectors 实时同步你的 ChatGPT 和 Claude 对话历史，使用你自己的浏览器 会话 cookie——增量式（持久化的每提供商水位线，加上 尾部窗口间隙修复），通过相同的编辑 + 幂等管道，并且 可选按计划运行。凭据留在你的机器上（~/.gbrain/connectors/*.json， 0600），并且只发送到提供商自己的主机：

gbrain connectors auth chatgpt --cookie -    # paste the Cookie header (stdin keeps it out of argv)
gbrain connectors sync chatgpt --dry-run     # preview, then --limit 5, then --full
gbrain config set connectors.chatgpt.auto_sync true   # opt-in daily auto-sync (+ gbrain autopilot --install)

对你的代理说： "连接我的 ChatGPT 账户并将我的整个历史记录拉入大脑" — "连接我的 Claude 账户" — "自动保持我的对话同步。" 你的代理会引导你完成 cookie 捕获，运行试运行 → 抽样 → 完整序列，并在你选择加入时设置计划。

完整契约、自动化通道和 Cloudflare 注意事项：docs/guides/chat-connectors.md。

（不要与上面的入站"连接器"混淆——那些是将 gbrain 作为 MCP 连接器添加到 ChatGPT/Claude/Perplexity 内部，以便这些助手可以 搜索你的大脑。 gbrain connectors 方向相反：它将你的 对话历史从那些账户拉入大脑。）

第三方技能包可以针对版本化的 IngestionSource 契约在 gbrain/ingestion提供自定义摄取源（Granola、Linear、 语音、OCR）。参见 docs/skillpack-anatomy.md。

你大脑的形状（模式包）

大多数个人知识工具强制使用一种固定布局：它们对"笔记" + "人物" + "标签"的想法。将 Notion 导出或你自己多年的 Obsidian 库放在上面，代理不知道 Projects/ 文件夹是什么意思，或者 Reading/ 是人还是来源。

gbrain 没有固定布局。 它附带捆绑的模式包，并在没有合适的时候让你编写自己的模式包：

• gbrain-base-v2（默认）— 15 类型 DRY/MECE 规范分类法（14 个规范 + note 兜底）： person, company, media, tweet, social-digest, analysis, atom, concept, source, deal, email, slack, writing, project, note。子类型/格式/来源推送到 frontmatter。
• gbrain-base（旧版）— 更宽的 24 类型布局。保持捆绑以向后兼容；使用它的库可以通过 gbrain onboard --check --explain → gbrain jobs submit unify-types --allow-protected --params '{"target_pack":"gbrain-base-v2","apply":true}' 升级（省略 "apply":true 以进行试运行预览——这是默认设置）。
• gbrain-recommended — 用 gbrain-base 中的 13 个额外目录扩展 docs/GBRAIN_RECOMMENDED_SCHEMA.md （来源、地点、旅行、对话、个人、公民、项目等）。使用 gbrain schema use gbrain-recommended激活。
• 你自己的包 — gbrain schema detect 将你实际的文件系统聚类为建议的类型， gbrain schema suggest 对它们运行 LLM 遍历，然后 gbrain schema review-candidates --apply 提升你喜欢的那些。三条命令，大脑就知道你的形状。编写后继包（声明 migration_from: 以便现有库可以选择加入）：参见 docs/architecture/pack-upgrade-mechanism.md.

gbrain schema active                # which pack is running, which tier set it
gbrain schema list                  # bundled + installed packs
gbrain schema detect                # propose types matching your filesystem
gbrain schema suggest               # LLM-refined proposals on top of detect
gbrain schema review-candidates     # human gate: promote / rename / ignore
gbrain schema use my-pack           # activate

对你的智能体说： "我的模式与笔记不匹配——请根据我的语料库提出新类型" — "为我的大脑模式添加一个实验室结果的页面类型。" 模式编写技能会为你运行 检测 → 建议 → 审查 流程。

活动包贯穿每条读写路径： parseMarkdown 从包的路径前缀推断页面类型； whoknows 将专家路由限定在声明的类型内； expert_routing: true; extract_facts 仅在 extractable: true 类型上运行。保留的搜索缓存键包含包名和版本，但语义结果复用暂时禁用。切换包后大脑会重新解读自身；切回来时不会丢失任何内容。

七级解析链（每次调用标志 → 环境变量 → 每源数据库键 → 全脑数据库键 → gbrain.yml → ~/.gbrain/config.json → gbrain-base 默认值）。完整参考和编写指南：docs/architecture/schema-packs.md。

教程

逐步演练，助你充分利用 GBrain。每个教程都带你从零开始，通过具体命令和真实数据达成可用成果。

• 从零开始设置你的个人 AI 智能体 + 大脑 — 标准的全栈安装。两个 GitHub 仓库、一个 Telegram 机器人、Render 上的 AlphaClaw、OpenClaw + GBrain + Supabase。端到端约 2 小时。
• 将 GBrain 设置为你公司的知识库 — 面向 10-50 人团队的联邦式、多用户、OAuth 作用域机构记忆。端到端约 90 分钟。
• [使用 gbrain skillopt](docs/tutorials/improving-skills-with-skillopt.md自动改进技能**]( SKILL.md 视为可训练参数。直接用技能生成一个入门基准 --bootstrap-from-skill （或自行编写），强化评判器，然后观察优化器提出修改，只保留那些可衡量得分更高的修改。约 20 分钟，API 调用约 $1。标志 + 成本 + 安全参考：docs/guides/skillopt.md。

更多演练正在制作中：将现有智能体（Claude Code、Cursor、OpenClaw、Hermes）连接到 GBrain 记忆层；为 VC 交易流设置 GBrain，包含创始人记分卡和会议准备；迁移现有 Notion 或 Obsidian 库；将代码库索引为可查询的代码大脑。完整教程索引：docs/tutorials/。

想看到尚未收录的教程？打开一个问题，描述你希望记录的工作流程。

它的作用（循环）

  signal   →   search   →   respond   →   write   →   auto-link   →   sync
  (every    (brain-first  (informed     (page +    (typed edges     (cron
  message)  retrieval)    by context)   timeline)  + backlinks)     keeps fresh)

• 信号检测器 在你的智能体收到的每条消息上运行。捕获想法、实体提及、时间敏感的待办事项、名称、链接。
• 大脑优先查找 在任何外部 API 调用之前。这是你拥有的最便宜、最快、最个性化的信息来源。
• 自动链接 在每次页面写入时触发。无 LLM 调用；纯模式匹配 [[wiki/people/bob]] 风格引用。新实体 → 新页面存根 → 图谱增长。
• 定时驱动增强 在你睡觉时运行：去重人物页面、修复引用、评估显著性、发现矛盾、准备明天的任务。

整个循环在 docs/architecture/topologies.md 中有描述，并附有图表。

对你的智能体说： "设置自动驾驶"（安装运行循环的定时任务）— "运行梦境" — "梦境周期运行了吗？"

能力

混合搜索。 向量（pgvector 上的 HNSW）+ BM25 关键词 + 倒数排名融合 + 来源层级提升 + 意图感知查询重写。三种命名搜索模式（conservative, balanced, tokenmax）将成本/质量旋钮捆绑到一个配置键中。实时成本/召回比较见 docs/eval/SEARCH_MODE_METHODOLOGY.md。安装选择器默认应用 tokenmax （它推荐 conservative 用于 Haiku 级子代理层级或无密钥设置）；一个 search.mode 未设置的大脑在查询时解析为 balanced 。交叉编码器重排序器在 balanced 和 tokenmax中开启，在 conservative 中关闭 — 默认是 rerank-2.5 ；没有密钥时搜索在融合顺序中失败开放，并且 VOYAGE_API_KEY上的 Voyage gbrain search modes / gbrain doctor 会说明这一点（问你的智能体 "检查我的大脑重排序器是否真的在运行"）。每次查询的图谱信号会注意到顶级结果是否是那个查询的枢纽（邻接提升）、是否在团队大脑间得到佐证（跨来源提升）、或者是否被来自活跃会话的弱块挤出（会话降级）。运行 gbrain search "<query>" --explain 查看每个阶段的归因：基础分数、每个触发的提升、它乘了什么。 gbrain doctor 附带一个 graph_signals_coverage 检查； gbrain search stats 显示触发次数和失败分解。向量检索汇集每页的最佳块，因此页面以其最强证据浮现，而不是因一个弱块输给邻居。匹配页面标题短语或声明的自由文本别名的查询（gbrain reindex --aliases 回填现有页面）会提升到它们命名的页面。每个结果都带有 evidence 标签（为何匹配）和 create_safety 提示（exists / probable / unknown），以便智能体决定页面是否已存在，而不是根据原始分数猜测。 gbrain search diagnose "<query>" --target <slug> 追踪哪个检索层浮现（或错过）一个页面。对你的智能体说： "调整我的检索" — "我运行的是什么搜索模式？" — "为什么这个页面排第一？"（你的智能体运行 gbrain search --explain）。

自接线知识图谱。 每个 put_page 从 markdown/wikilinks/类型化链接语法中提取实体引用，并在零 LLM 调用的情况下写入边。类型化边（attended, works_at, invested_in, founded, advises, mentions，…）。通过 gbrain graph-query进行多跳遍历。图谱正是产生比纯向量 RAG 高出 +31.4 P@5 提升的原因。对你的智能体说： "谁在 acme-example 工作？" — "fund-a 和 widget-co 之间是什么关系？" — "alice-example 有什么联系？" Obsidian 风格库： 指向跨文件夹的裸 [[note-name]] wikilinks — 你写了 [[struktura]] 但页面位于 projects/struktura.md — 一旦你用 gbrain config set link_resolution.global_basename true选择加入，就按基名解析。默认关闭； gbrain doctor 会在你切换前告诉你将获得多少条边。参见 迁移 Obsidian 库.

任务队列（Minions）。 基于 BullMQ 形态、Postgres 原生的任务队列。持久化子代理（通过两阶段 pending→done 持久化在崩溃后存活的 LLM 工具循环）、带审计的 shell 任务、带级联超时的子任务、面向外部提供方的速率租约、通过 S3/Supabase 存储的附件。可选按任务进程隔离（gbrain jobs work --job-isolation process）会在各自的、可被 SIGKILL 的子进程中运行每个已领取的任务，因此卡住的处理程序会真正终止，崩溃只影响一个任务而非整个 worker；当 worker 的数据库健康检查失败时，它会指明失败层（pool_starved 与 server_unreachable），而不是笼统地报“数据库不可达”。规模调整与部署指南见 [docs/guides/minions-deployment.md](docs/guides/minions-deployment.md）；探针判定分类见 [docs/guides/queue-operations-runbook.md](docs/guides/queue-operations-runbook.md）。它用能从任何故障中恢复的机制取代了“将子代理作为即发即弃的 Promise 生成”。对你的 agent 说： “把这个作为后台任务运行，完成后告诉我” — “为回填提交一个 gbrain 任务” — “后台在跑什么？”

非英语大脑（FTS 语言配置）。 Postgres 全文搜索分词器可通过 GBRAIN_FTS_LANGUAGE配置。默认值为 english。可将其设置为 Postgres 实例中存在的任何文本搜索配置：

export GBRAIN_FTS_LANGUAGE=portuguese     # uses built-in portuguese stemmer
export GBRAIN_FTS_LANGUAGE=spanish        # built-in spanish stemmer
export GBRAIN_FTS_LANGUAGE=pt_br          # custom config (e.g. unaccent + portuguese)

列出可用配置： psql -c "SELECT cfgname FROM pg_ts_config"。查询侧（websearch_to_tsquery）和写入侧（填充 pages.search_vector 和 content_chunks.search_vector的触发器函数）都遵循 GBRAIN_FTS_LANGUAGE。首次安装（或升级）时， configurable_fts_language 模式迁移会读取环境变量并以配置的语言创建触发器函数；后续的插入/更新将使用该设置进行分词。若要在已运行迁移的大脑上更改语言，请使用专用 CLI 命令：

export GBRAIN_FTS_LANGUAGE=portuguese
gbrain reindex-search-vector --dry-run    # preview row counts
gbrain reindex-search-vector --yes        # recreate triggers + backfill

该命令是幂等的（使用相同语言重新运行对向量内容无操作），并使用与迁移相同的重建和回填原语。对于不区分重音的葡萄牙语（pt_br），请参阅 docs/guides/multi-language-fts.md 了解 unaccent + 葡萄牙语词干提取器配方。对你的 agent 说： “将我的大脑搜索语言设置为葡萄牙语并重新索引。”

50+ 精选技能（当前列表见 [skills/manifest.json](skills/manifest.json）。路由见 [skills/RESOLVER.md](skills/RESOLVER.md）。涵盖信号捕获、摄取（想法 / 媒体 / 会议）、增强、查询、大脑运维、引用修复、每日任务管理、cron 调度、报告、语音、灵魂审计、技能创建、评估框架和迁移。技能是 Markdown 文件（与工具无关），打包为单个技能包，安装程序会将其放入你的 agent 工作区。

对你的 agent 说——短语手册。 你永远不会按名称调用技能；你说出需求，你的 agent 会进行路由。每个技能都在其 frontmatter 中声明触发短语，[skills/RESOLVER.md](skills/RESOLVER.md）是完整的人类可读短语手册——一张“当你说这个时，触发这个技能”的表格。尝鲜： “摄取这个 PDF”（媒体摄取）— “今天有什么安排？”（简报）— “填满我的大脑”（冷启动）— “大脑健康” / “检查反向链接”（维护——任一短语都会路由到那里）— “我的大脑设置正确吗？”（gbrain-advisor）— “重启破坏什么了吗？”（冒烟测试）— “把这个作为后台任务运行”（minion-orchestrator）。如果你不确定该说什么，可以问你的 agent： “我的大脑能做什么？” 并让它把解析器读给你听。

评估框架。 gbrain eval longmemeval 针对您的混合检索运行公开的 LongMemEval 基准测试。测量于2026-09-06，gbrain v0.48.4.0，通过此命令在LongMemEval-S（2025年9月修订清理版，500个问题，按官方评分器剔除30个弃权问题后评分为470个），k=5，单次运行：在发布默认路径（balanced: voyage:rerank-2.5 开启，自动截断关闭）下，严格的会话级 recall_all@5 为 95.53%（449/470），意味着每个黄金会话都落在前5个不同检索会话内，仅检索，无阅读模型；关闭重排序器后，与不运行重排序器的系统进行同类对比，93.40%（439/470）。较宽松的任意命中 recall_any@5 为 99.79% / 98.72%，作为诊断指标而非主要指标报告。关闭重排序器的行复现了兄弟项目 gbrain-evals 运行器2026-09-02的收据（438/470；470行中469行按问题一致），逐行收据存放于此。与关闭重排序器的混合检索配对相比，重排序器增益18个问题，损失8个；v0.48.4.0之前发布的默认版本（重排序器开启且自动截断开启）得分为379/470，因为自动截断在多部分问题上保留了最佳会话并丢弃其余部分，这就是自动截断现在关闭的原因。一个警告，排序器浪潮重新测量而非移除： tokenmax的LLM多查询扩展在k=5时有害——在旧权重下为255/470 recall_all@5 （与混合检索配对 +3 / −187），使用新的 search.expansion_variant_budget 旋钮在其最小的预注册值下为394/470，在保留决策集上仍落后纯混合检索43个问题——因此捆绑包保留旧权重，小k召回率在该模式下仍然较差，条件扩展是已提交的下一步。 gbrain eval export + gbrain eval replay 捕获真实查询并针对代码更改重放（设置 GBRAIN_CONTRIBUTOR_MODE=1). gbrain eval cross-modal 使用三个不同提供商的边界模型交叉检查输出与任务。 gbrain eval retrieval-quality 运行NamedThingBench，该基准硬性门控命名事物检索家族（标题子串、别名同义词、通用到命名、多块稀释），因此“查找此查询命名的页面”的回归会在CI中响亮失败。 gbrain eval brainbench 运行跨框架内存一致性套件：知道何时询问、推送精确率/召回率、写回保真度和跨会话连续性，按框架接缝评分（您的OpenClaw生产流水线加上Claude Code和Codex注入契约），针对已提交的141个夹具合成语料库——默认密封（内存PGLite，无密钥，秒级），CI对主分支的已提交基线门控每个PR。方法论见 [docs/eval/BRAINBENCH.md](docs/eval/BRAINBENCH.md）；搜索模式方法论见 [docs/eval/SEARCH_MODE_METHODOLOGY.md](docs/eval/SEARCH_MODE_METHODOLOGY.md）。对您的代理说： "对检索运行回归检查"（您的代理运行 gbrain eval brainbench）；"运行公开的LongMemEval基准测试进行同类对比"（此操作无技能支持；您的代理运行 gbrain eval longmemeval <longmemeval_s_cleaned.json> --retrieval-only --top-k 5 --by-type --no-trajectory --mode balanced --reranker off --autocut off。该仓库内命令是93.40%行（以及2026-09-02收据的93.19%）的复现路径：其 --by-type 摘要报告严格的 recall_all@5 ，以任意命中作为诊断指标，按数据集的原始会话ID连接，并按官方评分器剔除30个弃权问题； --reranker on --autocut off 改为运行已发布的默认路径——自规则R2起所有模式均关闭自动截断——而 --reranker on --autocut on --capture-pool 复现自动截断重放所依据的捕获）。

衡量标准。 一个区别决定每次内存基准比较：严格的 recall_all@5 仅在每个黄金会话都落在前5名时才计入问题，而宽松的任意命中在单个会话命中时即计入，LongMemEval-S的470个评分问题中有300个需要两个或更多会话。在严格指标下，在此数据集上，gbrain在关闭重排序器时得分为93.40%（v0.48.4.0，2026-09-06，470个评分；2026-09-02兄弟收据为93.19%），在发布默认路径上开启 voyage:rerank-2.5 时为95.53%（同次运行，同样470个）；k=5上限为99.4%，因为3个问题携带6个黄金会话。我们能找到的最接近的严格比较：MemPalace仅发布任意命中（96.6% / 98.4%），但根据官方黄金标签重新评分其已提交的逐问题排名，其原始向量设置为85.7%，LLM重排序器在循环中为90.0%（我们的重新计算，他们的数据）；ContextFit发布All@5为87.45%（411/470），其重排序层在运行期间读取黄金标签，因此我们标记为大致可比。Mastra、Mem0、MemCog、Supermemory等引用的94%至96%数字是LLM评判的答案准确率，这是一场不同的竞赛，评分阅读器和评判器与内存同等重要。gbrain的第一个评判数字，随v0.48.4.0发布：86.6%（433/500；95% CI 83.6–89.6），使用默认的 anthropic:claude-sonnet-4-6 阅读器读取检索会话的全文，gpt-4o评判器运行官方提示；470个非弃权问题中有449个检索到所有黄金会话，阅读器转换了其中396个，因此与这些供应商数字的差距在于回答层，且协议不同，故不主张任何方向的比较。同一语料库上的纯向量得分为93.8%（v0.48.0.0收据），因此混合层在此基准上大致中性，并在其他地方发挥作用。完整表格含来源及我们的解读：[gbrain-evals docs/comparison-systems.md](https://github.com/garrytan/gbrain-evals/blob/main/docs/comparison-systems.md）。

大脑一致性。 gbrain eval suspected-contradictions 采样检索对、分层日期预过滤、查询条件LLM评判器、持久缓存。揭示代理已写入的观点与事实之间的冲突。接入每日梦境周期。对您的代理说： "梦境周期运行了吗——它揭示了什么矛盾？" — "事实核查我们关于acme-example的内容"（逐条声明的实时来源验证）— 或让您的代理直接运行 gbrain eval suspected-contradictions 。

代理编写的模式。 你的大脑有形状——存在哪些页面类型（person, meeting, paper, case, lab-result），它们链接到什么（attended, authored, prescribed-by），哪些事实会被自动提取。默认配置带有通用类型，但你大脑的实际形状并非默认形状。代理可以通过14个 gbrain schema CLI动词 + 一个批量MCP操作（schema_apply_mutations，管理员范围，非localOnly，因此远程代理可通过HTTPS访问它）来代表你演化该形状。原子文件锁、带有代理身份的审计日志、以1000行批次进行的块状UPDATE回填，绝不会阻塞并发写入者。大脑不再是一堆笔记，而是变成了有结构的东西。对你的代理说： "为我的模式添加一个案例文件的页面类型" — "我的大脑有未类型化的页面——从我的语料库中提出新类型。" 为何重要： docs/what-schemas-unlock.md — 7个杀手级用例（4000次隐形会议、创始人运营大脑、研究大脑、法律大脑、团队大脑、代理作为共同策展人）。5分钟演练： docs/schema-author-tutorial.md。代理技能： skills/schema-author/SKILL.md。

集成

数据流入大脑。每个集成都是一个配方——markdown + 设置提示——随 recipes/ 一起提供，并可通过 gbrain integrations list发现。对你的代理说： "将语音通话设置到我的大脑中" — "将我的电子邮件和日历接入大脑" — 你的代理读取配方并陪你完成设置。

• 语音：电话通过Twilio + OpenAI Realtime（或DIY STT+LLM+TTS）创建大脑页面。设置配方：recipes/twilio-voice-brain.md。
• Gmail + 日历 + 联系人（原生）：google源类型通过你自己的OAuth客户端同步线程、事件和联系人，并在其上运行开环引擎（gbrain waiting)。设置：docs/guides/google-connect.md；配方：recipes/email-to-brain.md, recipes/calendar-to-brain.md。
• 电子邮件 + 日历（webhooks）：路由到大脑信号的webhook处理器。docs/integrations/meeting-webhooks.md。
• 嵌入提供者：涵盖十几个提供者——Voyage（默认： voyage-4 @ 1024d）、OpenAI、OpenRouter、Google Gemini、Azure OpenAI、MiniMax、阿里云DashScope、智谱、Ollama（本地）、llama.cpp llama-server（本地）、LiteLLM代理，外加ZeroEntropy（已弃用——托管API于2026-09-04结束）。定价矩阵 + 决策树见docs/integrations/embedding-providers.md。
• 重排序器：Voyage rerank-2.5 托管（默认；重排序在 balanced 和 tokenmax 模式下开启，与嵌入使用相同的 VOYAGE_API_KEY ；预览 rerank-3 / rerank-3-lite 可通过 gbrain config set search.reranker.model voyage:rerank-3选择），ZeroEntropy zerank-2 （已弃用——托管API于2026-09-04结束；显式配置可绕过该日期），外加 llama-server-reranker 配方，用于通过llama.cpp实现完全本地的交叉编码器重排序——针对相同的 gateway.rerank() 接缝运行Qwen3-Reranker或自托管zerank权重。设置演练见docs/ai-providers/llama-server-reranker.md。
• 凭据保险库 + 网关： gbrain creds 在本地保险库中管理OAuth和API凭据（recipes/credential-gateway.md）；代理端保险库感知的秘密分发：docs/integrations/credential-gateway.md。
• MCP客户端：支持所有主流MCP客户端。docs/mcp/ 每个客户端的设置。
• Memorable（程序性记忆）：可选，默认关闭。你的大脑记住发生了什么；Memorable让你的代理记住如何做——完成的会话变成可重放的程序，存储在你的机器上（在独立的本地存储中，或如果你选择，则在你大脑数据库中），当类似任务再次出现时被召回。参见下方章节，以及docs/memorable-agents.md获取面向代理的详细信息。

Memorable — 记住如何做，而不仅仅是做了什么（可选）

当你的代理第三次修复同一类错误时，它不应该从头重新诊断。没有程序性记忆，每个会话都冷启动：重新探索代码库、重新找到文件、重新发现哪个命令真正验证了修复。Memorable 闭环了这一点。一旦启用，已完成会话的真实工具调用——运行了什么、使用了什么参数，以及（如果工具框架记录了）每一步是否成功——变成一个有序、可重放的程序：步骤、触发签名、前置条件、后置条件。它存储在你的机器上，默认在独立的本地存储中，或如果你选择，则在你现有的大脑数据库中（细则解释了权衡）。下次类似任务出现时：

memorable recall "the order-validation tests are failing again"
# → 0.981  procedures/ab12cd34-fix-failing-order-tests  [lexical]
memorable show procedures/ab12cd34-fix-failing-order-tests
# → last time this landed in src/orders/validate.js and
#   ./test.sh verified it — the steps, in order, with real outcomes

你的代理跳过它已经做过一次的诊断，直接进行修复。这就是整个产品：捕获是自动的（会话结束时无需记住任何东西），召回是下一个会话开始时的单条命令。

对你的代理说： "设置Memorable，这样你就能记住任务是如何完成的" — 你的代理安装并初始化CLI（npm i -g memorable-cli, memorable init, memorable enable）；然后你自己运行下面的一个同意步骤。日常使用："开始之前，检查Memorable我们上次是怎么做的" — 你的代理运行 memorable recall "<the task in your words>" — 以及 "Memorable到目前为止存储了什么？" — 你的代理运行 memorable list。

开启它（三个步骤，最后一步由你完成）：

npm i -g memorable-cli                    # 1. the CLI, published on npm (closed source)
memorable init && memorable enable         # 2. standalone local store + let Memorable record sessions
                                           #    (`memorable init gbrain` stores procedures in your brain DB
                                           #     instead — trade-off in the fine print's first bullet)
gbrain config set integrations.memorable.enabled true   # 3. YOU run this: gbrain shows exactly what
                                                         #    leaves the machine and asks you to approve it

第3步是强制性的，并且设计为交互式——中继保持关闭，直到你接受gbrain的披露提示。无需创建账户，也无需配置嵌入模型（如果存在，你的gbrain提供者会被重用；否则Memorable的服务器为你计算嵌入）。从那时起，捕获自动运行：Claude Code和Codex会话在会话结束时被记录。OpenClaw捕获在每次压缩时运行，但尚不产生存储的程序（它只记录工具名称，服务拒绝将其视为不可重放——细节见细则）。

细则（启用前请阅读）

来源，直白说明： memorable CLI是一个由第三方（Memorable，而非gbrain）发布的闭源npm包，没有公开的源代码仓库，也没有gbrain可以验证的构建证明。启用中继意味着一个第三方二进制文件在你的会话边界运行，并将经过编辑的会话数据发送到Memorable的提取API。gbrain本身绝不会为此集成将任何数据发送出机器。

gbrain验证什么 vs. Memorable声称什么 — 这种区分很重要：

• gbrain 验证（由 gbrain 自身代码强制）：
  • 中继默认关闭，并且在你接受 gbrain 的披露提示之前保持关闭（gbrain config set integrations.memorable.enabled true）。它写入的同意标记位于 gbrain 私有文件中，CLI 从未写入该文件，因此 CLI 在频带外翻转配置标志永远无法在你首次同意之前激活中继；gbrain 侧的禁用/取消设置会撤销该标记并强制重新披露。
  • 工具调用参数在到达回执之前会使用高熵规则进行秘密扫描。
  • 会话结束时 gbrain 启动的中继进程在没有 Memorable 侧同意的积极证据的情况下也会被跳过。
  • GBRAIN_MEMORABLE=0 （任何常见的否定拼写，去除空格——没有环境变量值可以启用）会终止一切。
  • gbrain doctor的 memorable_relay_health 会列出所有损坏或半同意状态。
• Memorable 的声明（来自其文档和可观察的客户端行为——gbrain 无法验证服务器端）： 提取 API 是无状态的，原始痕迹不会长期保留，仅存储派生的“节点”，并且用户之间没有共享图。请注意，匿名 mk_ API 密钥意味着也没有账户可以通过它来行使删除服务器可能保留的任何内容的权利。

它如何融入 gbrain 的模型：

• 程序存储位置——了解信任形态。 独立模式（memorable init，上面块中的默认值）将程序存储在本地存储中，位于 ~/.memorable 下，并完全将 CLI 排除在你的大脑数据库之外——对于敏感大脑来说这是更安全的选择。在 gbrain-backend 模式（memorable init gbrain）下，程序成为你已运行大脑中专用非联邦 memorable 源中的普通页面；Memorable 的服务永远不会连接到你的数据库，但闭源的 CLI 随后对整个大脑数据库拥有完全的本地访问权限（这就是它存储程序的方式）。
• 回忆主要是本地的——但有一个例外。 查找首先是精确 + 词法匹配，然后通过你自己的嵌入提供程序进行语义匹配。如果你没有配置本地提供程序且词法匹配未命中，CLI 会将查询文本（你的任务描述，最多 8 KB）发送到 Memorable 的 /v1/embed ——回忆并不总是没有数据外发。
• 按工具框架捕获。 Claude Code 和 Codex 会话在会话结束时捕获（Codex 通过一个受信任门控的 hooks.json 条目，由 gbrain bootstrap 管理）；OpenClaw 会话每次压缩时捕获——从未压缩的短会话不会被捕获，最后一次压缩之后的尾部也永远不会被捕获。OpenClaw 捕获目前仅记录工具名称（其会话格式中至今未观察到参数），而 Memorable 的 API 拒绝仅名称的痕迹，因为不可重放——预计 OpenClaw 中继会被拒绝，直到参数捕获落地。任何其他工具框架可以直接移交痕迹： memorable ingest trace.json。
• 存储会自行修剪，你也可以修剪它。 重新记录会刷新相同修订并并排保留不同方法； memorable list / memorable prune 管理存储，在所有同意模式下。本地 gbrain 侧工件（~/.gbrain/integrations/hooks/session-receipts.jsonl + memorable-relay.jsonl）有大小上限，一行清除命令即可删除它们（参见文档）。
• 开/关是明确的——CLI 写入 gbrain 的配置。 memorable enable | disable | setup 在 integrations.memorable.enabled 。仅该标志永远不会激活中继：gbrain 的披露同意是独立的，由 ~/.gbrain/config.json 本身（频带外）翻转 gbrain config set integrations.memorable.enabled false 或 gbrain config unset …撤销，并且每当捕获面扩大时都会重新要求（新的工具框架通道按设计使旧同意失效）。

回执形态、每命令外发表、故障排除和完整同意模型记录在 docs/memorable-agents.md。

架构

flowchart LR
    Repo[Markdown brain repos] --> Sync[Sync and parse]
    Sync --> Engine{Brain engine}
    Engine -->|default| PGLite[(PGLite)]
    Engine -->|shared or large| Postgres[(Postgres and pgvector)]
    Agent[AI agent or operator] --> Surface[CLI or MCP]
    Surface --> Ops[Contract-first operations]
    Ops --> Search[Hybrid retrieval]
    Ops --> Graph[Typed graph traversal]
    PGLite --> Search
    Postgres --> Search
    PGLite --> Graph
    Postgres --> Graph
    Search --> Synthesis[Synthesis and gap analysis]
    Graph --> Synthesis
    Synthesis --> Answer[Cited answer]

两个引擎，一个契约。 PGLite（通过 WASM 的 Postgres 17，零配置，默认）用于个人大脑，最多约 5 万页。Postgres + pgvector（Supabase 或自托管）用于共享/大型/多机器部署。契约优先的 BrainEngine 接口在 src/core/engine.ts 中定义了两个引擎都实现的 140 多个方法；CLI 和 MCP 服务器从单一来源生成。

大脑仓库是记录系统。 你的知识以 markdown 文件形式存在于常规 git 仓库（你的“大脑仓库”）中。GBrain 将仓库同步到 Postgres 以供检索；git 中的删除在数据库中变为软删除。你可以发布公共子集、共享团队挂载、运行指向同事大脑服务器的瘦客户端设置。拓扑结构见 docs/architecture/topologies.md。

两个组织轴（大脑 ⊥ 源）。 大脑 是一个数据库（你的个人大脑，你加入的团队挂载）。源 是该大脑内的一个仓库（wiki、gstack、一篇论文、一个知识库）。路由位于 .gbrain-source 点文件中，并通过文档化的 6 层优先级链解析。完整图表见 docs/architecture/brains-and-sources.md。

为什么图很重要。 向量搜索返回语义接近的块。图返回事实连接的块。混合搜索从两者中提取；每次写入时的自动链接保持图的新鲜度。深入探讨：docs/architecture/RETRIEVAL.md。

故障排除

首先对你的代理说： “运行大脑健康检查并修复你发现的问题” ——这会路由到维护技能，该技能运行 gbrain doctor 并自动修复或打印确切的修复命令；你的代理可以运行整个循环（“让我的大脑健康评分达到 90” 使用带成本上限的修复规划器）。以下部分适用于你想要手动路径的情况。

PGLite 启动时崩溃并显示 RuntimeError: Aborted() （通常在 macOS 升级后）？ 这不是 macOS 不兼容——操作系统升级重启在 gbrain 写入中途将其杀死并撕裂了数据目录的 WAL。gbrain 会在下一条命令时自动修复（数据保留，备份保留）；如果自动修复被禁用或跳过，运行 gbrain pglite-repair --dry-run 进行诊断，运行 gbrain pglite-repair --yes 就地修复。完整恢复阶梯（修复 → 重建 → 引擎切换）见 docs/ENGINES.md — 故障排除：启动中止 和 docs/INSTALL.md.

gbrain import 失败并返回 expected N dimensions, not M？ 运行 gbrain doctor。它将打印出精确的 gbrain config set ... 或 gbrain migrate embeddings 命令来修复不匹配。你不应该需要删除 ~/.gbrain。全新的 gbrain init --pglite 会根据 API 密钥自动检测你的嵌入提供商：在运行 init 之前，在环境中设置 VOYAGE_API_KEY （或 OPENAI_API_KEY / 另一个提供商密钥）——或者在 ~/.gbrain/config.json中设置，init 也会读取它——或者显式传递 --embedding-model <provider>:<model> 。如果设置了多个密钥，init 会启动一个交互式选择器（非 TTY 环境在其密钥存在时自动选择 Voyage 默认值）。如果完全没有密钥，init 会在没有密钥的情况下继续（仅限关键词搜索）并发出明显通知；稍后添加密钥并重新运行 gbrain init --force --embedding-model voyage:voyage-4 以启用嵌入，或者预先传递 --no-embedding 以明确无密钥模式。参见 docs/integrations/embedding-providers.md 获取完整的提供商矩阵，以及 docs/operations/headless-install.md 获取 Docker/CI 顺序。

gbrain doctor 警告 default_source_local_path？ 你的 default 源没有 local_path 并且该空指针被证明会破坏写穿透（仓库回退是另一个源自己的工作树，或者文件支持默认页面没有可解析的根）。单独的 null local_path 是设计中的回退拓扑，并报告正常。修复是指针更新，绝不是文件移动： gbrain sources set-path default <path> 在更改之前打印先前的值，并拒绝嵌套在另一个源树内部或吞并另一个源树的路径（退出码 6； --force 可绕过）。对你的代理说： “运行大脑健康检查并修复你发现的问题” —— 维护技能会运行 gbrain doctor 并应用打印出的修复。

联邦大脑上的每小时 cron 同步持续超时？ 将你的 cron 切换为每个源的循环，使用 shell timeout(1) 执行操作系统级别的终止，并让 gbrain 提前半分钟优雅地自我终止：

gbrain sync --break-lock --all --max-age 1800
for src in $(gbrain sources list --json | jq -r '.[].id'); do
  timeout 600 gbrain sync --source "$src" --timeout 540 || true
done

当 --timeout 在导入中途触发时， gbrain sync 以状态 partial 退出 0，并且 last_commit 保持不变——下一次运行会重新遍历相同的差异，并且 content_hash 会短路已导入的文件。 --max-age 1800 第一个命令会自愈由先前挂起运行留下的任何卡住但仍存活的锁，基于锁的最后刷新时间（而不是获取时间）作为键，因此健康的长时持有者构造上是安全的。范围说明：提取 + 嵌入阶段一旦启动仍会运行到完成； --timeout 仅中断导入遍历。

Dream 周期在 Supabase 上静默丢失 wiki 链接？ 引擎会在 Supavisor 池化器故障时自动重试每个批量写入（addLinksBatch / addTimelineEntriesBatch / upsertChunks），最坏情况等待 12 秒，覆盖完整的 5-10 秒断路器恢复窗口。 gbrain doctor 通过 batch_retry_health 检查（读取最近 24 小时的 ~/.gbrain/audit/batch-retry-YYYY-Www.jsonl）来呈现事件。要针对异常缓慢的池化器进行调整：

# Defaults: 3 retries, base 1s, max 10s, decorrelated jitter.
# Override per operator without a release:
export GBRAIN_BULK_MAX_RETRIES=5       # int >= 0; 0 disables retries
export GBRAIN_BULK_RETRY_BASE_MS=2000  # int > 0
export GBRAIN_BULK_RETRY_MAX_MS=15000  # int >= base

错误值会在 gbrain doctor 启动时出现，并附带可直接粘贴的修复（而不是在周期中途的首次重试时）。仅 PGLite 的安装零成本——重试包装是引擎级别的，但 PGLite 没有池化器，因此重试在实践中永远不会触发。

Dream 周期每次运行丢失约 150 行链接，日志中出现 'No database connection: connect() has not been called' 错误？ 重试层会在数据库单例被置空时自愈：一个 reconnect 回调在 withRetry 上重建尝试之间的连接，并且 PostgresEngine.batchRetry 注入 () => this.reconnect() ，因此引擎级别的批量写入能够在同一进程中其他部分导致的中途断开中存活。 gbrain capture 不会在 CLI 退出后从后台 facts:absorb 工作进程产生 'No database connection' stderr 行，因为操作调度在 getFactsQueue().drainPending({timeout: 1000}) 之前等待 engine.disconnect()。要找出哪个代码路径仍在进程中途调用断开，运行 gbrain doctor --json | jq '.checks[] | select(.id=="batch_retry_health")'；该检查会显示 24 小时断开调用计数以及来自 ~/.gbrain/audit/db-disconnect-YYYY-Www.jsonl 审计的最近调用者帧。

gbrain brainstorm 返回 judge_failed: true 且评分为 0 的想法？ 你使用的是过时的构建； gbrain upgrade 就是完整的修复（无需配置更改，无需模式迁移）。当前构建会将评判者的输出上限调整为想法数量，而不是在约 40 个想法之后截断 JSON 中间部分，并且斜杠形式的模型 ID（gbrain brainstorm --judge-model anthropic/claude-sonnet-4-6 --max-cost 5）解析定价与冒号形式相同，而不是以 BudgetExhausted reason=no_pricing.

**gbrain reindex --markdown 失败。重新分块是否清除了你的 auto/dream/signal-detector 标签？ 运行 gbrain upgrade。标签协调是仅添加的：重新导入和 reindex --markdown 会添加当前的 frontmatter 标签，并且从不删除，因此写入数据库的富集标签（auto-tag、dream synthesize、signal-detector）在重新分块后仍然存在。仅数据库的重新索引回退也会在重新分块之前重建完整的 markdown（frontmatter + 正文 + 时间线），因此没有磁盘源页面会保留其 frontmatter、标题和时间线，而不是被覆盖为空 frontmatter。权衡：从页面 frontmatter 中移除标签不会在下次同步时从数据库中移除（frontmatter 标签移除需要来源列，已推迟）。

gbrain sync 在大脑上卡住（无进展，高 CPU）？ 三个工具。首先，找出卡住的文件：

GBRAIN_SYNC_TRACE=1 gbrain sync --no-pull --no-embed --yes

最后一行 [sync] begin import: <path> 没有后续完成的行就是挂起时正在处理的文件。其次，如果你怀疑 schema-pack inference.regex 存在灾难性回溯，请禁用该包完成同步，稍后重新运行提取：

gbrain sync --no-schema-pack --no-pull --no-embed --yes

gbrain schema lint 会警告包正则表达式中的经典嵌套量词 ReDoS 形状（(a+)+, (a*)*，…），并且运行时限制推理正则表达式的输入长度（通过 GBRAIN_MAX_REGEX_INPUT_CHARS覆盖）。第三，在带有活动 gbrain serve （你的代理的 MCP 服务器）的 PGLite 大脑上， gbrain sync 将运行委托给通过其本地 IPC 套接字的 serve 进程——锁所有者执行工作，你的代理保持在线，Ctrl-C 中止到检查点，下次同步从中恢复。嵌入延迟到 serve 的后台扫描。参见 docs/architecture/serve-sync-concurrency.md 了解限制（不支持的标志， serve --http）和完整的分类。

gbrain init --migrate-only / 在 Windows 上执行 schema 迁移会失败，并提示 getaddrinfo ENOTFOUND? 运行 gbrain upgrade。Schema 初始化 会在进程内运行其各个阶段，而不是为每个阶段生成子进程 gbrain init --migrate-only；在 Windows + bun + Supabase 连接池环境下，即使父进程连接正常，生成的子进程也会因 DNS 解析失败而退出，而进程内运行则完全消除了子进程生成。祖父迁移以分块批量 SQL 方式执行（按页面主键分块、过滤软删除、源安全），在包含 80K 页面的 PGLite 大脑上可在数秒内完成。

文档

• docs/INSTALL.md — 所有安装路径，端到端
• docs/guides/bootstrap.md — 持久化个人代理引导契约（访谈、身份文件、钩子、私有仓库、安全态势、卸载），以及本地测试模式（gbrain bootstrap harness），用于将框架生成的 Claude Code/Codex 会话连接到正在运行的 serve
• docs/what-schemas-unlock.md — 为什么 schema 很重要：7 个杀手级用例、类型化页面种类的结构性论证、代理协同策展模式
• docs/schema-author-tutorial.md — 5 分钟演练：fork 捆绑包、添加自定义类型、回填现有页面、通过 gbrain whoknows
• docs/architecture/ — 系统设计、拓扑、检索理论
• docs/guides/ — 操作手册（Google 连接、开放循环、子代理路由、minion 部署、技能开发、大脑优先查找、想法捕获、尽职调查摄入）
• docs/integrations/ — 连接外部数据源（语音、电子邮件、日历、嵌入提供商）
• docs/mcp/ — 每个客户端的 MCP 设置（Claude Desktop、Code、Cursor、ChatGPT、Perplexity、Cowork）
• docs/eval/ — 评估框架、指标术语表、方法论
• docs/ethos/ — 理念（薄封装、厚技能、Markdown 作为配方、起源故事）
• AGENTS.md — 非 Claude 代理的入口
• CLAUDE.md — Claude Code 的入口（深度操作上下文）
• CONTRIBUTING.md — 贡献者指南、测试纪律、评估捕获模式
• SECURITY.md — 安装路径信任模型、自更新完整性、自动扫描、OAuth 威胁模型、加固默认值

贡献

运行 bun run test 进行快速循环，运行 bun run verify 进行推送前检查，运行 bun run ci:local 在本地运行完整的 Docker 支持的 CI 堆栈。详细的测试纪律见 CONTRIBUTING.md。

社区 PR 会分批合并为发布波次，而不是逐一合并——参见 docs/RELEASING.md 中的社区 PR 波次流程。贡献者归属通过 Co-Authored-By: 尾部标记保持。我们在 CHANGELOG.md 中感谢每一项被接受的贡献。

如果你发现 bug 或想要某个功能：请先提交 issue。快速修复（拼写错误、文档 bug、明显的回归）可以直接提交 PR。任何涉及 schema、检索排序、MCP 协议或安全边界的内容，都需要先在 issue 中进行设计讨论。

许可证 + 致谢

MIT。我构建 GBrain 是为了运行我的 OpenClaw 和 Hermes 部署——这是我 AI 代理背后的生产大脑。

起源故事：docs/ethos/ORIGIN.md。

社区 PR 贡献者按版本在 CHANGELOG.md 中致谢。ZeroEntropy（@zeroentropy) 提供 ZeroEntropy 嵌入 + 重排序器集成。Voyage AI 提供非对称编码配方模板。Ramp Labs 提供搜索质量改进谱系。