setup

设置 GBrain 记忆

为用户已有的 Agent 提供可靠的记忆。保留其身份、原生记忆、现有指令以及无关配置。从免密钥存储和关键词检索开始。私有仓库、身份访谈、自动捕获、付费 API 密钥或后台服务都不是前置条件。

约定

• 在检查或修改安装状态之前，先选定目标 brain 和 source。
• 复用健康的安装；诊断部分或冲突的状态，但不要重新初始化记忆。
• 转述强制的搜索模式矩阵，并征得操作者的选择。
• 保存带有来源信息的显式记忆，并验证随机写入/回读。
• 将软件安装、原生指令激活和跨会话召回分开报告。
• 自动捕获、导入、连接器、定时任务和付费增强都需要明确的主动选择加入（opt-in）。

阶段 1：选择路径

利用用户已有的上下文；不要重复用户已经做出的选择。

意图	操作
在 Grok Bot 中添加记忆	首选：通过 MCP 使用你自己电脑上的 brain。remote-mcp 会发布它（--funnel，Bot 运行在厂商云端），然后 hosted harness access 会在 Bot 中安装私有交接配置。若没有常驻机器，请遵循 Grok Bot 以及隔离的 setup helper。根目录：/workspace/gbrain，数据位于 .gbrain 下。
在 Muse 中添加记忆	首选：通过 MCP 使用你自己电脑上的 brain。remote-mcp 会发布它（--funnel），然后 hosted harness access 会在 Muse 中安装私有交接配置。若没有常驻机器，请遵循 Muse。无论哪种方式，都要先确定其持久的用户文件位置。不要自行创建 MUSE.md、持久路径或原生 MCP 机制。
为其他已有 Agent 添加记忆	遵循 INSTALL_FOR_AGENTS.md；编码 Agent 教程涵盖 Claude Code 和 Codex。
连接已有的托管 brain	遵循 mcp-access 和 hosted harness access。为目标 harness 选择原生 OAuth/PKCE 或私有机器交接方式。
从其他设备、应用或云端 Agent 通过 MCP 使用 brain	遵循 remote-mcp：gbrain mcp expose 会将本地服务发布到 Tailscale tailnet（仅云端 Agent 使用 Funnel），然后 mcp-access / 托管访问会为每个使用方选择原生 OAuth 或私有机器交接方式。
显式创建带有身份和私有仓库的新个人 Agent	遵循 BOOTSTRAP_FOR_AGENTS.md。gbrain bootstrap 仅用于此明确请求。
显式配置带共享产物的按工作树代码引擎	遵循 topologies。brain 路由和 source 路由必须分别设置。

如果意图不明确，默认为现有 Agent 添加记忆。仅询问选择安全目标所需的缺失信息，例如要连接哪个已有 brain，或哪个 Muse 目录是持久的。

第 2 阶段：检查、安装或修复

对于已有的安装，如果存在记录的绝对启动器路径，请使用它：

gbrain engine status --json
gbrain engine status --probe

这些命令在数据库停止运行时也能使用。用于检查引擎、配置来源、根目录和源。环境中的数据库/MCP 设置或工作目录挂载并不构成接管该数据库的授权。 仅设置 GBRAIN_HOME 并不能隔离所有路由。

对于 Grok Bot/Muse，请让安装辅助程序检查并隔离所选根目录。 不要在其外部再运行全局初始化。其回执会区分缺失、部分、格式错误和冲突的状态。修复时使用保留的 <root>/bin/gbrain-setup；接管和升级需要明确的选项。 切勿为了从初始化错误中恢复而替换现有记忆。

对于其他本地安装，在遵循标准分发版和无密钥初始化之前，请先解决冲突的路由：

bun install -g github:garrytan/gbrain#latest-stable
gbrain init --pglite --no-embedding

如果缺少 Bun，请先安装，参见 INSTALL_FOR_AGENTS.md。不要使用无关的 npm 包 gbrain，也不要在用户当前项目中运行 bun add。 本地/瘦客户端转换需要明确的意图，并需保留之前的配置。

必须选择搜索模式： 初始化可能会选择非交互式默认值，并打印一个带有 [AGENT] 标记的九格成本矩阵。请转达该矩阵，并在继续之前确认操作者的选择。请遵循 INSTALL_FOR_AGENTS.md 中的第 3.5 步；以打印出的矩阵为准，不要依赖记忆中的价格。示例性的模型 API 成本与harness订阅是分开的。此选择不会启用付费 API 或捕获功能。

如果用户明确希望使用 Postgres，请参阅 engines 或 postgres-adopt。--prefer-postgres 为可选项。 请向用户告知一次：在 Postgres 上，带有检出目录的源会以经典模式启动，此时检出目录是事实来源，Agent 以已提交文件的形式保存页面，然后运行 gbrain sync；直接保存需要托管模式（未绑定源）。 Supabase 使用数据库连接字符串，而不是 anon 密钥。请妥善保管凭据，不要将环境中的机密复制到文件配置中。

托管替代方案

跳过本地数据库初始化、导入和维护安装。请阅读 mcp-access。如果目标 harness 使用原生 OAuth/PKCE，请使用其原生路径：注册实际的重定向 URI 和认证方式，在客户端内发起 OAuth，并在所有者登录和同意过程中保留待处理请求。不要在仅支持 OAuth 的客户端中安装机器交接。

对于机器路径，所有者需通过已认证的管理 API，使用 gbrain mcp grant 和私有的 --credentials-out 文件来配置 memory-writer 授权。请使用实际的 harness 标识符。正在运行的 PGLite 服务必须使用其现有引擎；不要在第二个进程中打开正在运行的数据库。URL 或普通 OAuth 令牌并不具备管理权限。

将交接内容私下传递给目标 harness，然后在该处安装：

gbrain connect https://brain.example.com/mcp --harness codex \
  --credentials-file /absolute/private/agent-example.json --install

瘦 CLI 适配器还需要已验证的持久化 --root。请遵循适配器的重新加载说明，并阅读完整的托管指南。 不要仅为了让便捷的健康检查命令通过而授予 admin 权限。 委派需要明确的选择、绑定的工具、活跃的源和路径策略。新建委派的支出不受限制，并发数为 1；授予前请先说明此点。

第 3 阶段：挂载记忆指令

保留现有指令文件。通过实际 harness 支持的机制添加一个带标识的记忆章节。对于 Grok Bot/Muse，使用生成的 instructions/gbrain-skill.md；生成文件并不证明已激活。

该常驻指令必须包含以下内容：

1. 在回答个人或持续进行中的工作相关问题前，先调取相关的已保存上下文。
2. 保存用户明确要求记住的内容，并记录来源及目标 brain/source。
3. 修正前先读取已存记录；让旧事实退役，保存更正内容，并进行验证。
4. 使用 forget 将内容从活跃记忆中撤回。历史记录、源材料和备份可以保留。
5. 自动捕获需要用户主动开启；付费增强与任务委派各自需要单独授权。
6. 如存在已记录的绝对路径启动器，则使用它。每项声称的变更都要通过实际调用进行验证。

Source 用于组织记忆；它们并不能隔离共享本地文件或凭据的 Agent。应保留用户原有的记忆与身份。

第 4 阶段：验证实际可用的功能

遵循所选指南中的命令。保存一条随机且无害的测试事实并附上来源，保留返回的 ID，然后在单独的调用中读回。修正该事实，撤回这条测试事实，并验证活跃调取中已不再包含它。在重试前，先核对丢失的变更响应。

运行 gbrain doctor --json 进行诊断。缺少可选的 embeddings 意味着该能力未配置，并不代表应添加付费密钥。健康评分或进程成功退出本身都不能证明记忆的完整往返流程有效。

对于托管客户端，使用私有凭据文件运行 gbrain mcp verify。应分别报告传输、认证、权限、读写、清理和 worker 检查的结果。总体结果为 partial（退出码 2）表示缺少原生证据。

在实际 harness 中打开新对话，要求其在不重复内容的前提下给出第二条随机测试事实，并观察已记录的启动器或 MCP 调用。如果 harness 不可用，则将此项检查标记为未验证。清理测试夹具，并按 ID 报告任何清理失败的记录。

可选能力与维护

仅处理用户明确请求的能力：

能力	下一步
导入选定的笔记或聊天导出文件	确认所选来源；参照 ingest 或 conversation archive 操作。不要扫描并导入任意目录。
连接账户	参照 chat connectors 或 Google setup，并遵守其中的凭据与授权边界。
自动采集对话	用户选择加入后，参照 signal detector 操作。不启用它时，回忆和显式记忆功能仍可正常使用。
付费检索或增强	单独配置所选能力及预算。已有的 API 密钥并不代表授权产生费用。
定时维护	对于 Agent 内安装，复用生成的例程 ID 和绝对启动器路径；先以有界的 doctor --fast --json 开始。观察原生激活情况。托管客户端则使用宿主已有的调度。
同步选定的文件源	参照 live sync。免密钥同步使用 --no-pull --no-embed；不要隐式添加 embedding 或 worker。
稍后导入更多数据	将 cold start 作为可选的下一步提供；不要自动启动。
升级	参照 gbrain-upgrade 以及安装记录的修复/升级策略操作。

事实、更正、任务和账目可能只存在于数据库中。 Git 克隆并不是完整的备份。对于 PGLite，请使用 私有备份与恢复流程。 将整个归档视为敏感数据；复制到虚拟机之外的副本需要明确的目标位置。恢复时应还原到一个不存在的新根目录，然后再显式地重新挂接外部根目录、连接器和调度任务。

错误恢复

故障	下一步操作
数据库无法连接	运行 gbrain engine status --probe，然后运行 gbrain db-repair；在授权的修复范围内应用安全的修复。
Agent 内安装部分完成	运行回执中给出的确切恢复命令；保留已完成的阶段和记忆。
PGLite 忙碌	等待正在运行的所有者完成，然后重试。切勿移除正在使用中的锁。
配置格式错误或存在冲突	报告冲突及预期目标；不要重新初始化，也不要覆盖无关设置。
托管端交接信息丢失	在宿主上恢复交付；区分访问令牌丢失与客户端密钥丢失。
原生指令或例程不可用	保留内容，并报告剩余的激活步骤。
可选的健康检查不可用	说明缺失的能力；不要悄悄扩大授权、支出或连接器访问权限。

失败时的处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或提示块，请遵循 agent operator protocol。针对本技能的具体说明：

• gbrain init 会打印包含检索模式成本矩阵的 [AGENT] 块：需转达给用户，并在继续之前获得操作者的选择。
• 初始化出错：切勿为了恢复而替换已有记忆。运行 gbrain doctor --json 并遵循其中的 fix。
• gbrain mcp verify 报告整体状态为 partial（退出码 2）：说明原生证据缺失；应表明激活尚未验证，而不是声称其可以正常工作。

反模式

• 在常规记忆设置过程中替换现有 Agent 的身份，或创建私有仓库。
• 将环境配置、可用的 API 密钥或一次成功的探测，视为采用数据或产生开销的许可。
• 为提高健康评分而自动启用捕获、导入无关文件，或安装 worker。
• 为修复部分安装而重新初始化记忆，移除正在使用的锁，或在常规授权修复过程中轮换凭据。
• 在未经观察的情况下宣布原生激活或跨对话召回已完成。

输出格式

报告实际的根目录、数据库、数据源或托管端点、已安装版本、记忆往返结果、指令激活情况、跨对话证据以及清理情况。列出待完成的步骤及确切的修复操作。对凭据进行脱敏处理。

仅宣布已观察到的阶段为完成。命令行测试、计划任务文件、流畅的回答、HTTP 响应或作业 ID 均无法证明完整的原生体验已经实现。