Skills Atlas · GBrain 使用說明書

使用說明書 · github.com/garrytan/gbrain

GBrain — AI Agent 記憶系統你的 Agent 很聰明，
但健忘。
GBrain 給它一顆持久記憶的腦。

GBrain 是一套 Markdown 原生的知識圖譜記憶系統，由 Y Combinator 總裁暨執行長 Garry Tan 開源（MIT 授權、TypeScript）。它讓 AI Agent 把會議、信件、推文、語音、想法寫進一個會自動接線的知識圖譜，再用「向量＋關鍵字＋RRF」的混合檢索把過去的脈絡找回來 — 並用 Postgres 原生的 Minions 任務佇列在夜裡把實體 enrich 起來，整段流程不需要外掛資料庫伺服器。

生產部署規模

17,888 Pages

README 揭露的正式部署：另含 4,383 位人物、723 家公司的結構化追蹤。

自主排程

21 Cron Jobs

無人介入的背景任務，靠 Minions 佇列在崩潰後仍可續跑。

混合檢索召回

97.9% R@5

240 頁基準上 P@5 49.1%／R@5 97.9%，勝過純向量或純關鍵字。

授權與堆疊

MIT

TypeScript 完全開源；引擎可選嵌入式 PGLite 或 Postgres／Supabase。

01 / 編者手記為什麼 AGENT 需要一顆真正的腦

大語言模型的 context window 很大，但兩次對話之間什麼都不記得。

編者手記 EDITOR'S NOTE

GBrain 補的就是這一塊：把 Agent 看過、聽過、做過的事，沉澱成一個 git 可讀、資料庫可查的知識圖譜，讓「記得」變成一個可被檢索、可被 cron 維護、可被 MCP 工具呼叫的系統 — 而不是又一個塞滿 prompt 的對話框。

記憶不是 RAG。

多數「Agent 記憶」其實是把段落塞進向量庫再撈回來。GBrain 多做一層：自動抽取實體關係、建立帶型別的連結（attended、works_at、invested_in、founded、advises），而且這層接線不呼叫 LLM，所以便宜、確定、可重跑。檢索端再把向量、關鍵字、reciprocal rank fusion 疊起來，回傳帶分數、帶來源的結果。

Markdown 原生，不是又一個黑盒資料庫。

每一頁知識都是一份人類看得懂的 Markdown，存在 git 裡；資料庫只是它的索引與圖譜層。gbrain.yml 的儲存分層可以把機器生成的大量內容（轉錄稿、媒體）留在 DB、把人讀的內容留在 git，兩邊用 gbrain sync 增量對齊。引擎也可以在嵌入式 PGLite 與 Postgres／Supabase 之間雙向遷移，不被任何一家綁死。

確定性的背景工作，才撐得起「自主」。

Minions 是 Postgres 原生的任務佇列，崩潰後可續跑、可恢復，README 揭露的數字是單一 minion 任務約 753ms 完成、相對於 sub-agent 動輒 10 秒以上的 gateway timeout，且這類確定性背景工作 $0 token 成本。生產部署裡 21 個 cron job 就靠它在無人介入下跑了下來。

02 / 功能總覽知識圖譜 · 混合檢索 · MINIONS · MCP

功能總覽 Capabilities

GBrain 把「Agent 記憶」拆成六塊：自動接線的知識圖譜、混合檢索、多模態攝取、Minions 任務佇列、模組技能系統，以及對外的 MCP 整合層。

6 Entries
Graph · Retrieval · Jobs
Markdown-Native

01^/06

garrytan / gbrain

會自己接線的知識圖譜

自動抽取實體關係、建立帶型別的連結 — 而且不呼叫 LLM

匯入內容時，GBrain 會把人物、公司、概念之間的關係抽出來，建成帶型別的邊：attended、works_at、invested_in、founded、advises。每頁同時保有一份「編譯後的事實」與一條 append-only 的時間軸，並用 backlink 數加權實體排序。關鍵在於這層接線是確定性的、不走 LLM，所以可重跑、可批次回填、近乎零成本 — 之後用 gbrain graph-query <slug> 就能沿著型別關係做推理式遍歷。

✓ 無 LLM 呼叫 5 種型別邊編譯事實 + 時間軸 backlink 加權 graph-query

Edge Types attended / works_at … Per Page Truth + Timeline Cost No-LLM

garrytan / gbrain · query

向量 + 關鍵字 + RRF 的混合檢索

README 揭露：240 頁基準上 P@5 49.1%、R@5 97.9%

gbrain search 走 tsvector 關鍵字檢索；gbrain query 則把向量相似度、關鍵字命中與 reciprocal rank fusion 疊起來，回傳帶分數、帶來源出處的結果（例如 concepts/do-things-that-dont-scale (score: 0.94) [Source: paulgraham.com]）。README 給出的基準分數明顯高過純向量或純關鍵字的做法。

vector + keyword reciprocal rank fusion scored + sourced P@5 49.1% / R@5 97.9%

Commands search · query Benchmark 240-page set

garrytan / gbrain · recipes/

多模態攝取，夜裡自動 enrich

會議、信件、推文、語音通話、原始想法 — 都能變成圖譜節點

GBrain 內建會議轉錄稿、Email、推文、語音通話、文章等攝取流程，匯入後自動抽實體、建關係，並在夜間排程裡把實體 enrich 補全。Embedding 端提供 14 種 recipe，包含 OpenAI（預設）、Voyage、Google Gemini、Azure、本機的 Ollama 與 llama.cpp，以及 LiteLLM proxy — 雲端或全本機都跑得起來。

meetings / emails / tweets voice notes overnight enrichment 14 embedding recipes

Sources 5+ modalities Embeddings 14 recipes

garrytan / gbrain · jobs

Minions — Postgres 原生的任務佇列

崩潰後可續跑、可恢復、確定性執行；README 揭露單任務約 753ms

背景工作不交給容易 timeout 的 sub-agent，而是丟進 Minions：gbrain jobs submit <name> 觸發確定性背景任務，gbrain jobs supervisor 是會自動重啟、能在 crash 後恢復的 worker。README 給的對比是 minion 任務約 753ms 完成、相對於 sub-agent 動輒 10 秒以上的 gateway timeout，且這類確定性工作 $0 token 成本、任務成功率 100%。

Postgres-native crash recovery resumable $0 token

Submit jobs submit Worker jobs supervisor

garrytan / gbrain · skills/

數十個模組技能 + 路由器

攝取、enrichment、營運、研究各有專屬指令，靠 RESOLVER.md 分派

skills/ 目錄是一組模組化指令集（README 列為 30+ 個技能），涵蓋從攝取、enrichment、操作維運到研究的各種任務，由 skills/RESOLVER.md 這個 dispatcher 決定每個請求路由到哪個技能。gbrain skillify scaffold <name> 會生成新技能的 5 個 stub；gbrain skillpack install <name> 部署策展好的技能包；gbrain check-resolvable 稽核路由完整度。

30+ skills RESOLVER.md skillify scaffold skillpack install

Dispatcher RESOLVER.md Scaffold 5 stubs

garrytan / gbrain · serve

30+ 工具，透過 MCP 對外曝露

Claude、Cursor、ChatGPT 等都能把 GBrain 當記憶層呼叫

GBrain 透過 Model Context Protocol 曝露 30+ 個工具，任何支援 MCP 的客戶端都能直接讀寫這顆腦。stdio 模式只要在 ~/.claude/server.json 加一段 { "command": "gbrain", "args": ["serve"] }；要上正式環境則用 gbrain serve --http，附帶 OAuth 2.1 與內建的 admin dashboard。subagent 執行也會把 transcript 持久化下來。

30+ MCP tools stdio + HTTP OAuth 2.1 admin dashboard

Local gbrain serve Production serve --http

03 / 安裝與設定 AGENT-NATIVE · CLI · MCP · ENGINE · EMBEDDINGS

安裝與設定 Setup

三條安裝路徑（給 Agent、給 CLI、給 MCP 客戶端），加上引擎選擇、embedding 供應商、健康檢查 — 都收在這裡。

6 Entries
Bun · PGLite · MCP
~30 min to live

01^/06

garrytan / gbrain · INSTALL_FOR_AGENTS.md

給 Agent 自己讀的安裝指令

把一個 raw URL 貼進 OpenClaw／Hermes，約 30 分鐘到可運作狀態

這是 README 標為「推薦」的路徑：讓 Agent 取回並照著 INSTALL_FOR_AGENTS.md 做。前置條件是 Git 與 Bun runtime、以及 OPENAI_API_KEY（向量檢索必需）、ANTHROPIC_API_KEY（選用、能提升檢索品質）。指令本身會引導 Agent 完成 clone、bun install && bun link、gbrain init、gbrain doctor --json、匯入與索引、回填知識圖譜、載入核心技能，並排好 sync／auto-update／dream cycle／doctor 等週期任務。

✓ README 推薦 OpenClaw / Hermes ~30 min OPENAI_API_KEY ANTHROPIC_API_KEY（選用）

Prereqs Git + Bun Required OPENAI_API_KEY Time ~30 min

garrytan / gbrain · CLI

標準 CLI 安裝

git clone → bun install → bun link → gbrain init，兩秒就有一顆本機腦

git clone https://github.com/garrytan/gbrain.git && cd gbrain && bun install && bun link，接著 gbrain init 會在約兩秒內建好本機的 PGLite brain。之後 gbrain import ~/notes/ 索引 markdown（idempotent，可重跑）、gbrain query "your question" 做混合檢索。gbrain get|put|delete <slug> 直接讀寫單頁。

Bun runtime gbrain init idempotent import get / put / delete

Install bun install + link First Brain ~2s (PGLite)

garrytan / gbrain · MCP

接成 MCP 伺服器

stdio 一行設定給 Claude Code，HTTP 模式給正式環境

本機用法：在 ~/.claude/server.json 的 mcpServers 加 "gbrain": { "command": "gbrain", "args": ["serve"] }，Claude Code、Cursor、ChatGPT 等支援 MCP 的客戶端就能呼叫那 30+ 個工具。正式環境用 gbrain serve --http，內含 OAuth 2.1 server 與管理用 admin dashboard。

~/.claude/server.json gbrain serve serve --http OAuth 2.1 + admin

Local stdio (serve) Production --http

garrytan / gbrain · engines

選引擎，可雙向遷移

PGLite 嵌入式零設定起步，要規模就遷到 Postgres／Supabase

預設是嵌入式的 PGLite，不需要外掛資料庫伺服器；需要擴展時用 gbrain migrate --to supabase 切到 Postgres／Supabase，之後也能 gbrain migrate --to pglite 切回來 — 兩個方向都通，所以可以先在筆電上做完，再決定要不要上雲，不會被任何一端鎖死。

PGLite（預設） Postgres / Supabase migrate --to 雙向

Default PGLite (embedded) Scale Postgres / Supabase

garrytan / gbrain · recipes/

14 種 embedding 供應商 recipe

雲端、企業，或完全跑在本機 — 都有現成設定

內建 14 個 embedding recipe：OpenAI（預設）、Voyage、Google Gemini、Azure，本機選項有 Ollama 與 llama.cpp，再加上可代理多家模型的 LiteLLM proxy。換供應商不必改程式，挑對應 recipe 即可 — 對資料不能出境的團隊，純本機這條路是現成的。

OpenAI（預設） Voyage / Gemini / Azure Ollama / llama.cpp（本機） LiteLLM proxy

Recipes 14 Local Ollama / llama.cpp

garrytan / gbrain · doctor

健檢與路由稽核

gbrain doctor 自我修復，check-resolvable 確認技能路由不漏

gbrain doctor 跑健康檢查，附帶可選的自動修復；gbrain doctor --json 適合丟進腳本或 CI。gbrain check-resolvable 則稽核技能路由的完整度，確認每個請求都有對應的技能可以接 — 這在你用 skillify 持續加技能後特別重要。

doctor + auto-repair --json check-resolvable

Health gbrain doctor Routing check-resolvable

04 / 進階用法 POWER-USER PATTERNS · gbrain.yml · MINIONS · CI

把 GBrain 用滿，藏在 README 裡的那幾招。

這些都不是基本流程裡會碰到的：儲存分層、minion 與 subagent 的取捨、批次回填圖譜、用 eval replay 守住回歸、以及讓其他 Agent 也讀得懂這顆腦的導航檔。所有指令與旗標都對得上 README，沒有臆造的參數。

garrytan / gbrain · gbrain.yml

儲存分層：DB 放重，git 放人讀

把機器生成的大量內容留在資料庫，人會看的內容留在 git

在 gbrain.yml 設 storage.db_tracked（例如 people/、companies/ — 既進 DB 也進 git）與 storage.db_only（例如 media/x/、meetings/transcripts/ — 只進 DB），就不會讓轉錄稿和媒體把 git 倉庫撐爆，又能保留人讀得懂的核心頁面。

db_tracked / db_only git 不爆量 gbrain.yml

Config storage: Split tracked / only

garrytan / gbrain · jobs

背景工作丟 Minion，別丟 Subagent

README 的對比：minion 約 753ms vs sub-agent 10 秒以上的 gateway timeout

可確定性、可重跑的背景工作用 gbrain jobs submit <name> 丟進 Minions 佇列，再跑 gbrain jobs supervisor 當會自動重啟、crash 後可恢復的 worker。比起把活塞給容易 timeout 的 sub-agent，這條路更快、成功率 100%、而且這類確定性工作 $0 token 成本。

jobs submit jobs supervisor $0 token

Submit jobs submit Worker jobs supervisor

garrytan / gbrain · extract

既有 brain 也能批次回填圖譜

不必重匯：直接從 DB 把連結與時間軸補出來

如果你已經有一堆頁面但圖譜還沒接好，用 gbrain extract links --source db 與 gbrain extract timeline --source db 批次回填型別關係與時間軸；要一次全跑就 gbrain extract all。因為這層接線不走 LLM，回填是確定性的、可放心重跑。

extract links extract timeline --source db

Backfill extract all Source db

garrytan / gbrain · evals/

用 eval replay 守住檢索品質

BrainBench-Real 收錄真實查詢（去識別化），改 code 前先過閘門

gbrain eval replay 會拿先前擷取的基準來檢查程式變更有沒有讓檢索品質退步；BrainBench-Real 則把真實查詢收錄下來、做 PII 清洗後當測試集。把它接進 CI，就不會在重構檢索邏輯時悄悄把召回率改差。

eval replay BrainBench-Real PII scrubbing

Gate eval replay Suite BrainBench-Real

garrytan / gbrain · sync

git 與 brain 之間，增量對齊

編輯落在 markdown 那一側時，用 sync 把差異補回索引

gbrain import 是首次或全量索引；gbrain sync 則是 git-to-brain 的增量更新 — 當你（或別的工具）直接改了 markdown，跑一次 sync 就把改動推回索引與圖譜，不必整批重來。配合 README 建議的 15 分鐘 sync 排程，brain 永遠跟得上 git。

gbrain sync git-to-brain 增量

Full gbrain import Incremental gbrain sync

garrytan / gbrain · AGENTS.md

讓別的 Agent 也讀得懂這顆腦

llms.txt / llms-full.txt 給 LLM 導航，AGENTS.md 給非 Claude 客戶端

倉庫附了 llms.txt 與 llms-full.txt 讓 LLM 快速建立全貌；AGENTS.md 是給非 Claude Agent 的整合協議；skills/RESOLVER.md 則是技能路由的 dispatcher。要把 GBrain 接進 Cursor、Windsurf 或自製 Agent，從這三個檔入手最快。

llms.txt / llms-full.txt AGENTS.md RESOLVER.md

Nav llms.txt Non-Claude AGENTS.md

05 / 實戰應用 CRON · IMPORT · GRAPH · SKILLIFY · QUERY

實戰應用 Workflows

把功能組成可重複的流程：夜間自主 enrichment、個人筆記匯入與同步、圖譜查詢、把臨時修正變技能、回歸閘門、檢索問答。

6 Entries
Cron · Graph · Skillify
Production-Proven

01^/06

garrytan / gbrain · cron

夜裡自己 enrich 的腦

README 揭露的生產部署：21 個 cron job、無人介入跑下來

這是 GBrain 最有代表性的用法 — 把它接給一個自主 Agent，排好 sync（約 15 分鐘）、auto-update（每日）、dream cycle（每夜把實體 enrich 補全）、doctor（每週健檢）等週期任務，再交給 gbrain jobs supervisor 這個可在 crash 後恢復的 worker 跑。README 揭露的正式部署裡，這套排程支撐了 17,888 頁、4,383 位人物、723 家公司的持續追蹤，以及 21 個 cron job、約 753ms 的 minion 完成時間、100% 任務成功率 — 全部沒有人在旁邊盯。

✓ 生產驗證 21 cron jobs dream cycle jobs supervisor 100% 成功率

Cron Jobs 21 Tracked 17,888 pages Mode Autonomous

garrytan / gbrain · import

把現有筆記接成一顆腦

init → import → extract all → query，幾分鐘就能查自己的 markdown

最低門檻的上手路徑：gbrain init 建一顆本機 PGLite brain，gbrain import ~/notes/ 把 markdown 索引進來（idempotent，重跑安全），gbrain extract all 把型別連結與時間軸接起來，之後 gbrain query "..." 就能在整個筆記庫上做混合檢索。要持續同步就掛 gbrain sync。

gbrain init import ~/notes/ idempotent extract all

First Brain ~2s Index idempotent

garrytan / gbrain · graph-query

沿著知識圖譜做推理式查詢

不只是「找相關段落」，而是「順著關係走一條路」

gbrain graph-query <slug> 走的是型別關係遍歷 — 從一個人出發找他 works_at 的公司、再找同公司的其他人，或從一場會議的 attended 邊展開參與者網絡。每頁同時有「編譯後的事實」與 append-only 時間軸，實體排序又被 backlink 數加權，所以越被引用的節點越容易被撈到。

typed traversal compiled truth + timeline backlink-boosted

Command graph-query Ranking backlink-boosted

garrytan / gbrain · skillify

把臨時修正沉澱成技能

一次性的 hack → 永久、有測試、路由可驗證的 skill

Skillify 系統把「這次手動改了什麼」變成可重用的能力：gbrain skillify scaffold <name> 生出含 5 個 stub 的新技能骨架，照 conformance checklist 補齊內容與測試，gbrain check-resolvable 確認它在路由表裡接得上，需要的話再 gbrain skillpack install 部署成策展好的技能包。下次同樣的情境就不用再手動處理。

skillify scaffold 5 stubs conformance checklist check-resolvable

Scaffold 5 stubs Verify check-resolvable

garrytan / gbrain · serve --http

多個 Agent 共用同一顆腦

gbrain serve --http 起一個 OAuth 2.1 server，配內建 admin dashboard

團隊或多 Agent 場景下，用 gbrain serve --http 把這顆腦變成一個有 OAuth 2.1 與管理面板的服務，任何支援 MCP 的客戶端（Claude Code、Cursor、ChatGPT…）都能呼叫那 30+ 個工具來讀寫共享知識；subagent 的執行 transcript 也會被持久化下來，方便回溯。

serve --http OAuth 2.1 admin dashboard 30+ MCP tools

Server serve --http Auth OAuth 2.1

garrytan / gbrain · query

直接問這顆腦

gbrain query "what themes appear across my notes?" → 帶分數、帶來源

日常用法就一句 gbrain query "..."：混合檢索回傳排序過、附出處的結果，例如 concepts/do-things-that-dont-scale (score: 0.94) — PG 關於從不可規模化的努力中學習的論點 [Source: paulgraham.com, 2013-07-01]。因為每筆都帶來源，回答可以追溯，不是憑空生成。

gbrain query scored results 附來源出處

Command gbrain query Output scored + sourced

想把 GBrain 接進你的 Agent 堆疊？

記憶層已經開源。
接上生產環境這一段，
是 Tenten 在做的事。

Tenten 是 AI-First 設計與技術顧問公司。我們把 Claude、MCP、Agentic Commerce 接進 Headless CMS、Webflow、Shopify Plus 的企業級交付 — 也包含像 GBrain 這樣的 Agent 記憶層：選引擎、設儲存分層、排好 cron 與 Minions、把 MCP 工具接進你正式上線的營運流程。

預約 30 分鐘諮詢 → Tenten Awesome List

Tenten 如何部署這些 Skills

Skills 架構諮詢

依團隊與堆疊選出適配 skills，建立 OpenClaw 路由與 CI/CD 部署流程。

Claude Design System Sprint

兩週固定價格，接上 frontend-design + brand-guidelines 到 production。

Agentic Commerce Build

Shopify Plus / Webflow / Headless 遷移，搭配 Claude + MCP 營運層。

大語言模型的 context window 很大，但兩次對話之間什麼都不記得。

記憶不是 RAG。

Markdown 原生，不是又一個黑盒資料庫。

確定性的背景工作，才撐得起「自主」。

功能總覽 Capabilities

會自己接線的知識圖譜

向量 + 關鍵字 + RRF 的混合檢索

多模態攝取，夜裡自動 enrich

Minions — Postgres 原生的任務佇列

數十個模組技能 + 路由器

30+ 工具，透過 MCP 對外曝露

安裝與設定 Setup

給 Agent 自己讀的安裝指令

標準 CLI 安裝

接成 MCP 伺服器

選引擎，可雙向遷移

14 種 embedding 供應商 recipe

健檢與路由稽核

把 GBrain 用滿，藏在 README 裡的那幾招。

儲存分層：DB 放重，git 放人讀

背景工作丟 Minion，別丟 Subagent

既有 brain 也能批次回填圖譜

用 eval replay 守住檢索品質

git 與 brain 之間，增量對齊

讓別的 Agent 也讀得懂這顆腦

實戰應用 Workflows

夜裡自己 enrich 的腦

把現有筆記接成一顆腦

沿著知識圖譜做推理式查詢

把臨時修正沉澱成技能

多個 Agent 共用同一顆腦

直接問這顆腦

把 GBrain 用起來的四條路

先讓 CLI 跑起來，再決定要不要上雲

用 serve --http 開一個有 OAuth 的記憶服務

把 INSTALL_FOR_AGENTS.md 貼給 OpenClaw／Hermes

把 eval replay 接進 CI，把 skillify 變成習慣

記憶層已經開源。 接上 生產環境這一段， 是 Tenten 在做的事。

記憶層已經開源。
接上生產環境這一段，
是 Tenten 在做的事。