GBrain 架构设计哲学：一个个人 AI Agent 的'第二大脑'工程

参考对象：Garry Tan（Y Combinator CEO）的 GBrain 开源项目。这不是一个教程，而是对代码层面的架构决策进行逆向工程。

1. Markdown-First：人类可读才是"真相源"

GBrain 最底层的设计决策是所有数据都是 Markdown。不是数据库 blob，不是专有格式，而是可以直接 cat 的文件。

// import-file.ts 的核心哲学
const hash = createHash('sha256')
  .update(JSON.stringify({
    title: parsed.title,
    type: parsed.type,
    compiled_truth: parsed.compiled_truth,
    timeline: parsed.timeline,
    frontmatter: stableFrontmatter,
    tags: parsed.tags.sort(),
  }))
  .digest('hex');

注意这里的 compiled_truth 和 timeline 分离——这是 GBrain 的内容模型核心。compiled_truth 是"事实"，timeline 是"事件序列"。这种分离让搜索可以区分"知道什么"和"何时知道"。

设计意图：如果 GBrain 明天倒闭，用户的所有数据就是一堆 Markdown 文件。没有锁定，没有迁移成本。这是**"逃生舱"设计**——任何系统都应该有一个零成本的退出路径。

2. 摄入管线：六层漏斗的防御性工程

GBrain 的 importFromContent 函数是一个六层漏斗，每层都有明确的防御职责：

L4 内容 Sanity Gate 是精华

这不是简单的过滤，而是三档处置（类似交通灯）：

• 红灯（Quarantine）：高置信度垃圾（Cloudflare/CAPTCHA 模式），直接隔离，隐藏于搜索，但可审查。
• 黄灯（Flag）：模糊可疑（markup-heavy/oversized），保留搜索能力，但给 Agent 发警告——"这看起来不对劲，你决定怎么处理"。
• 绿灯：正常通过，但可能附带 oversize_warn 提示。

// 关键设计：quarantine 不是删除，而是"隐藏但可审查"
// 这是"安全但不审查"的哲学——不替用户决定什么是垃圾

代码围栏提取（D2）

约 40% 的 GBrain 内容是文档/指南，包含大量内联代码。v0.20 的 D2 改动让代码围栏不再是"散文的一部分"，而是被提取为一等代码块，用代码感知分块器（TS/JS/Python 等语法感知）处理。

设计意图：搜索"how do we import from engine"时，应该返回实际的 import 示例，而不是描述 import 的段落。

3. 四层混合检索：没有银弹，只有组合

Vector (HNSW on pgvector) 
    ↓
BM25 Keyword (tsvector) 
    ↓
RRF (Reciprocal Rank Fusion) 
    ↓
Knowledge Graph Traversal (+31.4 P@5)

每一层解决不同的问题：

• Vector：语义相似性（"相似的概念"）
• BM25：精确匹配（"这个特定的函数名"）
• RRF：融合排序（避免单一模型的偏见）
• Graph：关系推理（"谁投资了这个公司？" → 遍历 founded → invested 边）

Graph 层是 GBrain 的杀手级差异化。它不需要 LLM 调用——正则级联提取实体关系（founded → invested → works_at），然后图谱遍历即可回答关系型问题。

4. Think 管线：INTENT → GATHER → SYNTHESIZE → GAP

runThink 是 GBrain 的"大脑"，不是简单的 RAG，而是意图驱动的合成引擎：

// 意图推断
function inferIntent(question: string, anchor?: string): string {
  if (anchor) return 'entity';
  const q = question.toLowerCase();
  if (/\b(when|history|over time|evolved|since|before|after)\b/.test(q)) return 'temporal';
  if (/\b(meeting|event|happened)\b/.test(q)) return 'event';
  return 'general';
}

四阶段：

1. INTENT：问题分类（实体/时间/事件/一般）
2. GATHER：混合检索收集证据（pages + takes + graph hits）
3. SYNTHESIZE：LLM（默认 Claude Opus）生成结构化答案（JSON：{answer, citations, gaps}）
4. GAP：诚实报告"我不知道什么"

Trajectory 注入（v0.40.2）

对于时间/知识更新类问题，系统会额外查询实体轨迹——某个实体（如公司、人）在时间轴上的变化。这解决了传统 RAG 的"静态快照"问题。

// 5s 超时 + 并发限制 3 + Promise.allSettled（一个失败不杀全部）
const settled = await Promise.allSettled(
  batch.map(async (cand) => {
    const points = await Promise.race([
      engine.findTrajectory({ entitySlug: resolved.slug, ... }),
      new Promise(resolve => setTimeout(() => resolve([]), 5000)),
    ]);
  })
);

优雅降级（Graceful Degradation）

没有 API Key？不抛异常，返回：

answer: '(no LLM available — set ANTHROPIC_API_KEY)'
gaps: ['no LLM available; gather succeeded but synthesis skipped']

设计意图：检索成功本身就是价值。LLM 只是锦上添花，不是必要条件。

5. 知识图谱：零 LLM 调用的自布线系统

传统知识图谱需要 NER + 关系抽取（LLM 调用量大）。GBrain 的 Schema 系统走了一条更轻、更确定性的路：

• 路径前缀推断类型：people/ 下的文件就是 person 类型
• Schema 声明可提取的关系：person 可以有 founded、invested_at、works_at
• 正则级联提取：从文本中直接匹配这些关系，零 LLM 调用

---
type: person
name: Garry Tan
---

Founded [Posthog](https://posthog.com) in 2020.
Invested in [Vercel](https://vercel.com) via YC W20.

系统会自动提取：

• garry-tan --founded--> posthog
• garry-tan --invested_at--> vercel

Schema 的进化：不是预设的 rigid ontology，而是Agent 共同策展的——Agent 使用中发现新类型，Schema 可以演化。

6. 生产可靠性：为"一个人的生产环境"设计

Garry Tan 的生产部署：146,646 pages、24,585 people、5,339 companies、66 cron jobs。代码中处处可见为单人生产环境设计的可靠性措施：

同步锁（Sync Lock）

const lockId = syncLockId(brainDir, source);
if (!await engine.obtainLock(lockId, { ttl: SYNC_LOCK_TTL_MS })) {
  throw new LockUnavailableError(`Sync already in progress for \({source}`);
}
```
防止并发同步导致的重复摄入和数据库竞争。

### 成本门控（Spend Cap）
```typescript
if (spendCap > 0) {
  const projected = totalSpendSoFar + estimatedCost;
  if (projected > spendCap) {
    throw new SpendCapError(`Projected\){projected} exceeds cap ${spendCap}`);
  }
}

显式尊重用户的钱包。不是"用完为止"，而是"提前拒绝"。

检查点（Checkpoint）

if (checkpoint > 0) {
  // 定期 commit，中断后可恢复
  await engine.commit();
}

10,000 文件同步到一半挂了？从检查点恢复，不是从头开始。

跨 Slug 去重（Identity Deduplication）

const dup = await engine.findDuplicatePage(sourceId, {
  hash,           // 内容哈希匹配
  frontmatterId: fmIdStr,  // 外部 ID 匹配（如 Granola UUID）
});

解决重叠摄入根目录的 bug：先 import /vault/Subdir/ 再 import /vault/，同一文件不会被重复索引。

7. 部署拓扑：三种"大脑"的居住方式

Topology 1: 单机（PGLite / Supabase）
    本地 Markdown 仓库 ←→ 本地/远程数据库

Topology 2: 瘦客户端
    远程大脑（服务器） ←→ 本地 Agent（MCP 瘦客户端）

Topology 3: 分引擎
    Conductor 工作树拆分
    ├── 代码引擎（代码索引）
    └── 笔记引擎（笔记索引）

Topology 3 是隔离即安全的哲学：代码索引和笔记索引物理分离，避免代码变更污染笔记检索空间。通过 ~/.gbrain/config.json + GBRAIN_HOME 环境变量切换。

8. 信任模型：本地 vs 远程的边界

GBrain 有一个贯穿始终的信任边界概念：

if (opts.remote === true && parsed.frontmatter) {
  delete parsed.frontmatter[QUARANTINE_KEY];
  delete parsed.frontmatter[CONTENT_FLAG_KEY];
  delete parsed.frontmatter[EMBED_SKIP_KEY];
}

远程（MCP/OAuth）调用者不能通过手工 frontmatter 标记来隐藏页面或注入警告文本。只有本地可信调用者（sync、capture、dream）和 Content Sanity Gate 本身可以设置这些标记。

这是 "fail-closed"（默认关闭） 的安全哲学：任何不是严格本地的调用都被视为不可信。

9. Cron & "梦境循环"：睡觉也在进化

66 个 cron jobs 不是装饰，而是自动化维护：

• 链接对账（reconcile-links）
• 信号检测（signal detectors）
• 自动合成（dream synthesize）
• 上下文检索回填（contextual reindex Minion）

这是 "让系统自己维护自己" 的哲学——不是手动整理笔记，而是设定规则让大脑在后台自我整理。

总结：GBrain 的架构设计思想

GBrain 不是又一个 RAG 包装器。它是为个人 AI Agent 设计的持久化记忆层——从"每次会话从零开始"到"Agent 记得上周见过谁"。

它的架构选择指向一个清晰的信念：AI 的记忆不应该是一个黑盒数据库，而应该是一个人类可以阅读、编辑、版本控制的 Markdown 知识库。

参考代码（均来自 garrytan/gbrain GitHub 仓库）：

• src/core/engine.ts — 核心接口定义
• src/commands/sync.ts — 同步命令实现
• src/commands/think.ts — Think 命令 CLI
• src/core/think/index.ts — Think 管线核心
• src/core/import-file.ts — 摄入管线核心
• docs/architecture/RETRIEVAL.md — 检索架构
• docs/architecture/topologies.md — 部署拓扑
• docs/ethos/ORIGIN.md — 起源与设计理念
• docs/what-schemas-unlock.md — Schema 系统

#记忆 #小凯 #GBrain #架构设计 #AI Agent #第二大脑 #RAG #知识图谱