brain-ops

Brain Operations——环境上下文层

在回复前回忆相关上下文。保存明确请求及其来源；在用户选择启用前，自动捕获处于关闭状态。阅读此技能不会启用捕获、委派或付费增强。仅限聊天的指令会禁止本轮写入，即使已启用常驻捕获也是如此。

约定： 查阅 skills/conventions/brain-first.md，了解查询链和可复制的检索筛选条件。 约定： 查阅 skills/conventions/quality.md，了解引用和反向链接规则。 记忆动词（MEMORY_VERBS v1，gbrain ≥ 0.43）。 通过 MCP 进行读写时，优先使用五个核心记忆动词：remember(fact, provenance, ttl?) 用于保存单条持久事实（必须提供来源 provenance；会去重并替代旧事实）；recall(query | entity, budget_tokens) 用于按预算打包读回记忆；entity(name) 用于获取无需大模型参与的实体卡片；synthesize(question) 用于开销较大的跨页面综合回答；forget(id) 用于撤回活跃记忆（历史、源材料和备份可能仍然保留）。context_pack 和 delta 补全七动词接口。当你已经有一条成型的事实时，使用 remember 而不是 extract_facts；put_page / add_link / add_timeline_entry 仍是页面与图谱的写入路径。若接口中没有这些动词，则回退到经典操作。约定见：docs/protocol/MEMORY_VERBS_v1.md。

预算紧张时的页面问题： 请明确使用 recall({query: "zebra telescope", budget_tokens: 75, budget_policy: "query_first"})，使排序后的页面证据优先于近期事实进行打包。命令行： gbrain recall --query 'zebra telescope' --budget-tokens 75 --budget-policy query_first --json。 以实体优先、事件/会话过滤和事实聚焦的问题，应保持其现有的事实优先路径；不要更改 context_pack。成本按字符数估算，超大的首个条目会被直接丢弃，不会跳过或截断。若结果为空，请先阅读 budget_packing，再判断是否缺少记忆。MCP 请求与调用示例见 skills/query/SKILL.md。指引本身并不等同于原生 harness 已激活：在观察到新会话发出已选择加入的调用之前，采用情况仍未经验证。

选择能看到目标可见性的读回路径： 受信任的本地命令行调用方可以读回并撤回私有事实。所有 MCP 调用方（包括 stdio），以及连接到 MCP 的轻量命令行，目前只能读回和撤回世界可见事实。用户要求记住某内容，并不授权将真实的私人信息变为世界可见。若可用，请对私有记忆使用受信任的本地写入/读回路径。若只能远程访问，私有写入的成功回执仅确认已存储，私有读回仍未经验证；请说明这一限制，以及进行私有读回或撤回所需的受信任本地路径。不要为了让验证通过而扩大可见性或申请更宽泛的 OAuth 范围。进行 MCP 连接测试时，仅可在用户授权下使用无害的合成 visibility: "world" 测试数据，保留其 ID，并在事后撤回。

结果中的 <REDACTED:pattern>（例如 <REDACTED:url_credentials> 或 <REDACTED:high_entropy_assignment>）表示知识库在该处保存了形似凭证的值，且本次响应已将其隐去；已存储的页面并未改变。请告知用户被隐去的是哪一类值，并说明该值可在知识库主机上读取。不要为恢复该值而重试其他操作，也不要猜测并回显其内容。用户要求你 remember 的凭证，按设计会对远程读回隐藏：所有 MCP 调用方（包括 stdio），以及连接到 MCP 的轻量命令行，都属于远程访问，因此只有在知识库主机上运行 gbrain recall，才会按原样显示该凭证。文档见： docs/guides/write-refusals.md#secret-scan-refusals-and-redaction。

无密钥知识库： 当 extract_facts 返回 skipped: extraction_unavailable 时，由你自己充当抽取器：从该轮对话中自行提取事实，并通过 remember 逐条写入，设置 kind（event | preference | commitment | belief | fact，这五个是冻结的协议枚举；抽取器和数据库中使用的 idea 类型不在其中），可见性则采用信封中 agent_action 指定的值（默认 private，请明确固定；remember 默认为 world）。也可以在实体页面上编写 ## Facts 代码块。skipped: extraction_failed 信封（服务端抽取器在该轮出错，reason 说明原因）同样建议对该轮采用手动 remember 的回退方式；未来的写入仍会保持自动抽取。

合约

此技能保证：

• 在任何外部 API 调用之前检查 Brain（优先查询 Brain）
• 明确的保存请求和选择加入的入站信号会触发 READ → WRITE 循环；信息补充需要单独配置的授权
• 每次对外响应都会检查 Brain，查找相关上下文
• 每条写入的事实都注明来源（内联 [Source: ...] 引用）
• 用户的直接陈述具有最高数据权威性
• 每次写入 Brain 时都维护反向链接（铁律）

铁律：反向链接（强制）

每当提及有 Brain 页面的人或公司，都必须从该实体页面创建指向提及它的页面的反向链接。提及未链接，就意味着 Brain 已损坏。格式请参阅 skills/conventions/quality.md。

阶段

阶段 1：优先查询 Brain（强制）

在使用任何外部 API 研究人物、公司或主题之前：

1. gbrain entity "<name>"（v0.43+）——针对一个已知人物／公司／项目，获取完整卡片（描述、别名、未结事项、近期事件、关联、反向链接／事实计数）。不调用 LLM，耗时不到 100 毫秒。对于已知实体查询，这一次调用即可替代步骤 2–6；近似匹配时会返回建议。
2. gbrain search "name"——精确词元查找现有页面（轻量混合检索，不扩展）
3. gbrain query "natural question about name"——概念／全景类问题优先使用此命令（语义匹配加重排可找回同义表达；结果不足时，--expand 会添加 LLM 改写；search 返回非零结果并不能证明结果完整）
4. gbrain get <slug>——如果知道 slug，则读取完整页面
5. 检查反向链接：谁引用了此实体？
6. 检查时间线：近期有哪些涉及此实体的事件？

Brain 几乎总能提供一些信息。外部 API 用于填补空缺，而不是从头开始。 先使用 gbrain 搜索，再直接读取、grep 或查询 Brain 文件；筛选器 （--types、--match keyword、query --since/--until、--source、--json） 见 Brain 优先约定中的“检索：优先使用 gbrain”部分。

⚠️ 切勿用浅层 ls 来界定或统计语料库——请查询 gbrain 或使用 find。 联合来源通常会同时采用多种目录结构——扁平的旧版结构，以及按日期嵌套的 meetings/YYYY/MM/ 结构。非递归的 ls dir/*.md 只能看到其中一种，因此会严重少计。真实案例：对某个来源的 meetings/ 执行浅层 ls，只统计到 132 个文件，且几乎全是用户的文件，于是误以为这就是全部语料库——遗漏了嵌套在 meetings/YYYY/MM/ 下的数千份记录。统计／界定 Brain 语料库：

• **最佳做法：**使用 gbrain sources list（显示每个来源已索引的页面数）和 gbrain query。gbrain 能正确索引所有联合来源；应信任其索引，而非文件系统。
• **如果必须访问文件系统：**使用 find <dir> -name '*.md' | wc -l，绝不要使用 ls *.md。然后梳理目录布局：find <dir> -name '*.md' | sed -E 's#(.*/)[^/]+$#\1#' | sort | uniq -c。
• 问题绝不会是“gbrain 看不到该来源”——几乎总是浅层的文件系统 glob 所致。在相信偏低的计数之前，先对照 gbrain sources list 验证。

阶段 1.5：分析查询（gbrain think）

对于需要综合分析、结合时间背景或给出分析性回答的问题—— 不只是“找到页面”，而是“回答问题”：

1. 使用 gbrain think "<question>"——跨页面、takes 和图谱进行多跳综合。时间相关问题会转入轨迹分析；其他问题则由 LLM 综合并生成带引用的回答，同时分析冲突和信息缺口。 返回的是有依据的回答，而不只是匹配页面列表。
2. 最适合回答：“acme-example 上次融资是什么时候”“3 月份的 ARR 是多少”“自 Q1 以来发生了哪些变化”“alice-example 的联合创始人是谁，他们在做什么”“总结我们与 acme-example 的关系”。
3. 找不到匹配的时间线事实时，会平稳回退到标准检索。
4. 成本：每个问题都会调用 LLM——这是成本较高的路径。只需要 slug 或快速检查上下文的简单页面查询，请使用 query。

Phase 2: Authorized Capture (READ → WRITE)

For an explicit save request, or a message within the user's opted-in capture scope that has no chat-only restriction:

1. Detect entities：识别提到的人物、公司和交易
2. Load brain pages：在回复前读取已有页面以获取上下文
3. Identify new information：这条信号带来了哪些页面尚未掌握的新信息？
4. Write it back：用新信息、时间线条目和来源引用更新 brain 页面
5. Create if missing：若内容值得记录，则保存所提供的信息并附上出处；仅在获得单独授权时才调用丰富化

为用户的直接陈述标注 [Source: User, YYYY-MM-DD]。 没有捕获授权时，可以在当前对话中使用这些信息，但不得持久化保存。明确的"记住"请求不等于授权持续捕获。

Phase 2.5: Structured Graph Updates (auto-link)

"Auto-link" 对账会从页面中提取实体引用，并以推断出的关系类型将其写入图谱（links 表）；过时的链接（页面文本中已不再出现的引用）会被移除。由哪一方执行取决于写入路径：

• Trusted local writes（gbrain put、gbrain capture、gbrain call put_page）会内联执行自动链接，并返回 auto_links: { created, removed, errors }。
• **MCP callers（stdio 和 HTTP）**会返回 auto_links: { skipped: "remote", hint } 与 auto_timeline: { skipped: "remote" }。正文中的 wikilink 仅保存为文本。 随后的提交后效果会为同一来源中已存在的页面添加普通 mentions 边（auto_links.mention_links: "queued"；执行 gbrain config set mcp.remote_auto_links off 可关闭该行为）。类型化边、frontmatter 边和时间线边不在此范围内：stdio 模式下的 gbrain serve 会通过其维护扫描（启动时以及每 10 分钟空闲触发一次）异步对账这些边。 gbrain serve --http 不会自行扫描——请使用 gbrain sweep --once（通过 IPC 委托给正在运行的 serve）或 gbrain extract links --source db 按需对账。 对于需要立即生效的关系，请使用 add_link，但会议出席关系除外，它由自动链接根据会议页面推导。未受信任的正文文本可能植入提升排名的边，因此内联路径仅限本地使用。
• 推断的链接类型：attended、works_at、invested_in、founded、advises、source（frontmatter）、mentions（默认）。在当前激活的 schema pack 未覆盖出席规则的情况下（即 gbrain init 设置的 gbrain-base-v2），attended 仅来自会议页面中明确的参会人名单（其 Attendees: 行或 attendees: frontmatter），且方向为 person -> meeting；覆盖该规则的 pack（如较早的 gbrain-base）会自行设定规则与方向。
• 禁用方法：gbrain config set auto_link false。默认开启。
• 带有具体日期的时间线条目仍需显式执行 gbrain timeline-add（或通过 gbrain extract timeline --source db 批量处理）。

Phase 3: On Every Outbound Response (READ → PULL → RESPOND)

在回答任何关于人物、公司或主题的问题之前：

1. Check the brain：读取相关页面
2. Pull context：使用编译后的 truth 与近期时间线
3. Respond with context：brain 让每一个回答都更好

当 brain 页面存在时，不要仅凭通用知识作答。

Phase 4: Optional Enrichment

丰富化是用户可选的额外操作。仅仅提及某个实体、分享某个链接，或开启捕获选项，都不构成外部调研、付费调用或委派任务的授权。应遵循用户明确的导入/丰富化请求，或其已保存的范围与支出策略。在没有此类授权的情况下，只需调取已有上下文，并仅保存用户授权保留的所提供信息。

仅当委派已获授权且运行环境支持时，才使用后台 Agent。汇报观察到的结果，不要声称某个生成的例行程序已经运行。

输出格式

在回复中使用检索到的上下文并注明引用。只有在读回确认后才确认已授权的写入；如果用户没有请求或选择写入，不要仅为生成记忆更新而持久化对话。

跨来源引用格式（v0.18.0+）

当一个脑包含多个来源（wiki、gstack、yc-media 等）时，每条引用都必须包含来源 ID：[source-id:slug]。示例：

你告诉过我重试预算方案——参见 [wiki:topics/resilience] 和 [gstack:plans/retry-policy]，了解相关出处。

规则：

• 键是 sources.id（不可变），绝不能使用 sources.name（可变显示名称）。
• 单来源脑仍可使用 [default:slug]，也可以省略前缀以保持向后兼容。
• search、query、get_page、list_pages 返回的每个页面负载都带有 source_id——引用时务必使用它，绝不可猜测。

如果搜索结果的 source_id: "gstack" 且 slug: "plans/foo"，引用格式为 [gstack:plans/foo]。规则就是这么简单。

发生错误时

对于任何 gbrain 错误 code、退出代码、[AGENT] 块或通知块，请遵循Agent 操作员协议。此技能的具体要求如下：

• put_page 返回 revision_conflict：重新读取页面，将更改合并到新文本中，并使用新修订版本保存。write_pending（退出代码 10）：在声称写入成功前，轮询 get_write_request（gbrain write-request <request_id>）。
• put_page（或 capture、标签、时间线）返回 owner_unavailable，且 detail: unbound_source：这是一个经典的 Postgres 脑。在来源的检出目录中将页面写入文件、提交，然后运行 gbrain sync --source <id>；如果你在远程环境中，请将这三个步骤告诉用户。绝不要认领来源或切换模式来完成写入（参见Agent 操作员协议）。
• 写入被机密扫描或 slug 围栏拒绝（permission_denied）：不要通过删除或重命名来规避；告诉用户拒绝了什么以及原因（参见 docs/guides/write-refusals.md）。
• recall / search 在返回内容为空时带有降级通知或 search_degraded：说明脑目前仅在搜索关键词，而不是说没有保存任何内容。
• 通过 MCP 遇到 insufficient_scope / scope_denied：连接缺少该权限范围。告知用户；绝不要仅为让写入通过而索要更广泛的令牌。

反模式

• 未先检查脑就回答有关人物或公司的问题
• 未先检查脑就使用外部 API
• 写入事实时未附带行内 [Source: ...] 引用
• 为了补充信息而阻塞回复
• 用权威性较低的来源覆盖用户的直接陈述
• 为不重要的实体创建脑页面
• 为同一实体创建重复页面——创建前务必先检查：运行 gbrain entity "<name>"（可捕获别名和近似匹配），然后使用名称变体执行 query

使用的工具

• search — 低成本混合搜索（向量 + 关键词，不扩展）
• query — 用于概念/全局概览问题的混合搜索（--expand 会添加 LLM 多查询扩展）
• get_page — 读取脑页面
• put_page — 创建或更新脑页面
• add_link — 交叉引用实体
• add_timeline_entry — 记录事件
• get_backlinks — 检查哪些页面引用了某个实体
• sync_brain — 将更改同步到索引