GBrain 用 Markdown、Git、混合检索和 MCP，为 AI Agent 构建可长期演进的外部记忆系统。
原文标题：爆火 14k 星！GBrain 彻底解决 AI Agent 失忆痛点
原文作者：数据派THU
冷月清谈：
怜星夜思：
2、Markdown + Git 作为 Agent 记忆的真值源，会不会比数据库更适合长期知识管理？
3、GBrain 这种个人化很强的开源项目，适合普通开发者直接用，还是更适合拿来参考架构？
4、零 LLM 调用的知识图谱提取听起来很省钱，但会不会牺牲理解能力？
原文内容
本文约4000字，建议阅读8分钟本文介绍了开源 GBrain 系统，剖析其架构机制、接入方法与落地优缺点。
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@597.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 去猜。
而且这层图谱有一种b机制。一个实体第一次被提及时，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"是日常。
06 12 个月后回头看
我的判断：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 对你的领域理解越深。
标签：
