gbrain-guide

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

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（概念/安装层）使用。