garrytan/gbrain
GitHub: garrytan/gbrain
GBrain 是一个为 AI 智能体设计的长期记忆知识库系统，解决上下文遗忘与信息孤岛问题。
Stars: 7530 | Forks: 806
# GBrain
你的AI智能体很聪明，但它对你的生活一无所知。GBrain解决了这个问题。会议、邮件、推文、日程事件、语音通话、原始想法……所有这些都流入一个可搜索的知识库，在每次回复前你的智能体都会读取它，并在每次对话后写入其中。智能体每天都在变得更聪明。
## 需要先有一个AI智能体吗？
GBrain 设计为由 AI 智能体安装和操作。如果你还没有运行的智能体：
- **[OpenClaw](https://openclaw.ai)** — 在 [Render 上部署 AlphaClaw](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw)（一键式，需要 8GB+ RAM 实例）
- **[Hermes Agent](https://github.com/NousResearch/hermes-agent)** — 在 [Railway 上使用此模板部署](https://github.com/praveen-ks-2001/hermes-agent-template)（一键式）
## 从这里开始
**https://github.com/garrytan/gbrain** — 将此仓库克隆到你的智能体文件系统中。这是文档、技能、升级和食谱的主目录。后续升级：`git pull origin main && bun install`。
将这段代码块复制到 [OpenClaw](https://openclaw.ai)、[Hermes](https://github.com/NousResearch/hermes-agent) 或任何持久的 AI 智能体中。智能体读取文档、执行工作，并在需要时向你请求 API 密钥。约 30 分钟。
### 没有智能体（独立 CLI 模式）
```
git clone https://github.com/garrytan/gbrain.git && cd gbrain && bun install && bun link
gbrain init # local brain, ready in 2 seconds
gbrain import ~/notes/ # index your markdown
gbrain query "what themes show up across my notes?"
```
## 获取数据
GBrain 安装完成后，你的智能体需要数据流入。GBrain 提供了集成食谱，智能体为你设置。它们读取食谱、请求 API 密钥、验证每一项并运行冒烟测试。[Markdown 就是代码](docs/ethos/THIN_HARNESS_FAT_SKILLS.md)... 食谱本身就是安装器。
| 食谱 | 所需条件 | 功能 |
|------|----------|------|
| [Public Tunnel](recipes/ngrok-tunnel.md) | — | 为 MCP + 语音提供固定 URL（ngrok Hobby $8/月） |
| [Credential Gateway](recipes/credential-gateway.md) | — | Gmail + 日历访问（ClawVisor 或 Google OAuth） |
| [Voice-to-Brain](recipes/twilio-voice-brain.md) | ngrok-tunnel | 电话通话 → 大脑页面（Twilio + OpenAI Realtime） |
| [Email-to-Brain](recipes/email-to-brain.md) | credential-gateway | Gmail → 实体页面（确定性采集器） |
| [X-to-Brain](recipes/x-to-brain.md) | — | Twitter → 大脑页面（时间线 + 提及 + 删除） |
| [Calendar-to-Brain](recipes/calendar-to-brain.md) | credential-gateway | Google 日历 → 可搜索的每日页面 |
| [Meeting Sync](recipes/meeting-sync.md) | — | Circleback 转录 → 带参与者的智能体页面 |
运行 `gbrain integrations` 查看状态。依赖项会自动解析。参见 [Getting Data In](docs/integrations/README.md) 获取完整指南。
## 复合增长理论
大多数工具帮你找到东西。GBrain 让你随着时间推移变得更聪明。
```
Signal arrives (meeting, email, tweet, link)
→ Agent detects entities (people, companies, ideas)
→ READ: check the brain first (gbrain search, gbrain get)
→ Respond with full context
→ WRITE: update brain pages with new information
→ Sync: gbrain indexes changes for next query
```
每一次循环都增加知识。智能体在会议后丰富人物页面。下次提到这个人时，智能体已经拥有上下文。你永远不会从零开始。缺乏这个循环的智能体会回答陈旧上下文；拥有它的智能体会在每次对话中变得更聪明。这种差异每天累积。
## 语音：“她”开箱即用
语音集成是展示个人大脑为何重要的最强例证。
拨打一个电话号码。你的 AI 接听。它知道是谁在呼叫，从数千个人物页面中提取完整上下文，参考你上次的会议，并像真正了解你的世界的人那样回应。通话结束后，会生成一个结构化的智能体页面，包含转录、实体检测和交叉引用。
这不是演示。它使用真实电话号码运行，屏蔽未知来电，并且每次通话都会变得更聪明。你的智能体可以自行命名和设定个性。WebRTC 在浏览器标签页中零配置运行。真实电话号码是可选的。
# any Postgres with pgvector
```
导入是幂等的。重新运行会跳过未更改的文件（SHA-256 内容哈希）。约 30 秒导入 7,000 个文本文件，约 10-15 分钟用于嵌入。
## 文件存储与迁移
大脑仓库会积累二进制文件：图片、PDF、音频记录、原始 API 响应。包含 3,000 个 Markdown 页面的仓库可能有 2GB 二进制文件，使 `git clone` 变得痛苦。
GBrain 具有三阶段迁移生命周期，在保留所有引用的同时将二进制文件移至云存储：
```
Local files in git repo
│
▼ gbrain files mirror
Cloud copy exists, local files untouched
│
▼ gbrain files redirect
Local files replaced with .redirect breadcrumbs (tiny YAML pointers)
│
▼ gbrain files clean
Breadcrumbs removed, cloud is the only copy
```
每个阶段在执行 `clean` 前均可逆：
```
# 阶段 1：复制到云端（git 仓库保持不变）
gbrain files mirror ~/git/brain/attachments/ --dry-run # preview first
gbrain files mirror ~/git/brain/attachments/
# 阶段 2：用面包屑替换本地文件
gbrain files redirect ~/git/brain/attachments/ --dry-run
gbrain files redirect ~/git/brain/attachments/
# 您的 git 仓库从 2GB 降至 50MB
# 撤销：从云端重新下载所有内容
gbrain files restore ~/git/brain/attachments/
# 阶段 3：移除面包屑（不可逆，云端是唯一副本）
gbrain files clean ~/git/brain/attachments/ --yes
```
**存储后端：** S3 兼容（AWS S3、Cloudflare R2、MinIO）、Supabase Storage 或本地文件系统。在 `gbrain init` 期间配置。
附加文件命令：
```
gbrain files list [slug] # list files for a page (or all)
gbrain files upload --page # upload file linked to page
gbrain files sync # bulk upload directory
gbrain files verify # verify all uploads match local
gbrain files status # show migration status of directories
gbrain files unmirror # remove mirror marker (files stay in cloud)
```
文件解析器（`src/core/file-resolver.ts`）自动处理回退：如果本地文件缺失，会检查 `.redirect` 面包屑，然后是 `.supabase` 标记，并解析为云 URL。引用文件路径的代码在迁移后仍能正常工作。
## 知识模型
每个大脑页面遵循 **编译真相 + 时间线** 模式：
```
---
type: concept
title: Do Things That Don't Scale
tags: [startups, growth, pg-essay]
---
Paul Graham's argument that startups should do unscalable things early on.
The most common: recruiting users manually, one at a time. Airbnb went
door to door in New York photographing apartments. Stripe manually
installed their payment integration for early users.
The key insight: the unscalable effort teaches you what users actually
want, which you can't learn any other way.
---
- 2013-07-01: Published on paulgraham.com
- 2024-11-15: Referenced in batch W25 kickoff talk
- 2025-02-20: Cited in discussion about AI agent onboarding strategies
```
`---` 分隔符之上：**编译真相**。你当前最佳的理解。当新证据改变图景时会重写。下方：**时间线**。仅追加的证据线索，永不编辑，只添加。
编译真相是答案，时间线是证明。
## 搜索如何工作
```
Query: "when should you ignore conventional wisdom?"
|
Multi-query expansion (Claude Haiku)
"contrarian thinking startups", "going against the crowd"
|
+----+----+
| |
Vector Keyword
(HNSW (tsvector +
cosine) ts_rank)
| |
+----+----+
|
RRF Fusion: score = sum(1/(60 + rank))
|
4-Layer Dedup
1. Best chunk per page
2. Cosine similarity > 0.85
3. Type diversity (60% cap)
4. Per-page chunk cap
|
Stale alerts (compiled truth older than latest timeline)
|
Results
```
仅靠关键词搜索会遗漏概念匹配。“无视传统智慧”找不到标题为“天才的公交票理论”的文章，即使它完全相关。仅靠向量搜索会在嵌入被周围文本稀释时遗漏精确短语。RRF 融合确保两者都正确。多查询扩展捕捉你未想到的表述。
## 数据库架构
Postgres + pgvector 中有 10 张表：
```
pages The core content table
slug (UNIQUE) e.g. "concepts/do-things-that-dont-scale"
type person, company, deal, yc, civic, project, concept, source, media
title, compiled_truth, timeline
frontmatter (JSONB) Arbitrary metadata
search_vector Trigger-based tsvector (title + compiled_truth + timeline + timeline_entries)
content_hash SHA-256 for import idempotency
content_chunks Chunked content with embeddings
page_id (FK) Links to pages
chunk_text The chunk content
chunk_source 'compiled_truth' or 'timeline'
embedding (vector) 1536-dim from text-embedding-3-large
HNSW index Cosine similarity search
links Cross-references between pages
from_page_id, to_page_id
link_type knows, invested_in, works_at, founded, references, etc.
tags page_id + tag (many-to-many)
timeline_entries Structured timeline events
page_id, date, source, summary, detail (markdown)
page_versions Snapshot history for compiled_truth
compiled_truth, frontmatter, snapshot_at
raw_data Sidecar JSON from external APIs
page_id, source, data (JSONB)
files Binary attachments in Supabase Storage
page_slug (FK) Links to pages (ON UPDATE CASCADE)
storage_path, content_hash, mime_type, metadata (JSONB)
ingest_log Audit trail of import/ingest operations
config Brain-level settings (embedding model, chunk strategy, sync state)
```
索引：B-tree 在 slug/type 上，GIN 在 frontmatter/search_vector 上，HNSW 在嵌入上，pg_trgm 在 title 上用于模糊 slug 解析。
## 分块
三种策略，按内容类型分发：
- **递归**（时间线、批量导入）：5 级分隔符层级（段落、行、句子、子句、单词）。300 字块，带 50 字句子级重叠。快速、可预测、无损。
- **语义**（编译真相）：嵌入每个句子，计算相邻余弦相似度，应用 Savitzky-Golay 平滑寻找主题边界。失败时回退到递归。最高质量用于智能评估。
- **LLM 引导**（高价值内容，按需）：预分割为 128 字候选，让 Claude Haiku 识别滑动窗口中的主题转移。3 次重试每个窗口。最昂贵，但结果最佳。
## 命令
```
SETUP
gbrain init [--supabase|--url ] Create brain (PGLite default, or Supabase)
gbrain migrate --to supabase|pglite Migrate between engines (bidirectional)
gbrain upgrade Self-update
PAGES
gbrain get Read a page (supports fuzzy slug matching)
gbrain put [< file.md] Write/update a page (auto-versions)
gbrain delete Delete a page
gbrain list [--type T] [--tag T] [-n N] List pages with filters
SEARCH
gbrain search Keyword search (tsvector)
gbrain query Hybrid search (vector + keyword + RRF + expansion)
IMPORT/EXPORT
gbrain import [--no-embed] Import markdown directory (idempotent)
gbrain sync [--repo ] [flags] Git-to-brain incremental sync
gbrain export [--dir ./out/] Export to markdown (round-trip)
FILES
gbrain files list [slug] List stored files
gbrain files upload --page Upload file to storage
gbrain files sync Bulk upload directory
gbrain files verify Verify all uploads
EMBEDDINGS
gbrain embed [|--all|--stale] Generate/refresh embeddings
LINKS + GRAPH
gbrain link [--type T] Create typed link
gbrain unlink Remove link
gbrain backlinks Incoming links
gbrain graph [--depth N] Traverse link graph (recursive CTE, default depth 5)
TAGS
gbrain tags List tags
gbrain tag Add tag
gbrain untag Remove tag
TIMELINE
gbrain timeline [] View timeline entries
gbrain timeline-add Add timeline entry
ADMIN
gbrain doctor [--json] Health checks (pgvector, RLS, schema, embeddings)
gbrain stats Brain statistics
gbrain health Health dashboard (embed coverage, stale, orphans)
gbrain history Page version history
gbrain revert Revert to previous version
gbrain config [get|set] [value] Brain config
gbrain serve MCP server (stdio, local)
gbrain upgrade Self-update with feature discovery
bun run src/commands/auth.ts Token management (create/list/revoke/test)
gbrain call '' Raw tool invocation
gbrain --tools-json Tool discovery (JSON)
```
## 库与 MCP
参见上方 [GBrain without OpenClaw](#gbrain-without-openclaw) 获取库使用示例、MCP 服务器配置和技能文件加载。
`BrainEngine` 接口是可插拔的。参见 `docs/ENGINES.md` 了解如何添加后端。30 个 MCP 工具从合同优先的 `operations.ts` 生成。Parity 测试验证 CLI、MCP 和 tools-json 之间的结构一致性。
## 技能
厚重的 Markdown 文件告诉 AI 智能体 **如何** 使用 gbrain。核心逻辑不在二进制中。
| 技能 | 功能 |
|------|---------|
| **ingest** | 摄取会议、文档、文章。更新编译真相（重写而非追加），追加时间线，创建跨所有提及实体的交叉引用链接。 |
| **query** | 三层搜索（关键词 + 向量 + 结构化）带合成与引用。说“大脑没有 X 的信息”而不是编造。 |
| **maintain** | 定期健康检查：发现矛盾、过时编译真相、孤立页面、死链接、标签不一致、缺少嵌入、过期线程。 |
| **enrich** | 从外部 API 丰富页面。原始数据单独存储，提炼亮点存入编译真相。 |
| **briefing** | 每日简报：今日会议与参与者上下文、活动交易与截止日期、时效线程、最近更改。 |
| **migrate** | 从 Obsidian（维基链接转 gbrain 链接）、Notion（剥离 UUID）、Logseq（块引用）、纯 Markdown、CSV、JSON、Roam 的通用迁移。 |
| **setup** | 从头设置 GBrain：自动配置 Supabase 通过 CLI、AGENTS.md 注入、导入、同步。目标 TTHW < 2 分钟。 |
## 引擎架构
```
CLI / MCP Server
(thin wrappers, identical operations)
|
BrainEngine interface
(pluggable backend)
|
engine-factory.ts
(dynamic imports)
|
+--------+--------+
| |
PGLiteEngine PostgresEngine
(ships v0.7) (ships v0)
| |
~/.gbrain/brain.pglite Supabase Pro ($25/mo)
embedded PG 17.5 Postgres + pgvector + pg_trgm
via @electric-sql connection pooling via Supavisor
/pglite
gbrain migrate --to supabase/pglite
(bidirectional migration)
```
嵌入、分块和搜索融合是引擎无关的。只有原始关键词搜索（`searchKeyword`）和原始向量搜索（`searchVector`）是引擎相关的。RRF 融合、多查询扩展和 4 层去重运行在引擎之上的 `SearchResult[]` 数组上。两个引擎使用相同的 SQL（PGLite 运行真实 Postgres，而非独立方言）。
## 存储估算
对于约 7,500 页的大脑：
| 组件 | 大小 |
|------|------|
| 页面文本（compiled_truth + timeline） | ~150MB |
| JSONB frontmatter + 索引 | ~70MB |
| 内容分块（约 22K，文本） | ~80MB |
| 嵌入（22K × 1536 浮点数） | ~134MB |
| HNSW 索引开销 | ~270MB |
| 链接、标签、时间线、版本 | ~50MB |
| **总计** | **~750MB** |
Supabase 免费层（500MB）无法容纳大型大脑。Supabase 专业版（每月 25 美元，8GB）是起点。
初始嵌入成本：约 4-5 美元获取 7,500 页，使用 OpenAI text-embedding-3-large。
## 文档
**对于智能体：**
- **[GBRAIN_SKILLPACK.md](docs/GBRAIN_SKILLPACK.md)** —— **从这里开始。** 所有模式、技能与集成的索引
- [个人指南](docs/guides/) —— 17 份独立指南，从技能包中拆分
- [获取数据](docs/integrations/README.md) —— 集成食谱、凭证设置、数据流模式
- [GBRAIN_VERIFY.md](docs/GBRAIN_VERIFY.md) —— 安装验证运行手册
**对于人类：**
- [GBRAIN_RECOMMENDED_SCHEMA.md](docs/GBRAIN_RECOMMENDED_SCHEMA.md) —— 大脑仓库目录结构
- [基础设施层](docs/architecture/infra-layer.md) —— 导入、分块、嵌入和搜索的工作原理
- [薄外壳，厚技能](docs/ethos/THIN_HARNESS_FAT_SKILLS.md) —— 架构哲学
- [个人 AI 的 Homebrew](docs/ethos/MARKDOWN_SKILLS_AS_RECIPES.md) —— 为何 Markdown 即代码
**参考：**
- [GBRAIN_V0.md](docs/GBRAIN_V0.md) —— 完整产品规格，所有架构决策
- [ENGINES.md](docs/ENGINES.md) —— 可插拔引擎接口：PGLite（默认）+ Postgres，功能矩阵，迁移
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。运行 `bun test` 执行单元测试。端到端测试
针对真实 Postgres+pgvector：`docker compose -f docker-compose.test.yml up -d` 然后
`DATABASE_URL=postgresql://postgres:postgres@localhost:5434/gbrain_test bun run test:e2e`。
欢迎 PR：
- 新的增强 API 集成
- 性能优化
- 用于自托管 Postgres 的 Docker Compose
- 额外的引擎后端（DuckDB、Turso 等）
## 许可证
MIT
标签：AI智能体, API集成, Bun, DLL 劫持, GBrain, Git, Hermes Agent, OpenClaw, PGLite, Railway, Render, Ruby, SEO, 会议记录, 可观测性, 向量检索, 大语言模型, 威胁情报, 安全可观测性, 开发者工具, 想法记录, 持久化存储, 搜索, 日程同步, 智能助手, 版本控制, 知识库, 网络调试, 自动化, 自动化攻击, 语音通话, 邮件管理, 部署工具