brain-ops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Brain Operations — The Ambient Context Layer

Brain操作 — 环境上下文层

The brain is not an archive. It is a live context membrane that every interaction flows through in both directions.

Convention: See
skills/conventions/brain-first.md
for the 5-step lookup protocol. Convention: See
skills/conventions/quality.md
for citation and back-link rules.

Brain并非一个存档库，而是一个动态的上下文膜，所有交互都会双向流经此处。

约定： 请查看
skills/conventions/brain-first.md
了解5步查询协议。 约定： 请查看
skills/conventions/quality.md
了解引用和反向链接规则。

Contract

契约

This skill guarantees:

Brain is checked BEFORE any external API call (brain-first lookup)
Every inbound signal triggers the READ → ENRICH → WRITE loop
Every outbound response checks brain for relevant context
Source attribution on every fact written (inline
```
[Source: ...]
```
citations)
User's direct statements are highest-authority data
Back-links maintained on every brain write (Iron Law)

本Skill保证：

在调用任何外部API前先检查Brain（优先查询Brain）
每个入站信号都会触发「读取 → 丰富 → 写入」循环
每个出站响应都会检查Brain以获取相关上下文
写入的每条事实都带有来源归因（行内
```
[Source: ...]
```
引用格式）
用户的直接陈述是最高权威数据
每次Brain写入都会维护反向链接（铁则）

Iron Law: Back-Linking (MANDATORY)

铁则：反向链接（强制性要求）

Every mention of a person or company with a brain page MUST create a back-link FROM that entity's page TO the page mentioning them. An unlinked mention is a broken brain. See

skills/conventions/quality.md

for format.

任何提及拥有Brain页面的个人或公司的内容，必须创建一条从该实体页面指向提及页面的反向链接。未链接的提及会导致Brain功能异常。格式请查看

skills/conventions/quality.md

。

Phases

阶段

Phase 1: Brain-First Lookup (MANDATORY)

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

Before using ANY external API to research a person, company, or topic:

```
gbrain search "name"
```
— keyword search for existing pages

gbrain query "natural question about name"

— hybrid search for context

```
gbrain get <slug>
```
— if you know the slug, read the full page
Check backlinks: who references this entity?
Check timeline: recent events involving this entity

The brain almost always has something. External APIs fill gaps, not start from scratch.

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

```
gbrain search "name"
```
— 对现有页面进行关键词搜索

gbrain query "natural question about name"

— 混合搜索获取上下文

```
gbrain get <slug>
```
— 若已知slug，读取完整页面
检查反向链接：哪些实体引用了该对象？
检查时间线：涉及该实体的近期事件

Brain几乎总能提供相关信息。外部API仅用于填补空白，而非从零开始。

Phase 2: On Every Inbound Signal (READ → ENRICH → WRITE)

阶段2：处理每个入站信号（读取 → 丰富 → 写入）

Every message, meeting, email, or conversation that references a person or company:

Detect entities — people, companies, deals mentioned
Load brain pages — read existing pages for context before responding
Identify new information — what does this signal tell us that the page doesn't know?
Write it back — update the brain page with new info + timeline entry + source citation
Create if missing — if notable and no page exists, create via enrich skill

User's direct statements are the highest-value data source. Write them to brain pages immediately with attribution

[Source: User, YYYY-MM-DD]

每条提及个人或公司的消息、会议记录、邮件或对话：

识别实体 — 提取提及的人物、公司、交易
加载Brain页面 — 在回复前读取现有页面获取上下文
识别新信息 — 该信号包含哪些页面中没有的内容？
写回Brain — 更新Brain页面，添加新信息、时间线条目和来源引用
缺失则创建 — 若实体值得记录但无对应页面，通过enrich skill创建

用户的直接陈述是最高价值的数据源。 需立即写入Brain页面，并标注归因

[Source: User, YYYY-MM-DD]

。

Phase 2.5: Structured Graph Updates (automatic)

阶段2.5：结构化图谱更新（自动执行）

Every

put_page

call automatically extracts entity references and writes them to the graph (

links

table) with inferred relationship types. Stale links (refs no longer in the page text) are removed in the same call. This is "auto-link" reconciliation.

No manual
```
add_link
```
calls needed for ordinary page writes.
Inferred link types:
```
attended
```
(meeting -> person),
```
works_at
```
,
```
invested_in
```
,
```
founded
```
,
```
advises
```
,
```
source
```
(frontmatter),
```
mentions
```
(default).
The
```
put_page
```
MCP response includes
```
auto_links: { created, removed, errors }
```
so the agent can verify outcomes.
To disable:
```
gbrain config set auto_link false
```
. Default is on.
Timeline entries with specific dates still need explicit
```
gbrain timeline-add
```
(or batch via
```
gbrain extract timeline --source db
```
).

每次

put_page

调用都会自动提取实体引用，并将其写入图谱（

links

表），同时推断关系类型。页面文本中不再存在的陈旧链接会在同一调用中被移除。这就是「自动链接」协调机制。

普通页面写入无需手动调用
```
add_link
```
推断的链接类型：
```
attended
```
（会议→个人）、
```
works_at
```
、
```
invested_in
```
、
```
founded
```
、
```
advises
```
、
```
source
```
（前置元数据）、
```
mentions
```
（默认）

put_page

的MCP响应包含

auto_links: { created, removed, errors }

，以便Agent验证结果

如需禁用：
```
gbrain config set auto_link false
```
。默认开启。
带有特定日期的时间线条目仍需显式调用
```
gbrain timeline-add
```
（或通过
```
gbrain extract timeline --source db
```
批量处理）

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

阶段3：处理每个出站响应（读取 → 提取 → 回复）

Before answering any question about a person, company, or topic:

Check the brain — read relevant pages
Pull context — use compiled truth + recent timeline
Respond with context — the brain makes every answer better

Don't answer from general knowledge when a brain page exists.

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

检查Brain — 读取相关页面
提取上下文 — 使用整合的事实数据+近期时间线
结合上下文回复 — Brain能让每个回答更精准

当存在对应Brain页面时，请勿仅凭通用知识作答。

Phase 4: Ambient Enrichment

阶段4：环境式丰富

This is not a special mode. This is the default. Everything the user says is an ingest event.

Person mentioned → check brain, create/enrich if needed (spawn background)
Company mentioned → same
Link shared → ingest it (delegate to idea-ingest)
Data shared → delegate to appropriate skill

Rules:

Never interrupt the conversation to do enrichment
Spawn sub-agents for anything that would slow down the response
Never announce "I'm enriching the brain" — just do it silently

这并非特殊模式，而是默认行为。用户所说的一切都是摄入事件。

提及个人 → 检查Brain，必要时创建/丰富页面（后台执行）
提及公司 → 同上
分享链接 → 摄入内容（委托给idea-ingest skill）
分享数据 → 委托给对应skill处理

规则：

绝不要为了执行丰富操作而打断对话
对于任何会拖慢响应速度的任务，启动子Agent处理
绝不要告知用户「我正在丰富Brain」—— 静默执行即可

Output Format

输出格式

No separate output. Brain-ops is an always-on behavior layer, not a report generator. The output is updated brain pages and enriched responses.

无单独输出。Brain操作是一个始终运行的行为层，而非报告生成器。输出为更新后的Brain页面和经过丰富的响应内容。

Cross-source citation format (v0.18.0+)

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

When a brain has multiple sources (wiki, gstack, yc-media, etc.), every citation MUST include the source id:

[source-id:slug]

. Example:

You told me about the retry budget approach — see [wiki:topics/resilience] and [gstack:plans/retry-policy] for where this came from.

Rules:

The key is
```
sources.id
```
(immutable), never
```
sources.name
```
(mutable display).
Single-source brains still write
```
[default:slug]
```
OR may omit the prefix for backward compat.
Every page payload returned by
```
search
```
,
```
query
```
,
```
get_page
```
,
```
list_pages
```
carries
```
source_id
```
— always use it when citing, never guess.

If a search result has

source_id: "gstack"

and

slug: "plans/foo"

, the citation is

[gstack:plans/foo]

. That's the whole rule.

当Brain包含多个来源（wiki、gstack、yc-media等）时，每条引用必须包含来源ID：

[source-id:slug]

。示例：

您曾提及重试预算方案 — 详情请查看 [wiki:topics/resilience] 和 [gstack:plans/retry-policy]。

规则：

使用
```
sources.id
```
（不可变）作为标识，绝不使用
```
sources.name
```
（可变显示名）
单一来源的Brain仍可写为
```
[default:slug]
```
，或为兼容旧版本省略前缀
```
search
```
、
```
query
```
、
```
get_page
```
、
```
list_pages
```
返回的所有页面负载都带有
```
source_id
```
— 引用时务必使用该值，切勿猜测

若搜索结果的

source_id: "gstack"

且

slug: "plans/foo"

，则引用格式为

[gstack:plans/foo]

。这就是全部规则。

Anti-Patterns

反模式

Answering questions about people/companies without checking the brain first
Using external APIs before checking the brain
Writing facts without inline
```
[Source: ...]
```
citations
Blocking the response to do enrichment
Overwriting user's direct statements with lower-authority sources
Creating brain pages for non-notable entities

未先检查Brain就回答关于个人/公司的问题
未检查Brain就调用外部API
写入事实时未添加行内
```
[Source: ...]
```
引用
为执行丰富操作而阻塞响应
用低权威来源覆盖用户的直接陈述
为非重要实体创建Brain页面

Tools Used

使用的工具

```
search
```
— keyword search
```
query
```
— hybrid vector+keyword search
```
get_page
```
— read a brain page
```
put_page
```
— create/update brain pages
```
add_link
```
— cross-reference entities
```
add_timeline_entry
```
— record events
```
get_backlinks
```
— check who references an entity
```
sync_brain
```
— sync changes to the index

```
search
```
— 关键词搜索
```
query
```
— 向量+关键词混合搜索
```
get_page
```
— 读取Brain页面
```
put_page
```
— 创建/更新Brain页面
```
add_link
```
— 实体交叉引用
```
add_timeline_entry
```
— 记录事件
```
get_backlinks
```
— 检查哪些实体引用了目标对象
```
sync_brain
```
— 将变更同步到索引