---
slug: "gbrain-guide"
source_type: "clawhub"
source_url: "https://clawhub.ai/skills/gbrain-guide"
repo: ""
source_file: "description"
---
---
name: gbrain-guide
description: 指导 agent 规范操作 GBrain 本地知识库（经 MCP 接入 WorkBuddy）。涵盖 GBrain 概念与安装形态、分类规范（路径前缀→类型）、资料入库、链接/标签关联、schema pack 切换、健康度治理、大库分批处理与 Obsidian 联动。当涉及"把资料存进 GBrain / 用 GBrain 检索 / 整理知识库 / gbrain MCP 调用"时加载。
agent_created: true
---

# GBrain 知识库操作指南（agent 行为准则）

## 0. 与其他 skill 的分工
本地可配合市场 skill `build-a-self-updating-agent-memory-graph-with-gbrain`（偏**概念与安装**：GBrain 是什么、`gbrain init --pglite`、三种形态、时间轨迹/创始人评分卡、生产案例）。**本 skill 是它的实操补充**——讲 agent 具体怎么调 MCP 工具、怎么分类、怎么处理大库、怎么治理健康度。两者分工不重复：先看那个建认知，看本 skill 落地操作。

## 1. GBrain 是什么
- 开源「个人知识大脑」，由 Y Combinator 总裁兼 CEO Garry Tan 构建，用于运行 AI 代理的生产知识底座。
- 已本地运行，并**通过 MCP 接入 WorkBuddy**（所有工具以 `mcp__gbrain__` 前缀暴露，70+ 工具）。
- 职责：存储、解析、向量化（embedding）、混合检索（向量+关键词+图谱+RRF 融合）、实体链接、关联图。
- 支持的资料形态：Markdown、Word、PDF、Excel/CSV、Org-mode、图片；**视频/音频暂不支持**（需先 Whisper 转写文本再入库）。

**关键认知（务必先读）**：GBrain 只是底座，必须按规范使用，否则会变成一个 flat 文档桶。一个未规范使用的 brain 常见实测状态（示例，gbrain-base@1.0.0，引擎 pglite）：
- 大量 page **全部 orphan**（无类型匹配 / 未归类的原始资料）
- link_coverage = 0、timeline_coverage = 0（没建任何知识关联）
- embed_coverage = 1（chunk 已全部向量化，检索可用）
- brain_score 偏低（满分 100，离"健康知识库"差距大）

即：资料进来了，但没分类、没关联，检索价值被严重浪费。本 skill 的每一节都在避免这种状态。

## 2. 安装与运行形态
- 免 Docker 安装：`gbrain init --pglite`（约 2 秒，无服务器、无 Docker，PGLite = WASM 版 Postgres + pgvector）。
- Windows + Bun 有已知坑，生产规模建议用 **Docker Postgres + pgvector** 扛量。
- GBrain 以三种形态运行，按需选用（详见参考 skill 的三种形态说明）。
- 开启官方 agent 指导 skill：在 GBrain 机器执行 `gbrain config set mcp.publish_skills true`，之后 `list_skills` / `get_skill` 可拿到 GBrain 官方维护的、比本 skill 更权威的 agent 指导。

## 3. 分类规范（最重要）
GBrain 通过 **schema pack** 定义「页面 slug 的路径前缀 → page 类型」映射。默认 `gbrain-base@1.0.0`：**27 种 page 类型 + 12 种 link 类型**。

**入库铁律：资料放进什么前缀文件夹，就自动归哪类。** 不要丢原始路径（如 `6.ros2系列教程/...` 这种无规范前缀的目录），否则 GBrain 一股脑全标成 `source` 原始资料——这正是 page 全 orphan 的常见根因。

常用类型与路径前缀（来自 gbrain-base 实测）：
| 类型 | 路径前缀 | 用途 |
|---|---|---|
| source | source/, sources/ | 原始资料（默认兜底） |
| note | note/, notes/ | 笔记 |
| project | project/, projects/ | 项目 |
| person | person/, people/ | 人物 |
| company | company/, companies/ | 公司 |
| deal | deal/, deals/ | 交易/投资 |
| concept | wiki/concept/, wiki/concepts/ | 概念 |
| guide | wiki/guide/, wiki/guides/ | 指南 |
| analysis | wiki/analysis/ | 分析 |
| hardware | wiki/hardware/ | 硬件 |
| architecture | wiki/architecture/ | 架构 |
| writing | writing/ | 写作 |
| media | media/ | 媒体 |
| email | email/, emails/ | 邮件 |
| meeting | meeting/, meetings/ | 会议 |
| conversation | conversation/, conversations/ | 对话 |
| atom | atom/, atoms/ | 原子笔记 |
| extract_receipt | extracts/ | 抽取/收据 |
| calendar-event | cal/, calendar/ | 日历事件 |
| event | life/events/ | 生活事件 |
| diary | life/diary/ | 日记 |
| yc / civic / slack | yc/, civic/, slack/ | YC / 市政 / Slack |

完整 27 种类型 + 精确前缀：用 `mcp__gbrain__schema_explain_type(type=xxx)` 或 `mcp__gbrain__schema_stats` 查询；当前 pack 的 link 类型用 `schema_stats` 看 12 种。

**通用场景建议映射**（按自己领域替换）：
- 技术文档/教程 → `wiki/architecture/`、`wiki/hardware/`、`wiki/guide/`
- 概念解释 → `wiki/concept/`
- 项目资料 → `project/`
- 读书/笔记/资讯沉淀 → `note/`、`atom/` 或 `wiki/analysis/`

## 4. 入库工作流
1. **定位资料根目录**：先确认本地资料根目录的绝对路径，确保磁盘空间充足（索引 + 资料需预留数倍空间）。
2. **按前缀规整**：把文件移动到对应前缀路径，GBrain 自动分类。宁可先分大类，也不要堆 `source/`。
3. **触发入库**：`mcp__gbrain__sources_add` / `entry_import_content` / `put_page`（按资料形态选；Markdown 直接 put_page，PDF/Word 走 sources_add）。
4. **验证**：`mcp__gbrain__get_stats`、`mcp__gbrain__get_health` 看 embed_coverage（应=1）与 orphan 数（应趋近 0）。
5. **分批**：大规模资料（如数十 GB）不要一次性灌，按 5–10G 小批，避免 embedding 排队过长、便于中途纠错。

## 5. 建关联（GBrain 真正价值）
若 link_coverage=0，等于没建知识网，检索只能命中孤立片段。
- 用 `mcp__gbrain__add_link`（12 种 link type）连接「教程 → 项目 → 概念」
- 用 `mcp__gbrain__add_tag` 打标签
- 用 `mcp__gbrain__get_links` / `mcp__gbrain__traverse_graph` 验证关联是否形成网络

## 6. Schema Pack 切换
默认只用 base。内置还有 `gbrain-engineer`（代码/硬件更贴）、`gbrain-creator`、`gbrain-everything` 等可选。
- `mcp__gbrain__list_schema_packs` 看可选
- `mcp__gbrain__reload_schema_pack` 切换
- 技术/工程场景优先评估 `gbrain-engineer`

## 7. 健康度治理（定期跑）
- `mcp__gbrain__get_health`：brain_score、embed_coverage、orphan 数、link 覆盖率
- `mcp__gbrain__schema_review_orphans`：列出无类型匹配的页面（即被错归 source 的）
- `mcp__gbrain__schema_lint`：lint 当前 pack
- `mcp__gbrain__run_onboard`：自动体检/修复（admin 权限）

目标：brain_score 向 100 收敛、orphan→0、link_coverage 显著提升。

## 8. WorkBuddy MCP 接入速查
- 连接：GBrain 暴露 MCP server，WorkBuddy 已接入（`mcp__gbrain__*`）
- 检索：`search` / `query` / `recall` / `get_chunks`
- 写入：`put_page` / `entry_import_content` / `sources_add`
- 图遍历：`traverse_graph` / `get_links`
- 治理：`get_health` / `schema_review_orphans` / `run_onboard`
- 分类规范：`schema_explain_type` / `schema_stats` / `get_active_schema_pack`

## 9. 与 Obsidian 联动（可选）
GBrain 是检索层（查得到），Obsidian 做下游笔记沉淀（理得清）。
- 流：GBrain 检索相关片段 → agent 产出结构化笔记 → 存 Obsidian（纯 Markdown，agent 易读、易维护）
- 视频：少量视频先用 Whisper-GPU（若有 NVIDIA 独显）转写 → 文本入库

## 10. 大库落地要点（汇总）
- 视频占比小（基本文档）→ GBrain 直接吃，少量视频走 Whisper 转写
- 资料留本地（隐私），embedding/LLM 可走云端 API（速度优先）
- 分批 5–10G，先 pilot 小批量验证规模检索，再全量
- 前缀规整先行，别堆 source/
- 入库后必跑健康度治理，把 orphan/link 补起来

---
本 skill 为实操层，配合市场 skill `build-a-self-updating-agent-memory-graph-with-gbrain`（概念/安装层）使用。