内容
# OpenBrain
适用于 Apple Silicon 的全本地 AI 内存。 为任何 MCP 客户端提供持久的语义内存和向量搜索功能，无需云 API 支持。
所有操作均在您的 Mac 上运行：通过 Metal GPU 上的 MLX 进行嵌入，通过本地 LLM 进行丰富，存储在 PostgreSQL 中，并使用 pgvector。
基于 [OB1](https://github.com/NateBJones-Projects/OB1) 架构，由 [@NateBJones-Projects](https://github.com/NateBJones-Projects) 构建。
## 架构
Bun MCP 服务器代理来自任何 MCP 客户端的请求到 PostgreSQL+pgvector 进行存储，本地 MLX 嵌入服务进行向量化，本地 mlx-lm 服务器进行丰富。Redis 缓存嵌入和搜索结果。单独的 Bun Web UI 直接从 PostgreSQL 读取数据。所有操作均在设备上运行，数据路径中无需云 API。
## 要求
- **Apple Silicon Mac** (M1/M2/M3/M4) — MLX GPU 推理所需
- **16 GB RAM 最低** 默认模型（`Qwen3-8B-4bit`，约 4.5 GB）；32 GB+ 可运行更大的丰富模型
- macOS 14+
- [Node.js](https://nodejs.org) 22+（推荐 LTS v24）和 [pnpm](https://pnpm.io) 11+
- [Bun](https://bun.sh) 1.1+ 作为运行时（我们使用 `pnpm` 安装依赖；`bun` 运行它们）
- Python 3.13+，使用 [uv](https://docs.astral.sh/uv/)
- [PostgreSQL 17](https://www.postgresql.org/)，带有 [pgvector](https://github.com/pgvector/pgvector) 扩展
- [Redis](https://redis.io/)（可选但推荐）
- [Firecrawl](https://firecrawl.dev) API 密钥 — 用于所有网页抓取
- [yt-dlp](https://github.com/yt-dlp/yt-dlp)（可选 — YouTube 转录提取）
### Firecrawl
[Firecrawl](https://firecrawl.dev) 处理所有网页抓取（markdown 提取、JS 渲染等）。它是一个云服务；在 `.env` 中设置您的密钥：
```
FIRECRAWL_API_KEY=fc-...
```
没有密钥，`POST /api/ingest` 对于网页 URL 将返回错误。
### 快速安装（推荐）
```bash
bash installer/bootstrap.sh
```
这运行完整的链条：先决条件（Homebrew 软件包、Bun、Python 虚拟环境与 `mlx-lm`）、数据库设置、模式和 launchd 服务。幂等 — 安全地重新运行。
### 手动安装
如果您更愿意自己安装先决条件：
```bash
# Homebrew 软件包
brew install postgresql@17 pgvector redis uv yt-dlp pnpm
brew services start postgresql@17
brew services start redis
# Node 22+ via nvm（如果您已经有一个，请跳过）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
. ~/.nvm/nvm.sh && nvm install --lts && nvm alias default 'lts/*'
# 可选，用于通过 agents/ 子系统的 Gmail 集成
brew install gogcli
# 通过其官方安装程序安装 Bun（无 Homebrew 公式）。我们使用 Bun 作为运行时
# （Bun.serve, Bun.spawn）但从不 `bun install` — 这样会遇到 macOS SIP/provenance 问题。
# pnpm 处理依赖。
curl -fsSL https://bun.sh/install | bash
```
安装 Bun 后，重启您的 shell（或 `source ~/.zshrc`），以便 `bun` 二进制文件在您的 `PATH` 上。
## 快速开始
```bash
# 1. 克隆并进入仓库
git clone https://github.com/sajennings79/apple-silicon-openbrain.git
cd apple-silicon-openbrain
# 2. 配置环境
cp .env.example .env
# 编辑 .env（如果需要，默认配置适用于本地设置）
# 3. 运行设置（创建数据库，安装 Bun + Python 依赖）
bash scripts/setup.sh
# 4. 为 LLM 丰富服务器创建 Python 虚拟环境
python3 -m venv ~/.mlx-venv
~/.mlx-venv/bin/pip install mlx-lm
# 5. 启动所有服务（作为 launchd 守护进程安装）
bash scripts/install-services.sh
# 6. 验证所有服务是否正在运行
bun run health
```
或手动启动服务：
```bash
bun run dev # MCP 服务器（端口 6277）
cd embed-service && uv run server.py # 嵌入服务（端口 6278）
~/.mlx-venv/bin/python -m mlx_lm.server \
--model mlx-community/Qwen3-8B-4bit \
--port 8000 --max-tokens 4096 # LLM 丰富（端口 8000）
bun run ui # Web UI（端口 6279）
```
## 首次运行：模型下载
模型在每个服务首次启动时从 Hugging Face Hub 拉取 — 无需单独的下载步骤。两个服务在下载完成之前都会阻塞启动，然后上线。
| 模型 | 大小 | 使用者 | 触发条件 |
|-------|------|---------|--------------|
| `mlx-community/Qwen3-Embedding-0.6B-4bit-DWQ` | ~400 MB | 嵌入服务（`:6278`） | FastAPI 启动 |
| `mlx-community/Qwen3-8B-4bit`（默认） | ~4.5 GB | LLM 丰富（`:8000`） | `mlx_lm.server` 启动 |
默认 LLM 适用于 16 GB RAM 系统。要用 RAM 换取质量，请在 `.env` 中覆盖 `LLM_MODEL`（以及 `~/Library/LaunchAgents/com.openbrain.llm.plist` 中的匹配 `--model` 参数）：
| RAM | 建议模型 | 磁盘 |
|-----|-----------------|------|
| 16 GB（默认） | `mlx-community/Qwen3-8B-4bit` | ~4.5 GB |
| 32 GB | `mlx-community/Qwen3.6-27B-4bit`（稠密）或 `mlx-community/Qwen3.6-35B-A3B-4bit`（MoE） | ~17 GB |
| 64 GB+ | `mlx-community/Qwen3.5-122B-A10B-4bit` | ~60 GB |
所有模型都是公共仓库 — 无需 Hugging Face 令牌。文件缓存到 `~/.cache/huggingface/hub/`，后续启动完全离线。
如果您安装了 launchd 服务，首次运行的下载会在后台静默进行。使用以下命令监视进度：
```bash
tail -f logs/embed.log # 嵌入模型（在快速连接上约 30 秒）
tail -f logs/llm.log # 默认 8B 模型在快速连接上约 2 分钟
```
`bun run health` 将在 LLM 服务的下载完成之前报告其已关闭。已中断的下载将在下一次启动时恢复。
## MCP 客户端配置
OpenBrain 暴露了 HTTP 和 stdio 两种 MCP 传输方式。根据客户端支持的方式配置您的客户端。
**HTTP 传输方式**（推荐 — 所有客户端共享一个服务器）：
```json
{
"mcpServers": {
"openbrain": {
"type": "http",
"url": "http://localhost:6277/mcp"
}
}
}
```
**stdio 传输方式**（适用于以子进程形式启动服务器的客户端）：
```json
{
"mcpServers": {
"openbrain": {
"type": "stdio",
"command": "bun",
"args": ["run", "/path/to/openbrain/src/stdio.ts"]
}
}
}
```
确切的配置文件位置取决于您的客户端（例如，项目根目录中的 `.mcp.json`，或主目录下的全局配置）。
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| **StoreMemory** | 存储文本并自动嵌入、LLM 丰富（摘要、标签、实体）和跨内存链接 |
| **SearchMemory** | 具有可选过滤器（类型、来源、标签、日期范围）的语义向量搜索 |
| **RecallMemory** | 通过 UUID 检索特定内存 |
| **ListMemories** | 带过滤器的分页列表 |
| **UpdateMemory** | 更新内容或元数据；重新嵌入和重新丰富内容时更改 |
| **DeleteMemory** | 通过 UUID 软删除内存 |
## 服务
| 服务 | 端口 | 目的 |
|---------|------|---------|
| MCP 服务器 | 6277 | MCP 协议 + URL 抓取 API |
| 嵌入服务 | 6278 | 本地 MLX 嵌入（Qwen3-Embedding-0.6B，1024 维） |
| LLM 服务器 | 8000 | 本地 MLX 丰富（默认 Qwen3-8B） |
| Web UI | 6279 | 浏览和搜索内存的仪表盘 |
| PostgreSQL | 5432 | 带有 pgvector 的内存存储 |
| Redis | 6379 | 嵌入 + 搜索结果缓存 |
## Web UI
`http://localhost:6279` 处的 Web UI 提供：
- 带有标签/来源/类型过滤器的内存搜索和浏览
- 统计信息的仪表盘（总内存，按来源，按类型）
- 每月直方图和 30 天火花线
- 新内存创建表单
- 标签管理
## URL 抓取
使用书签链接直接将网页和 YouTube 转录保存到内存中。
1. 在浏览器中打开 `scripts/bookmarklet.html`
2. 将书签链接拖到书签栏
3. 点击任意页面，将内容保存到 OpenBrain
**网页** 通过 [Firecrawl](https://firecrawl.dev) 抓取（markdown 提取，JS 渲染）。在 `.env` 中设置 `FIRECRAWL_API_KEY` — 没有它，网页抓取将出错。
**YouTube URL** 通过 `yt-dlp` 本地处理（安装：`brew install yt-dlp`）。转录被提取并与视频元数据一起存储。
## 渐进式设置
您不需要运行所有服务即可开始：
1. **最小**: PostgreSQL + 嵌入服务 + MCP 服务器 — 提供存储和搜索
2. **添加丰富**: 启动 mlx-lm 服务器 — 内存自动丰富摘要和标签
3. **添加缓存**: 启动 Redis — 更快的重复搜索和嵌入查找
4. **添加 UI**: 启动 Web UI — 直观地浏览和管理内存
5. **添加抓取**: 在 `.env` 中设置 `FIRECRAWL_API_KEY` 并安装书签链接 — 从浏览器保存网页内容。
要完全跳过丰富（例如，在设置过程中），请在 `.env` 中设置 `DISABLE_ENRICHMENT=true`。
## 来源（定期抓取）
OpenBrain 按计划将内容拉入内存。每个 **来源** 都是 `sources` 表中的一行，具有类型（`rss`、`mail` 或 `webpage`）、配置和间隔。
```bash
# 通过 REST API 创建 RSS 来源：
echo '{"kind":"rss","name":"HN","config":{"feedUrl":"https://news.ycombinator.com/rss"},"intervalSeconds":3600}' \
| curl -X POST http://localhost:6277/api/sources -H 'content-type: application/json' --data @-
# 同步：
curl -X POST http://localhost:6277/api/sources/<id>/sync
# 同步所有到期的：
curl -X POST http://localhost:6277/api/sources/poll-due
```
Mac 应用程序（第 3 阶段+）从每小时的计时器驱动 `poll-due`，并为来源的 CRUD 提供 UI。在此之前，直接与 REST API 对话。（计时器仅为心跳 — 每个来源的 `intervalSeconds` 决定了实际到期的时间。）
### 通过 `gog` 的邮件来源
要将 Gmail 拉入内存，请安装 [gogcli](https://github.com/steipete/gogcli) 并进行身份验证：
```bash
brew install gogcli
gog auth add you@gmail.com
```
然后创建 `mail` 来源：
```json
{
"kind": "mail",
"name": "个人 Gmail（最近一天）",
"config": {
"account": "you@gmail.com",
"query": "newer_than:1d -in:promotions -in:spam -in:trash",
"maxMessages": 25
},
"intervalSeconds": 900
}
```
**重要**: 由 launchd 管理的服务没有 TTY 来进行 `gog` 的密钥环密码提示。在 `.env` 中设置 `GOG_KEYRING_PASSWORD`（gitignored）为您的 gog 密钥环密码，然后重启 MCP 服务。没有这个，邮件同步将因 `"no TTY available for keyring file backend password prompt"` 而失败。
## 定期代理
OpenBrain 配备了一小套 **启动包**，即基于提示的代理，它们按计划运行，查询内存存储，调用本地 LLM，并将结果写回为新内存。所有这些都在本地进行 — 无需 API 密钥。
```bash
# 运行一个已发货的代理，查看输出：
bun run agents/run-agent.ts agents/prompts/newsletter-digest.md
# 或通过包装器：
agents/run-agent.sh newsletter-digest.md
```
已发货的提示位于 `agents/prompts/`。通过在您选择的目录中添加其他 `.md` 文件来创建您自己的文件（[Mac 应用程序](apps/mac/) 默认使用 `~/Developer/claude-cron/prompts/`）。参见 `agents/prompts/README.md` 了解格式。
## 通过 Tailscale 进行远程访问
从网络上的其他设备访问 OpenBrain：
```bash
# 通过 Tailscale HTTPS 暴露 MCP 服务器：
tailscale serve --bg --https=6443 http://localhost:6277
```
然后更新您的书签网址以使用 `https://your-machine.tail-xxxxx.ts.net:6443`，并在 `.env` 中设置 `AUTH_TOKEN` 以保护端点。
## 开发
```bash
bun run dev # 带有自动重载的 MCP 服务器
bun run ui # Web UI
bun run health # 检查所有服务健康状况
bun run db:generate # 从模式更改中生成 Drizzle 迁移
bun run db:migrate # 应用待处理迁移
# 重新丰富缺少摘要的内存
bun run scripts/enrich-backlog.ts
```
## 管理服务
```bash
# 安装为 launchd 守护进程（开机自动启动）
bash scripts/install-services.sh
# 卸载所有服务
bash scripts/uninstall-services.sh
# 重启单个服务
kill $(lsof -ti :6277) # KeepAlive 自动重启它
# 查看日志
tail -f logs/mcp.log
tail -f logs/embed.log
tail -f logs/llm.log
```
## 许可证
MIT
