内容
# 第二大脑
本地、可查询的知识库和笔记仓库，具备混合搜索和实体图层 — 可由任何 AI 编码代理或助手从任何对话中搜索。
[](LICENSE)
[](https://github.com/mshtawythug/second-brain/actions/workflows/eval.yml)
[](https://www.python.org/downloads/)
存储职业文档、面试准备、Krisp 转录、Slack 线程、Gmail 和作者的 Markdown 笔记在 Postgres + pgvector 中。任何代理都可以通过 `brain` CLI 或捆绑的 `brain-mcp` MCP 服务器访问所有内容 — 无需在每次聊天中重新粘贴上下文。
## Token 节省
查询 `brain` 返回一个排名的片段，而不是将整个线程和文件转储到代理的上下文中，因此查找成本是直接 MCP 或文件读取的一小部分：
| 来源 | 直接读取（MCP / `Read` 工具） | 通过 `brain`（搜索 + 可选 `show`） | 节省 |
|---|---|---|---|
| **Gmail 线程** | 15–50k（元数据 + 带有引用回复/标头的完整线程） | ~2–4k（片段 + 一个有针对性的 `brain show`） | **~5–15×** |
| **Krisp 转录** | 25–75k（搜索 + 跨候选人的完整转录） | ~6–16k（搜索 + 一个相关的转录） | **~4–10×** |
| **长 PDF / DOCX（30+ 页）** | 15–25k（读取整个文件） | ~1–9k（一个片段 + 有针对性的 `show`） | **~5–15×** |
Brain 存储预提取的、去掉引号的正文和混合排名 *在* 获取之前，因此只有匹配的段落才会进入上下文。参见 [完整的按来源分解](docs/configuration.md#token-economics)。
## 60 秒了解
安装 CLI，然后运行离线演示 — 一个用合成的 *Larkspur* 合规性语料库播种的 disposable Postgres。不需要 Ollama，不需要个人数据，不需要模型下载：
```bash
pipx install git+https://github.com/mshtawythug/second-brain.git@v0.2.0
# 或，使用 uv：
uv tool install git+https://github.com/mshtawythug/second-brain.git@v0.2.0
brain demo # 启动一个沙盒 Postgres，播种 22 个文档，运行一个英雄查询
```
示例输出：
```text
为演示 Postgres 配置端口 55433 …
播种合成 Larkspur 语料库（22 个文档，无 Ollama） …
已播种 22 个新文档（0 个已存在）。
brain demo · 'compliance horror stories'
┌──────────┬─────────────────────────────────────────────┬────────┬───────┬───────────────────────────────…
│ ID │ 标题 │ 来源 │ 分数 │ 片段
├──────────┼─────────────────────────────────────────────┼────────┼───────┼───────────────────────────────…
│ … │ 合规性恐怖故事 — 收集的战争故事 … │ manual │ … │ 我不想重复的合规恐怖故事列表 …
│ … │ … 4 个更多排名的命中（SOC 2 准备就绪同步，事件事后总结，#compliance 战争故事线程，…）
└──────────┴─────────────────────────────────────────────┴────────┴───────┴───────────────────────────────…
尝试以下操作：
brain demo query "SOC 2 证据请求"
brain demo query "PCI 范围蔓延"
brain demo query "vendor risk" --source gmail
brain demo query "GDPR 删除请求"
brain show <id> # 以完整形式阅读顶部命中（在您自己的大脑中）
brain demo teardown # 完成后删除沙盒
```
_(ID 和分数是每次运行的；播种的语料库及其排名是确定性的 — 顶部命中始终是“合规性恐怖故事”笔记。)_
`brain demo` 只需要 Docker；`brain demo teardown` 会销毁沙盒。
已经运行过演示？您已经安装了 `brain` — 直接跳转到 `brain setup --profile …`。
## 快速开始
完整安装 — `brain` CLI 加运行时（Postgres，可选 Ollama / 图表 / 维基）：
```bash
curl -fsSL https://raw.githubusercontent.com/mshtawythug/second-brain/v0.2.0/install.sh | bash
```
安装程序从 `v0.2.0` 标签安装 `brain`，然后运行 `brain setup` 以配置 `$BRAIN_HOME`，启动 Postgres 容器，并（可选）安装维基 + Claude Code 技能。根据 `--profile` 选择建立多少：
| 配置文件 | 搜索 | 核心以外所需的额外依赖 |
|---|---|---|
| `minimal` | 仅 FTS（`BRAIN_EMBEDDER=none`） | 无 — 仅核心（无 Ollama，无模型）。 |
| `standard` *(默认)* | 混合（FTS + 向量） | + Ollama + 一个 ~1 GB 嵌入模型 (`snowflake-arctic-embed2`)。 |
| `full` | 混合 + GraphRAG + 维基 | + Apache AGE 镜像，概念提取 LLM，Quartz/Caddy 维基，和（可选）通过 `--daemons` 启动的 launchd 守护进程。 |
```bash
brain setup --profile minimal # 仅 Docker，FTS 搜索 — 建立速度最快
brain setup --profile standard # 默认：本地混合搜索
brain setup --profile full --daemons
```
**先决条件（核心）：** Git，Python 3.11+，以及正在运行的 Docker（桌面版或引擎版） — Postgres + pgvector 数据库在端口 55432 上运行在容器中。
**可选额外功能** （仅当您想要的不仅仅是仅限 FTS 搜索时）：
- **[Ollama](https://ollama.com/)** — 本地、免费的嵌入 + LLM 丰富。 要将 `minimal`（仅限 FTS）的大脑升级为混合搜索：安装 Ollama，然后 `ollama pull snowflake-arctic-embed2`，在 `.env` 中设置 `BRAIN_EMBEDDER=arctic`，并运行 `brain init && brain reembed`。
- **Node.js 18+ 和 [Caddy](https://caddyserver.com/)** — 仅用于渲染的 [维基](docs/vault-and-wiki.md)。
- **`gws` CLI** — 仅用于 Gmail 导入和 Google 驱动的目录链接。
更喜欢自己驱动每一步，还是修改代码？参见 [从源代码安装（手动）](docs/configuration.md#installing-from-source-manual)。
## 核心用法
```bash
brain ingest ~/Documents/resume.pdf --tag career # 导入文件（TXT / MD / PDF / DOCX）
brain ingest-dir ~/Documents/career # 递归，根据内容哈希幂等
brain search "what did I tell my manager about the migration" # 混合 FTS + 向量搜索
brain show <id-prefix> # 完整文档正文（6+ 十六进制前缀）
brain list --source gmail --limit 20 # 按来源浏览
brain tag <id-prefix> +interview +career -old-tag # 添加（+名称）/ 删除（-名称）标签
```
在 `search` / `show` / `list` 中添加 `--json` 以获取机器可读的输出，并为 `search` 添加 `--fts-only` 以跳过嵌入调用。完整的命令界面 — Gmail 导入、丰富、 tacit-knowledge 引发、GraphRAG、主动性/合成命令和保险库创作 — 位于 [CLI 参考](docs/cli-reference.md)。
## Claude 集成
`brain` 和捆绑的 `brain-mcp` 服务器是无 harness 的 — 任何运行 shell 命令或使用 MCP 的代理都可以查询语料库。
**Claude Code** — 注册 MCP 服务器（或符号链接 [技能](docs/configuration.md#claude-code-consult-brain-skill))：
```bash
claude mcp add brain -- brain-mcp
```
**Claude Desktop** — 添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（用 `/Users/you` 替换您的主目录）：
```json
{
"mcpServers": {
"brain": {
"command": "/Users/you/workspace/second-brain/.venv/bin/brain-mcp",
"env": {
"DATABASE_URL": "postgresql://brain:brain@localhost:55432/second_brain",
"BRAIN_EMBEDDER": "arctic"
}
}
}
}
```
`uvx second-brain` 还启动 MCP 服务器。完整的演练（符号链接，烟雾测试，故障排除）：[docs/guides/claude-desktop-setup.md](docs/guides/claude-desktop-setup.md)。
## 工作原理
**混合搜索。** 每个文档都被分段，嵌入，并为 Postgres 全文搜索编制索引。查询运行两个分支 — 词汇 `tsvector` 排名和向量余弦相似性 — 并使用 [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf)（k=60）融合它们，然后应用最近性提升和元数据过滤器。词汇搜索单独会错过同义表达（“我对 X 说了什么”）；向量搜索单独会错过确切的名称（一位同事，一名前雇主）；RRF 在一个排名列表中获取两者，无需调整权重。设置 `BRAIN_EMBEDDER=none` 以获取仅限 FTS 的大脑，无嵌入依赖。
**GraphRAG。** 除了搜索之外，brain 还在语料库中构建一个实体图谱（[Apache AGE](https://age.apache.org/) 在同一个 Postgres 中），并通过该结构检索 — 通过遍历关系而不是匹配文本来回答“我在与 X 的对话中出现了哪些主题”或“哪些人群和主题主导我的笔记”等问题。它与普通的搜索一起运行，而不是取代它。参见 [docs/graphrag.md](docs/graphrag.md)。
## 文档
- [docs/](docs/README.md) — 完整文档索引
- [CLI 参考](docs/cli-reference.md) — 超出核心五个的每个命令
- [GraphRAG](docs/graphrag.md) — 实体图检索（主题，模式，连接）
- [保险库和维基](docs/vault-and-wiki.md) — 两层笔记保险库 + 可选的渲染维基
- [配置](docs/configuration.md) — 技术栈，调整旋钮，集成，嵌入后端，卸载
- [CONTRIBUTING.md](CONTRIBUTING.md) — 开发设置，代码库布局，运行测试
- [CHANGELOG.md](CHANGELOG.md) — 发布历史
- [LICENSE](LICENSE) — MIT
