TL;DR
GBrain 是 YC 总裁 Garry Tan 开源的 Agent 记忆系统，三层架构（Brain Repo + 混合检索 + 34 技能工作流），已获 14,000+ GitHub Stars 核心差异化：Markdown + Git 作为人类与 AI 共享的真值源，自布线知识图谱（零 LLM 调用），Dream Cycle 夜间记忆巩固机制 通过 MCP 协议可在 30 分钟内接入 Python Agent；本文提供完整 Python 接入代码，可直接复用
先看一个数字：P@5 49.1%，R@5 97.9%。这是 GBrain 在 240 页知识库上的混合检索成绩——比纯向量搜索高出 31.4 个百分点。
说人话就是：你问 Agent "我之前说的那个项目叫什么来着"，它能找到了。而不是给你一段语义相近但完全无关的内容。
YC 总裁 Garry Tan 上个月把他跑了 13 年的"第二大脑"开源了。17,888 页笔记、4,383 个人脉、723 家公司、21 个 cron job 全天候自动运转——全都装在一个 MIT 开源的仓库里。上线 24 小时就拿了 5000 颗星，现在 14,000+。
这件事为什么重要？因为 Agent 的"失忆"问题正在成为整个行业最大的瓶颈。你用 LangGraph 搭了个 Agent，它能推理、能调工具、能写代码——但每次对话都像第一次见你。给它加个向量数据库，它还是记不住"上次你女儿叫什么名字"跟"三个月前你聊过的那笔投资"之间有什么关系。
GBrain 做的事，就是把 Agent 记忆从一个"外挂硬盘"升级成一个真正的"大脑"。
01三层架构：为什么"向量数据库 + 聊天记录"不够
GBrain 的架构分三层。每一层解决一类问题，三层合起来才构成完整的记忆系统。
Layer 1：Brain Repo（真值源）
最底层不是数据库，是 Markdown 文件。每个实体——人、公司、概念、会议——一个 .md 文件，全部用 Git 做版本控制。
每个文件有两种内容区：
Compiled Truth（当前认知摘要）：写在最上面，是对这个实体目前最准确的理解。新信息进来后会被重写。 Timeline（追加式时间线）：写在下面，只追加、不修改，保留每条信息的原始证据和时间戳。
这层的关键设计理念是：人类和 AI 共享同一份真值源。你能用 Obsidian 打开看、用 grep 搜索、用 Git 回溯。数据库崩了？从 Git 重建就是。
Layer 2：Retrieval Index（混合检索引擎）
这层是 GBrain 真正的技术核心。默认用 PGLite（一个跑在 WASM 里的嵌入式 Postgres），初始化两秒钟，零配置。
查询管线长这样：
→ [可选] Claude Haiku 生成 2 个替代表述（查询扩展）
→ 并行搜索：
├─ HNSW 向量搜索（1536-dim，cosine 相似度）
└─ PostgreSQL tsvector 全文搜索（title A权重 > compiled B权重 > timeline C权重）
→ RRF 融合（score = Σ(1/(60+rank))）
→ 四层去重（每页保留最佳 3 片段，Jaccard > 0.85 阈值）
→ Backlink 加权排序（被其他页面链接的页面加分）
→ 返回 Top-K 结果
向量搜索解决"意思相近"，关键词搜索解决"精确匹配"。两者融合后再用 backlink 加权——一个被反复引用的页面自然比孤立的页面更重要。这就是为什么它能比纯向量搜索高出 31.4 个百分点。
Layer 3：34 个 Skills 工作流
GBrain 的设计哲学叫 "Thin Harness, Fat Skills"——运行时代码很薄，智能全在 34 个 Markdown 技能文件里。
这 34 个技能分五类：
Always-on：signal-detector、brain-ops，全天候监听和调度 内容摄入：ingest、meeting-ingestion、media-ingest，把邮件/会议/推文变成结构化的脑页 研究综合：research-synthesizer，跨多个脑页抽取主题 脑区运维：enrich（充实实体信息）、maintain（去重合并）、citation-fixer（修正引用链） 身份设置：soul-audit（审视自己的知识盲区）、setup、briefing
每个技能文件就是一个 Markdown，规定了"什么时候触发 → 读取什么 → 写什么 → 写到哪 → 质量标准"的完整工作流。Agent 读这些文件就知道怎么做。
02最惊艳的设计：零 LLM 调用的知识图谱
每次往 Brain Repo 写一个页面，GBrain 会自动提取实体和关系——用的是正则和字符串匹配，零次 LLM 调用。
提取的关系类型包括：
attended（参加了某会议）works_at（在某公司工作）invested_in（投资了某公司）founded（创立了某公司）advises（担任某公司顾问）
这就意味着，你可以问 GBrain "谁投资了跟 Alice 有关的那家数据库公司？"——纯图谱查询就能回答，不需要 LLM 去猜。
而且这层图谱有一种自我进化机制。一个实体第一次被提及时，GBrain 给它建一个 Tier 3 存根页——只有名字和基本来源。跨三个不同来源再次出现？升级到 Tier 2，自动做 web 搜索和社交充实。参加过会议或跨八个来源出现？Tier 1，跑完整充实管线。
用 Garry Tan 自己的话说："The brain learns who matters without being told."
03晚上睡觉时，你的 Agent 在做这些事
GBrain 有一个叫 "Dream Cycle" 的夜间循环机制——灵感直接来自人脑的睡眠记忆巩固过程。
具体流程：
白天：Signal Detector 全天候并行捕获信号（邮件、推文、日程……），不阻塞 Agent 响应每个信号时，brain-ops 先查脑区——"这事我以前知道些什么？" 响应完成后，新信息被写入脑页，实体关系自动提取 晚上：Minions（GBrain 的任务队列）跑确定性批量任务——拉取标记的帖子、补充引用、去重合并、重建索引——全部归零 LLM token 成本
Minions 是这个循环里最被低估的设计。它把"拉帖子、解析 JSON、写页面、同步索引"这些确定性活从 LLM 手里抢过来，用原生 TypeScript 代码跑。对比用子 Agent fan-out 做同样的事：Minions 753 毫秒、0 美元；子 Agent 方式直接网关超时。
Garry Tan 自己的 brain 跑着 21 个 cron job，全天候自动化运转——你在睡觉，你的 Agent 在整理你的记忆。
04跑起来：30 分钟接入你的 Python Agent
GBrain 是 TypeScript 写的，但通过 MCP 协议可以接入任何语言的 Agent。下面是一个完整的 Python 接入流程。
第一步：安装 GBrain
git clone https://github.com/garrytan/gbrain.git
cd gbrain
bun install && bun link
gbrain init # 本地 brain，2 秒就绪
前置条件：需要安装 Bun（
curl -fsSL https://bun.sh/install | bash）
第二步：导入你的笔记
gbrain import ~/notes/ # 导入已有 Markdown 笔记
第三步：启动 MCP Server
# 启动 MCP Server
gbrain serve
# 或启动 HTTP 模式供 Python 调用
gbrain serve --http --port 3131
第四步：Python 接入 MCP
import asyncio
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def query_brain(query: str) -> list[dict]:
"""查询 GBrain 记忆库"""
server_params = StdioServerParameters(
command="gbrain",
args=["serve"],
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# 混合搜索：向量 + 关键词 + 图谱
result = await session.call_tool(
"gbrain_search",
arguments={"query": query, "top_k": 5}
)
return json.loads(result.content[0].text)
async def remember_fact(title: str, content: str, tags: list[str] = None):
"""往 GBrain 写入一条新知识"""
server_params = StdioServerParameters(
command="gbrain",
args=["serve"],
)
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(
"gbrain_write",
arguments={
"title": title,
"content": content,
"tags": tags or [],
}
)
return json.loads(result.content[0].text)
# --- 实际使用 ---
async def main():
# 写入一条记忆
await remember_fact(
title="LangGraph 状态机设计要点",
content="今天发现 LangGraph 的 StateGraph 在嵌套 subgraph 时，"
"checkpoint 机制会为每个 subgraph 独立保存状态。"
"这意味着你需要显式地在父 graph 中声明 shared_state 字段，"
"否则子图的状态不会被持久化到父图的 checkpoint 中。",
tags=["langgraph", "agent", "state-machine", "踩坑"]
)
# 稍后查询
results = await query_brain("LangGraph checkpoint 子图状态丢失")
for r in results:
print(f"📄 {r['title']} (score: {r['score']:.3f})")
print(f" {r['snippet'][:200]}...")
print()
asyncio.run(main())
这段代码做的事很简单：把任何 Python Agent 的工作记忆写入 GBrain，下次需要时查出来。你可以把这个逻辑封装成 LangGraph 的一个 Tool，让 Agent 在处理用户消息之前先查 GBrain，在处理完之后把关键信息写入 GBrain。
在 Claude Code 里用 GBrain
如果你用 Claude Code，配置更简单。在 claude_settings.json 里加一行：
{
"mcpServers": {
"gbrain": { "command": "gbrain", "args": ["serve"] }
}
}
然后直接在对话里说："查一下我之前关于 React 状态管理的笔记"。Claude Code 会自动调用 GBrain 的 MCP 工具。
05但别急着 all-in：几个现实的坑
我周六下午花了两小时把 GBrain 跑起来了。说实话，前 30 分钟在跟 Bun 搏斗。
我的环境是 M1 Mac，brew install bun 倒是顺利。但 bun install 的时候 PGLite 的 WASM 编译挂了——后来发现是 Node 版本冲突，切到 22 LTS 才过去。这种"环境问题"在 Python 生态里很少遇到，在 JS 生态里是日常。如果你也是 Python 技术栈为主，做好心理准备：你会在 bun、npm、node 的版本管理上先花 15 分钟。
索引速度倒是超出预期。我导入了大概 200 篇 Markdown 笔记，gbrain import 跑了两分钟左右。但注意：第一次 gbrain query 的时候 PGLite 冷启动有 3-5 秒延迟——后面就快了，毫秒级。这是因为嵌入式 Postgres 的 shared buffer 在第一次查询时才真正加载到内存。
另一个没在文档里写的坑：技能文件是英文的，而且用了大量 OpenClaw 特有的占位符语法。如果你想把 GBrain 接到非 OpenClaw 的 Agent 上，34 个技能文件里的 {agent_name}、{brain_repo} 这些变量要逐个改。我倒不觉得这是 GBrain 的问题——它本来就是 Garry Tan 给自己用的，开源出来已经很难得了。但这个改造成本，在决定用它之前要想清楚。
客观说，GBrain 目前还不是一个"所有人都该立刻用"的项目。
技术栈锁定：GBrain 是 Bun + TypeScript 写的，98% TypeScript。如果你用的是 Python 全栈，MCP 桥接是目前唯一的接入方式，而且官方文档对 Python 集成的说明几乎为零。 仅深度支持 OpenClaw 和 Hermes：这两个 Agent 框架有第一方支持。接入 LangGraph、CrewAI、AutoGen 需要你自行处理 MCP 协议适配。 单操作者设计：不适合团队协作。如果你想搭建团队共享的知识库，这不是正确选择。 依赖前沿模型：检索质量在 Claude Opus 4.6 / GPT-5.4 级别模型上最好，低端模型的表现有可见下降。 项目还在快速迭代：当前版本约 v0.30，API 不稳定，"breaking changes"是日常。
0612 个月后回头看
我的判断：Agent 记忆不会走"框架内置"那条路，它会走"协议层标准化"的路。
原因很简单。LangChain 当年把 Memory 模块内置进框架，结果是什么？任何想换框架的人都得重写一遍记忆逻辑。MCP 的出现改变了这个局面——记忆不再是框架的一个模块，而是协议层的一个服务。GBrain 的价值不在它今天的代码，在它验证了"Agent 记忆可以是一个独立的、通过标准协议接入的服务"这个模式。
但 GBrain 本身会不会成为这个标准？很难。它的设计太个人化了——Thin Harness, Fat Skills 的哲学意味着每个技能文件都是"Garry Tan 觉得应该这样"的产物。真正会规模化的是这个模式被抽象后的版本：一个语言无关的 Agent 记忆协议，Python/TS/Go 都有原生 SDK，本地跑 PGLite 还是接云端都行。GBrain 示范了这条路该怎么走。
一个预测：12 个月内，LangGraph 和 CrewAI 都会出官方 MCP Memory Server。不是因为他们想跟 GBrain 竞争——是因为用户发现 Agent 记忆是一个独立层之后，就不会再接受"框架自带的那个"了。
我看好几个方向：
多 Agent 协作是必然方向——一个 brain 被多个 Agent 共享读写的需求太明显了 Python 原生 SDK 应该会出现，社区需求摆在那 托管云版本 — 不是所有人都想自己维护 PGLite/Supabase 记忆协议的标准化：MCP 已经给了 Agent 记忆一个协议层的锚点，GBrain 的模式（Markdown 真值源 + 混合检索 + 技能工作流）有可能成为事实标准
07架构全貌
看懂这张图，就看懂了 GBrain 的全貌。信号从外部流入，Skills 层决定"要不要记"，Retrieval 层负责"怎么找到"，Brain Repo 是真值源，知识图谱让记忆之间产生关联——然后这个关联反哺回检索层，让下一次搜索更准。
这是一个正反馈循环。用的时间越长，brain 对你的领域理解越深。
